Solicitar um certificado

Este documento descreve as etapas para solicitar um certificado usando o serviço de autoridade certificadora (CAS, na sigla em inglês).

Para estabelecer confiança e comunicação segura no seu ambiente isolado do Google Distributed Cloud (GDC), solicite um certificado ativado ou desativado para ACME no Certificate Authority Service.

Este documento é destinado a públicos-alvo do grupo de operadores de aplicativos, como desenvolvedores de aplicativos ou cientistas de dados, que gerenciam os ciclos de vida dos certificados no projeto. Para mais informações, consulte Públicos-alvo da documentação do GDC com isolamento físico.

Antes de começar

Antes de solicitar um certificado, peça as permissões necessárias e prepare o ambiente.

Solicitar papéis do IAM

Para criar, visualizar e excluir solicitações de certificado, entre em contato com o administrador do IAM da organização para conceder a você o papel de Solicitante de certificado do serviço de AC (certificate-authority-service-certificate-requester) no namespace do projeto da autoridade certificadora.

Preparar o ambiente

Solicitar um certificado usando a AC com o modo ACME ativado

Se a autoridade certificadora estiver hospedada no modo ACME, ela vai gerar o URL do servidor ACME no status depois que estiver pronta.

Reúna o URL do servidor ACME da AC no ambiente do Distributed Cloud:

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

Substitua:

  • CA_NAME: o nome da AC, que pode ser raiz ou secundária
  • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside

Solicitar um certificado usando a AC com o modo ACME desativado

Para criar uma solicitação de certificado com o modo ACME desativado, é necessário criar e aplicar um recurso CertificateRequest à instância isolada do Distributed Cloud. Há duas maneiras de fazer isso:

  • Crie um CertificateResource e inclua uma CSR no recurso.
  • Crie um CertificateResource usando uma chave privada gerada automaticamente pelo GDC e forneça as configurações de certificado como valores personalizados.

Solicitar um certificado usando uma CSR

  1. Crie um recurso CertificateRequest e salve-o como um arquivo YAML chamado cert-request.yaml. Use sua chave privada para criar uma solicitação de assinatura de certificado (CSR) e adicione-a ao recurso.

    Se quiser, emita o certificado com um conjunto pré-configurado de parâmetros X.509 inserindo o nome do modelo no 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

    Substitua as seguintes variáveis:

    Variável Descrição
    CERT_REQ_NAME o nome do recurso CertificateRequest
    USER_PROJECT_NAMESPACE o nome do namespace em que o projeto do usuário reside
    CA_NAME o nome da AC, que pode ser raiz ou secundária
    CSR a solicitação de assinatura de certificado a ser assinada usando a AC
    SECRET_NAME o nome do Secret do Kubernetes que contém a chave privada e o certificado de CA assinado

    Substitua as seguintes variáveis opcionais:

    Variável Descrição
    TEMPLATE_NAME o nome do modelo de certificado predefinido que você quer usar. Para uma lista de modelos disponíveis e detalhes sobre conflitos, consulte Modelos de certificado predefinidos.
    VALIDITY_START_TIME o horário em que o certificado é considerado válido. Esse valor precisa estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2025-10-19T21:45:30Z). Se não for definido, o certificado será válido imediatamente após a emissão.
    VALIDITY_END_TIME o horário em que o certificado expira. Esse valor precisa estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2026-01-17T18:25:40Z). Se não for definido, o certificado vai expirar 90 dias após o horário de início.
    SUBJECT_OVERRIDE um assunto personalizado a ser usado no certificado emitido, substituindo as informações do assunto na CSR. Forneça esse valor como o assunto X.509 bruto codificado em ASN.1 DER.

  2. Aplique o recurso personalizado à instância do Distributed Cloud:

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

    Substitua MANAGEMENT_API_SERVER_KUBECONFIG pelo caminho do arquivo kubeconfig do servidor da API Management.

  3. Verifique se a solicitação de certificado está pronta:

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

    Substitua:

    • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor da API Management
    • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside
    • CERT_REQ_NAME: o nome do recurso CertificateRequest

    O resultado será assim:

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

  4. Consiga o nome do secret do 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'

    Substitua:

    • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor da API Management
    • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside
    • CERT_REQ_NAME: o nome do recurso CertificateRequest

    A saída mostra o SECRET_NAME que contém o certificado assinado:

    test-jwk-1

