Solicitar un certificado

En este documento se describen los pasos para solicitar un certificado mediante el Servicio de Autoridades de Certificación (CAS).

Para establecer la confianza y proteger la comunicación en tu entorno aislado de Google Distributed Cloud (GDC), solicita un certificado habilitado o inhabilitado para ACME al Servicio de Autoridades de Certificación.

Este documento está dirigido a los miembros del grupo de operadores de aplicaciones, como los desarrolladores de aplicaciones o los científicos de datos, que gestionan los ciclos de vida de los certificados en sus proyectos. Para obtener más información, consulta el artículo Audiencias de la documentación de GDC en entornos aislados.

Antes de empezar

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

Solicitar roles de gestión de identidades y accesos

Para crear, ver y eliminar solicitudes de certificado, ponte en contacto con el administrador de gestión de identidades y accesos de tu organización para que te asigne el rol Solicitante de certificados del Servicio de Autoridades de Certificación (certificate-authority-service-certificate-requester) en el espacio de nombres del proyecto de la autoridad de certificación.

Prepara tu entorno

Solicitar un certificado mediante una autoridad de certificación con el modo ACME habilitado

Si la autoridad de certificación está alojada en el modo ACME, mostrará la URL del servidor ACME en su estado cuando esté lista.

Recopila la URL del servidor ACME de la autoridad de certificación de tu entorno de Distributed Cloud:

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

Haz los cambios siguientes:

  • CA_NAME: el nombre de la autoridad de certificación, que puede ser una autoridad de certificación raíz o una subautoridad de certificación
  • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario

Solicitar un certificado mediante una autoridad de certificación 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 modos de hacerlo:

  • Crea un CertificateResource e incluye 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.

