Solicitar un certificado

En este documento, se describen los pasos para solicitar un certificado con Certificate Authority Service (CAS).

Para establecer la confianza y la comunicación segura en tu Google Distributed Cloud (GDC) aislado, solicita un certificado habilitado o inhabilitado para ACME de Certificate Authority Service.

Este documento está destinado a públicos dentro del grupo de operadores de aplicaciones, como desarrolladores de aplicaciones o científicos de datos, que administran los ciclos de vida de los certificados en sus proyectos. Para obtener más información, consulta Públicos de la documentación de Google Distributed Cloud aislado.

Antes de comenzar

Antes de solicitar un certificado, debes solicitar los permisos necesarios y preparar tu entorno.

Solicita roles de IAM

Para crear, ver y borrar solicitudes de certificados, comunícate con el administrador de IAM de tu organización para que te otorgue el rol de Solicitante de certificados del servicio de CA (certificate-authority-service-certificate-requester) en el espacio de nombres del proyecto de la autoridad certificadora.

Prepara el entorno

Solicita un certificado con la CA con el modo ACME habilitado

Si la autoridad certificadora está alojada en el modo ACME, genera la URL del servidor ACME en su estado después de que esté lista.

Recopila la URL del servidor ACME de la CA de tu entorno de Distributed Cloud:

kubectl get certificateauthorities CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -r '.status.acme.uri'

Reemplaza lo siguiente:

  • CA_NAME: el nombre de la CA, que puede ser una CA raíz o subordinada
  • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario

Solicita un certificado con la CA con el modo ACME inhabilitado

Para crear una solicitud de certificado con el modo ACME inhabilitado, debes crear y aplicar un recurso CertificateRequest a tu instancia aislada de Distributed Cloud. Hay dos formas de hacerlo:

  • Crea un CertificateResource y agrega una CSR en el recurso.
  • Crea un CertificateResource con una clave privada generada automáticamente por GDC y proporciona las configuraciones del certificado como valores personalizados.

Solicita un certificado con una CSR

  1. Crea un recurso CertificateRequest y guárdalo como un archivo YAML llamado cert-request.yaml. Usa tu clave privada para crear una solicitud de firma de certificado (CSR) y agrégala a tu recurso.

    De manera opcional, puedes emitir el certificado con un conjunto preconfigurado de parámetros X.509. Para ello, ingresa el nombre de la plantilla en el campo certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  csr: CSR
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Reemplaza las siguientes variables:

    Variable Descripción
    CERT_REQ_NAME el nombre del recurso CertificateRequest
    USER_PROJECT_NAMESPACE el nombre del espacio de nombres en el que reside el proyecto del usuario
    CA_NAME el nombre de la CA, que puede ser una CA raíz o subordinada
    CSR la solicitud de firma de certificado que se firmará con la CA
    SECRET_NAME el nombre del Secret de Kubernetes que contiene la clave privada y el certificado de la AC firmado

    Reemplaza las siguientes variables opcionales:

    Variable Descripción
    TEMPLATE_NAME el nombre de la plantilla de certificado predefinida que deseas usar. Para obtener una lista de las plantillas disponibles y detalles sobre los conflictos, consulta Plantillas de certificados predefinidas.
    VALIDITY_START_TIME la hora a partir de la cual se considera válido el certificado. Este valor debe tener el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2025-10-19T21:45:30Z). Si no se establece, el certificado es válido de inmediato después de la emisión.
    VALIDITY_END_TIME la hora en la que vence el certificado. Este valor debe tener el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2026-01-17T18:25:40Z). Si no se establece, el certificado vence 90 días después de la hora de inicio.
    SUBJECT_OVERRIDE un asunto personalizado para usar en el certificado emitido, que anula la información del asunto en la CSR. Proporciona este valor como el asunto X.509 sin procesar codificado en ASN.1 DER.

  2. Aplica el recurso personalizado a tu instancia de Distributed Cloud:

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Reemplaza MANAGEMENT_API_SERVER_KUBECONFIG por la ruta de acceso al archivo kubeconfig del servidor de la API de administración.

  3. Verifica que la solicitud de certificado esté lista:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Reemplaza lo siguiente:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta de acceso al archivo kubeconfig del servidor de la API de administración
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario
    • CERT_REQ_NAME el nombre del recurso CertificateRequest

    El resultado es similar a este:

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Obtén el nombre del secreto del certificado:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Reemplaza lo siguiente:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta de acceso al archivo kubeconfig del servidor de la API de administración
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario
    • CERT_REQ_NAME el nombre del recurso CertificateRequest

    El resultado muestra el SECRET_NAME que contiene el certificado firmado:

    test-jwk-1