Solicitar um certificado usando uma chave gerada automaticamente

  1. Crie um recurso CertificateRequest e salve-o como um arquivo YAML chamado cert-request.yaml. Preencha os valores escolhidos para o certificado.

    Se quiser, emita o certificado com um conjunto pré-configurado de parâmetros X.509 inserindo o nome do modelo no 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

    Substitua as seguintes variáveis:

    Variável Descrição
    CERT_REQ_NAME o nome do recurso CertificateRequest
    USER_PROJECT_NAMESPACE o nome do namespace em que o projeto do usuário reside
    CA_NAME o nome da AC, que pode ser raiz ou secundária
    SECRET_NAME o nome do Secret do Kubernetes que contém a chave privada e o certificado de CA assinado

    Substitua as seguintes variáveis opcionais. É necessário incluir pelo menos um dos campos do bloco spec.certificateConfig.subjectConfig do recurso CertificateRequest:

    Variável Descrição
    COMMON_NAME o nome comum do certificado
    ORGANIZATION a organização a ser usada no certificado
    LOCALITY a localidade do certificado
    STATE o estado ou a província a ser usada no certificado
    COUNTRY o país do certificado
    DNS_NAMES uma lista de dNSName subjectAltNames a serem definidas no certificado
    IP_ADDRESS uma lista de ipAddress subjectAltNames a serem definidas no certificado
    RFC822_NAMES uma lista de rfc822Name subjectAltNames a serem definidas no certificado
    URIS uma lista de uniformResourceIdentifier subjectAltNames a serem definidas no certificado
    TEMPLATE_NAME o nome do modelo de certificado predefinido que você quer usar. Para uma lista de modelos disponíveis e detalhes sobre conflitos, consulte Modelos de certificado predefinidos.
    VALIDITY_START_TIME o horário em que o certificado é considerado válido. Esse valor precisa estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2025-10-19T21:45:30Z). Se não for definido, o certificado será válido imediatamente após a emissão.
    VALIDITY_END_TIME o horário em que o certificado expira. Esse valor precisa estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2026-01-17T18:25:40Z). Se não for definido, o certificado vai expirar 90 dias após o horário de início.
    SUBJECT_OVERRIDE um assunto personalizado a ser usado no certificado emitido, substituindo as informações do assunto na CSR. Forneça esse valor como o assunto X.509 bruto codificado em ASN.1 DER.

  2. Aplique o recurso personalizado à instância do Distributed Cloud:

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

    Substitua MANAGEMENT_API_SERVER_KUBECONFIG pelo caminho do arquivo kubeconfig do servidor da API Management.

  3. Verifique se a solicitação de certificado está pronta:

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

    Substitua:

    • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor da API Management
    • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside
    • CERT_REQ_NAME: o nome do recurso CertificateRequest

    O resultado será assim:

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

  4. Consiga o nome do secret do 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'

    Substitua:

    • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor da API Management
    • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside
    • CERT_REQ_NAME: o nome do recurso CertificateRequest

    A saída mostra o SECRET_NAME que contém o certificado assinado:

    test-jwk-1

Listar solicitações de certificado

Use o parâmetro certificaterequests para listar todos os recursos CertificateRequest:

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

Substitua:

  • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor da API Management
  • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside

Confira abaixo um exemplo de comando usando o namespace agtest-project:

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

A saída esperada terá esta aparência:

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

Excluir um certificado

Para excluir um certificado, é necessário excluir o recurso personalizado CertificateRequest correspondente. Essa ação remove o recurso do banco de dados do CAS.

  1. Encontre o nome do CertificateRequest que você quer excluir. É possível listar as solicitações de certificado para ajudar a encontrar o nome.

  2. Exclua o recurso CertificateRequest:

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

    Substitua:

    • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor da API Management
    • USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside
    • CERT_REQ_NAME: o nome do recurso CertificateRequest

Limites e limpeza de solicitações de certificado

Para ajudar a manter a estabilidade do sistema e evitar o uso excessivo de recursos, o CAS aplica limites ao número de recursos personalizados CertificateRequest e oferece um recurso de limpeza automatizada opcional.

Cota de solicitação de certificado

O CAS aplica uma cota ao número de recursos personalizados CertificateRequest por organização, com um limite padrão de 5.000. Exceder esse limite pode degradar o desempenho do CAS e do servidor da API Management.

À medida que o número total de recursos CertificateRequest se aproxima da cota (por exemplo, em 80% e 90% do limite), você verá avisos na saída do comando ao criar novas solicitações. Se você tentar criar um CertificateRequest após a cota ser atingida, a solicitação será negada. Você poderá receber uma mensagem de erro semelhante a esta:

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

Se você encontrar esse erro, talvez seja necessário excluir recursos antigos ou desnecessários CertificateRequest. Para ajustar a cota, entre em contato com um membro do grupo de operadores de infraestrutura da sua organização. Eles podem substituir a cota seguindo as instruções no runbook PLATAUTH-G2102.

Limpeza automatizada

É possível ativar a limpeza automatizada para excluir recursos CertificateRequest expirados. Esse recurso ajuda a liberar recursos removendo-os após um período de carência configurável. O período de carência define o período entre a expiração de um certificado e a exclusão do recurso CertificateRequest.

A limpeza automatizada fica desativada por padrão. Um membro do grupo de operadores de infraestrutura da sua organização pode ativar esse recurso e configurar o período de carência seguindo as instruções no runbook PLATAUTH-G2103. O recurso permanece desativado se o período de carência não for definido ou for definido como zero.