Solicitar un certificado mediante 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 añádela a tu recurso.

    También puedes emitir el certificado con un conjunto preconfigurado de parámetros X.509 introduciendo 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

    Sustituye las siguientes variables:

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

    Sustituye las siguientes variables opcionales:

    Variable Descripción
    TEMPLATE_NAME el nombre de la plantilla de certificado predefinida que quieras usar. Para consultar una lista de las plantillas disponibles y obtener información sobre los conflictos, consulta el artículo Plantillas de certificado predefinidas.
    VALIDITY_START_TIME la hora a partir de la cual se considera válido el certificado. Este valor debe estar en el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2025-10-19T21:45:30Z). Si no se define, el certificado será válido inmediatamente después de su emisión.
    VALIDITY_END_TIME la hora en la que caduca el certificado. Este valor debe estar en el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2026-01-17T18:25:40Z). Si no se define, el certificado caducará 90 días después de su hora de inicio.
    SUBJECT_OVERRIDE un sujeto personalizado que se usará en el certificado emitido, que sustituirá la información del sujeto de la CSR. Proporciona este valor como el sujeto X.509 sin procesar codificado con 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

    Sustituye MANAGEMENT_API_SERVER_KUBECONFIG por la ruta al archivo kubeconfig del servidor de la API Management.

  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))'

    Haz los cambios siguientes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta al archivo kubeconfig del servidor de la API Management
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

    El resultado debería ser similar al siguiente:

    {
  "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'

    Haz los cambios siguientes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta al archivo kubeconfig del servidor de la API Management
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

    El resultado muestra el SECRET_NAME que contiene el certificado firmado:

    test-jwk-1

Solicitar un certificado mediante una clave generada automáticamente

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

    También puedes emitir el certificado con un conjunto preconfigurado de parámetros X.509 introduciendo 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

    Sustituye las siguientes variables:

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

    Sustituye 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 definirá en el certificado
    IP_ADDRESS una lista de ipAddress subjectAltNames que se definirá en el certificado
    RFC822_NAMES una lista de rfc822Name subjectAltNames que se definirá en el certificado
    URIS una lista de uniformResourceIdentifier subjectAltNames que se definirá en el certificado
    TEMPLATE_NAME el nombre de la plantilla de certificado predefinida que quieras usar. Para consultar una lista de las plantillas disponibles y obtener información sobre los conflictos, consulta el artículo Plantillas de certificado predefinidas.
    VALIDITY_START_TIME la hora a partir de la cual se considera válido el certificado. Este valor debe estar en el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2025-10-19T21:45:30Z). Si no se define, el certificado será válido inmediatamente después de su emisión.
    VALIDITY_END_TIME la hora en la que caduca el certificado. Este valor debe estar en el formato YYYY-MM-DDTHH:MM:SSZ (por ejemplo, 2026-01-17T18:25:40Z). Si no se define, el certificado caducará 90 días después de su hora de inicio.
    SUBJECT_OVERRIDE un sujeto personalizado que se usará en el certificado emitido, que sustituirá la información del sujeto de la CSR. Proporciona este valor como el sujeto X.509 sin procesar codificado con 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

    Sustituye MANAGEMENT_API_SERVER_KUBECONFIG por la ruta al archivo kubeconfig del servidor de la API Management.

  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))'

    Haz los cambios siguientes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta al archivo kubeconfig del servidor de la API Management
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

    El resultado debería ser similar al siguiente:

    {
  "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'

    Haz los cambios siguientes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta al archivo kubeconfig del servidor de la API Management
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

    El resultado muestra el SECRET_NAME que contiene el certificado firmado:

    test-jwk-1

Mostrar solicitudes de certificado

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

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

Haz los cambios siguientes:

  • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta al archivo kubeconfig del servidor de la API Management
  • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario

A continuación, se muestra un ejemplo de comando que usa 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 debería ser 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

Eliminar un certificado

Para eliminar un certificado, debes eliminar el recurso personalizado CertificateRequest correspondiente. Esta acción elimina el recurso de la base de datos del CAS.

  1. Busca el nombre del recurso CertificateRequest que quieras eliminar. Puedes mostrar las solicitudes de certificado para encontrar el nombre.

  2. Elimina el recurso CertificateRequest:

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

    Haz los cambios siguientes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: la ruta al archivo kubeconfig del servidor de la API Management
    • USER_PROJECT_NAMESPACE: el nombre del espacio de nombres donde reside el proyecto de usuario
    • CERT_REQ_NAME: el nombre del recurso CertificateRequest

Límites y limpieza de solicitudes de certificado

Para mantener la estabilidad del sistema y evitar un uso elevado de recursos, el CAS aplica límites al número de recursos personalizados CertificateRequest y ofrece una función de limpieza automática opcional.

Cuota de solicitudes de certificado

El CAS aplica una cuota al número de recursos personalizados CertificateRequest por organización, con un límite predeterminado de 5000. Si se supera este límite, el rendimiento del CAS y del servidor de la API Management puede verse reducido.

A medida que el número total de recursos CertificateRequest se acerque a la cuota (por ejemplo, al 80% y al 90% del límite), verás advertencias en el resultado del comando cuando crees nuevas solicitudes. Si intentas crear un recurso CertificateRequest una vez alcanzada la cuota, la solicitud se rechazará. Puede que veas un mensaje de error similar al siguiente:

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 te encuentras con este error, es posible que tengas que eliminar recursos antiguos o innecesarios CertificateRequest. Para ajustar la cuota, ponte en contacto con un miembro del grupo de operadores de infraestructura de tu organización. Puede anular la cuota siguiendo las instrucciones del runbook PLATAUTH-G2102.

Limpieza automática

Puedes habilitar la limpieza automática para eliminar los recursos CertificateRequest caducados. Esta función ayuda a liberar recursos eliminándolos después de un periodo de gracia configurable. El periodo de gracia define el tiempo que transcurre entre la caducidad de un certificado y la eliminación del recurso CertificateRequest.

La limpieza automática 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 periodo de gracia siguiendo las instrucciones del runbook PLATAUTH-G2103. La función permanecerá inhabilitada si no se define el periodo de gracia o si se define como cero.