Solicita un certificado con una clave generada automáticamente

  1. Crea un recurso CertificateRequest y guárdalo como un archivo YAML llamado cert-request.yaml. Propaga los valores elegidos para el certificado.

    De manera opcional, puedes emitir el certificado con un conjunto preconfigurado de parámetros X.509. Para ello, ingresa el nombre de la plantilla en el campo certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  certificateConfig:
    subjectConfig:
      commonName: COMMON_NAME
      organization: ORGANIZATION
      locality: LOCALITY
      state: STATE
      country: COUNTRY
      dnsNames:
      - DNS_NAMES
      ipAddresses:
      - IP_ADDRESSES
      rfc822Names:
      - RFC822NAMES
      uris:
      - URIS
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Reemplaza las siguientes variables:

    Variable Descripción
    CERT_REQ_NAME el nombre del recurso CertificateRequest
    USER_PROJECT_NAMESPACE el nombre del espacio de nombres en el que reside el proyecto del usuario
    CA_NAME el nombre de la CA, que puede ser una CA raíz o subordinada
    SECRET_NAME el nombre del Secret de Kubernetes que contiene la clave privada y el certificado de la AC firmado

    Reemplaza las siguientes variables opcionales. Debes incluir al menos uno de los campos del bloque spec.certificateConfig.subjectConfig del recurso CertificateRequest:

    Variable Descripción
    COMMON_NAME el nombre común del certificado
    ORGANIZATION la organización que se usará en el certificado
    LOCALITY la localidad del certificado
    STATE el estado o la provincia que se usará en el certificado
    COUNTRY el país del certificado
    DNS_NAMES una lista de dNSName subjectAltNames que se establecerá en el certificado
    IP_ADDRESS una lista de ipAddress subjectAltNames que se establecerá en el certificado
    RFC822_NAMES una lista de rfc822Name subjectAltNames que se establecerá en el certificado
    URIS una lista de uniformResourceIdentifier subjectAltNames que se establecerá en el certificado
    TEMPLATE_NAME el nombre de la plantilla de certificado predefinida que deseas usar. Para obtener una lista de las plantillas disponibles y detalles sobre los conflictos, consulta Plantillas de certificados predefinidas.
    VALIDITY_START_TIME la hora a partir de la cual se considera válido el certificado. Este valor debe tener el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2025-10-19T21:45:30Z). Si no se establece, el certificado es válido de inmediato después de la emisión.
    VALIDITY_END_TIME la hora en la que vence el certificado. Este valor debe tener el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2026-01-17T18:25:40Z). Si no se establece, el certificado vence 90 días después de la hora de inicio.
    SUBJECT_OVERRIDE un asunto personalizado para usar en el certificado emitido, que anula la información del asunto en la CSR. Proporciona este valor como el asunto X.509 sin procesar codificado en ASN.1 DER.

  2. Aplica el recurso personalizado a tu instancia de Distributed Cloud:

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Reemplaza MANAGEMENT_API_SERVER_KUBECONFIG por la ruta de acceso al archivo kubeconfig del servidor de la API de administración.

  3. Verifica que la solicitud de certificado esté lista:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Reemplaza lo siguiente:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta de acceso al archivo kubeconfig del servidor de la API de administración
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario
    • CERT_REQ_NAME el nombre del recurso CertificateRequest

    El resultado es similar a este:

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Obtén el nombre del secreto del certificado:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Reemplaza lo siguiente:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta de acceso al archivo kubeconfig del servidor de la API de administración
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

    El resultado muestra el SECRET_NAME que contiene el certificado firmado:

    test-jwk-1

