Solicitar um certificado

Neste documento, descrevemos as etapas para solicitar um certificado usando o Certificate Authority Service (CAS).

Para estabelecer uma comunicação segura e confiável no Google Distributed Cloud (GDC) com isolamento físico, solicite um certificado com ou sem ACME ao 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 ciclos de vida de 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, é preciso pedir as permissões necessárias e preparar o ambiente.

Solicitar papéis do IAM

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

Preparar o ambiente

• Faça o download e instale a CLI gdcloud, caso ainda não tenha feito isso.

• Instale a CLI kubectl.

• Gere um arquivo kubeconfig para configurar o acesso ao kubectl.

Solicitar um certificado usando uma CA 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 ele estiver pronto.

Colete o URL do servidor ACME da CA 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 CA, que pode ser uma CA raiz ou subordinada.
• USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside

Solicitar um certificado usando a CA com o modo ACME desativado

Para criar uma solicitação de certificado com o modo ACME desativado, crie e aplique um recurso CertificateRequest à instância do Distributed Cloud com isolamento físico. 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 do 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, na sigla em inglês) e adicione-a ao recurso.

   Se quiser, você pode emitir 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 está localizado
   CA_NAME	o nome da AC, que pode ser uma AC raiz ou subordinada.
   CSR	a solicitação de assinatura de certificado para assinar usando a CA
   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 passa a ser 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 para usar 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 para o arquivo kubeconfig do servidor de API Management.

3. Verifique a prontidão da solicitação 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))'
   

   Substitua:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor de 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á o seguinte:

   {
     "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 de 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, você pode emitir 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 está localizado
   CA_NAME	o nome da AC, que pode ser uma AC raiz ou subordinada.
   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	organização que será usada no certificado
   LOCALITY	a localidade do certificado
   STATE	estado ou província a ser usado no certificado
   COUNTRY	o país do certificado
   DNS_NAMES	uma lista de dNSName subjectAltNames a serem definidos no certificado
   IP_ADDRESS	uma lista de ipAddress subjectAltNames a serem definidos no certificado
   RFC822_NAMES	uma lista de rfc822Name subjectAltNames a serem definidos no certificado
   URIS	uma lista de uniformResourceIdentifier subjectAltNames a serem definidos 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 passa a ser 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 para usar 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 para o arquivo kubeconfig do servidor de API Management.

3. Verifique a prontidão da solicitação 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))'
   

   Substitua:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o arquivo kubeconfig do servidor de 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á o seguinte:

   {
     "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 de 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 de API Management.
• USER_PROJECT_NAMESPACE: o nome do namespace em que o projeto do usuário reside

Veja um exemplo de comando que usa 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, exclua 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 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 de 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 impõe limites ao número de recursos personalizados CertificateRequest e oferece um recurso opcional de limpeza automatizada.

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 prejudicar o desempenho do CAS e do servidor de 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 resposta ao comando ao criar novas solicitações. Se você tentar criar um CertificateRequest depois que a cota for atingida, a solicitação será negada. Talvez você veja 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 CertificateRequest antigos ou desnecessários. 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 automática 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 tempo entre a expiração de um certificado e a exclusão do recurso CertificateRequest.

A limpeza automática 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 vai permanecer desativado se o período de carência não for definido ou for definido como zero.