Solicitar un certificado

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

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

Este documento está dirigido 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 dentro de su proyecto. Para obtener más información, consulta Públicos de la documentación de GDC 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 la organización de IAM 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 una CA que tenga habilitado el modo ACME

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

Recopila la URL del servidor de ACME de la AC desde 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: Es el nombre de la CA, que puede ser una CA raíz o secundaria.
  • USER_PROJECT_NAMESPACE: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.

Solicita un certificado con una CA que tenga inhabilitado el modo ACME

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

  • Crea un CertificateResource y, luego, incluye una CSR en el recurso.
  • Crea un CertificateResource con una clave privada generada de forma automática 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 agregarla a tu recurso.

    De manera opcional, puedes emitir el certificado con un conjunto preconfigurado de parámetros de X.509 ingresando 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 Es 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 para 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 los detalles relacionados con los conflictos, consulta Plantillas de certificados predefinidas.
    VALIDITY_START_TIME Es la hora a partir de la cual el certificado se considera válido. 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 inmediatamente después de su emisión.
    VALIDITY_END_TIME la hora en 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 su 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 sujeto 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 la preparación de la solicitud de certificado:

    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: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.
    • CERT_REQ_NAME es el nombre del recurso CertificateRequest.

    El resultado es similar a lo 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 Secret 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: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.
    • CERT_REQ_NAME es el nombre del recurso CertificateRequest.

    En el resultado, se 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. Completa los valores elegidos para el certificado.

    De manera opcional, puedes emitir el certificado con un conjunto preconfigurado de parámetros de X.509 ingresando 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 Es 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 organización que se usará en el certificado
    LOCALITY la localidad del certificado
    STATE Estado o provincia que se usará en el certificado
    COUNTRY el país del certificado
    DNS_NAMES una lista de dNSName subjectAltNames que se establecerán en el certificado
    IP_ADDRESS una lista de ipAddress subjectAltNames que se establecerán en el certificado
    RFC822_NAMES una lista de rfc822Name subjectAltNames que se establecerán en el certificado
    URIS una lista de uniformResourceIdentifier subjectAltNames que se establecerán 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 los detalles relacionados con los conflictos, consulta Plantillas de certificados predefinidas.
    VALIDITY_START_TIME Es la hora a partir de la cual el certificado se considera válido. 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 inmediatamente después de su emisión.
    VALIDITY_END_TIME la hora en 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 su 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 sujeto 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 la preparación de la solicitud de certificado:

    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: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.
    • CERT_REQ_NAME es el nombre del recurso CertificateRequest.

    El resultado es similar a lo 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 Secret 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: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.
    • CERT_REQ_NAME: Es el nombre del recurso CertificateRequest.

    En el resultado, se muestra el SECRET_NAME que contiene el certificado firmado:

    test-jwk-1

Enumera las 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: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.

A continuación, se muestra un ejemplo de comando 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

Borra un certificado

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

  1. Busca el nombre de la CertificateRequest que quieres borrar. Puedes crear una lista de solicitudes de certificados para 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: Es el nombre del espacio de nombres en el que reside el proyecto del usuario.
    • CERT_REQ_NAME: Es el nombre del recurso CertificateRequest.

Límites y limpieza de solicitudes de certificados

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

Cuota de solicitudes de certificados

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

A medida que la cantidad total de recursos de 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 solicitudes nuevas. Si intentas crear un CertificateRequest después de alcanzar la cuota, se rechazará la solicitud. Es posible 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 encuentras este error, es posible que debas borrar recursos CertificateRequest antiguos o innecesarios. Para ajustar la cuota, comunícate con un miembro del grupo de operadores de infraestructura de tu organización. Pueden anular la cuota siguiendo las instrucciones de la guía de solución de problemas PLATAUTH-G2102.

Limpieza automatizada

Puedes habilitar la limpieza automática para borrar los recursos de 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 tiempo que transcurre entre el vencimiento de un certificado y el momento en que se borra el 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 período de gracia siguiendo las instrucciones de la guía de operaciones PLATAUTH-G2103. La función permanecerá inhabilitada si no se establece el período de gracia o si se establece en cero.