Cómo enumerar solicitudes de certificados

Usa el parámetro certificaterequests para enumerar todos los recursos CertificateRequest:

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog

Reemplaza lo siguiente:

  • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta de acceso al archivo kubeconfig del servidor de la API de administración
  • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario

A continuación, se muestra un comando de ejemplo con el espacio de nombres agtest-project:

kubectl --kubeconfig /root/release/root-admin/root-admin-kubeconfig  -n agtest-project get certificaterequest.pki.security.gdc.goog

El resultado esperado es similar al siguiente:

NAME                                               READY   AGE
test-externalca-subca-cert-req-with-csr            True    17h
test-externalca-subca-cert-req-with-csr-override   True    17h

Cómo borrar un certificado

Para borrar un certificado, debes borrar el recurso personalizado CertificateRequest correspondiente. Con esta acción, se quita el recurso de la base de datos de CAS.

  1. Busca el nombre del CertificateRequest que deseas borrar. Puedes enumerar las solicitudes de certificados para ayudarte a encontrar el nombre.

  2. Borra el recurso CertificateRequest:

    kubectl --kubeconfig  MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE delete certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME

    Reemplaza lo siguiente:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta de acceso al archivo kubeconfig del servidor de la API de administración
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres en el que reside el proyecto del usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

Límites y limpieza de solicitudes de certificados

Para ayudar a mantener la estabilidad del sistema y evitar el uso elevado de recursos, CAS aplica límites a la cantidad de recursos personalizados CertificateRequest y ofrece una función opcional de limpieza automatizada.

Cuota de solicitud de certificado

CAS aplica una cuota a la cantidad de recursos personalizados CertificateRequest por organización, con un límite predeterminado de 5,000. Si se supera este límite, se puede degradar el rendimiento de CAS y del servidor de la API de administración.

A medida que la cantidad total de recursos CertificateRequest se acerca a la cuota (por ejemplo, al 80% y al 90% del límite), verás advertencias en el resultado del comando cuando crees solicitudes nuevas. Si intentas crear un CertificateRequest después de que se alcanza la cuota, se rechaza la solicitud. Podría aparecer un mensaje de error similar a este:

Error from server (Forbidden): error when creating "cert-request.yaml":
admission webhook "certificaterequests.pki.security.gdc.goog" denied the
request: the number of certificate requests has exceeded the per organization
limit of {LIMIT}. Please refer to the guide PLATAUTH-G2102 for troubleshooting
this issue

Si encuentras este error, es posible que debas borrar recursos antiguos o innecesarios CertificateRequest. Para ajustar la cuota, comunícate con un miembro del grupo de operadores de infraestructura de tu organización. Pueden anular la cuota si siguen las instrucciones del runbook PLATAUTH-G2102.

Limpieza automatizada

Puedes habilitar la limpieza automatizada para borrar los recursos CertificateRequest vencidos. Esta función ayuda a liberar recursos quitándolos después de un período de gracia configurable. El período de gracia define el período entre el vencimiento de un certificado y el momento en que se borra el recurso CertificateRequest.

La limpieza automatizada está inhabilitada de forma predeterminada. Un miembro del grupo de operadores de infraestructura de tu organización puede habilitar esta función y configurar el período de gracia si sigue las instrucciones del runbook PLATAUTH-G2103. La función permanece inhabilitada si el período de gracia no está establecido o se establece en cero.