Peça um certificado

Este documento descreve os passos para pedir um certificado através do serviço de autoridade de certificação (CAS).

Para estabelecer confiança e proteger a comunicação no Google Distributed Cloud (GDC) air-gapped, peça um certificado com o ACME ativado ou desativado ao serviço de autoridade de certificação.

Este documento destina-se a públicos-alvo no grupo de operadores de aplicações, como programadores de aplicações ou cientistas de dados, que gerem os ciclos de vida dos certificados nos respetivos projetos. Para mais informações, consulte o artigo Públicos-alvo para a documentação do GDC air-gapped.

Antes de começar

Antes de poder pedir um certificado, tem de pedir as autorizações necessárias e preparar o seu ambiente.

Peça funções de IAM

Para criar, ver e eliminar pedidos de certificados, contacte o administrador de IAM da organização para lhe atribuir a função CA Service Certificate Requester (certificate-authority-service-certificate-requester) no espaço de nomes do projeto da autoridade de certificação.

Prepare o seu ambiente

• Transfira e instale a CLI gdcloud, se ainda não o tiver feito.

• Instale a CLI kubectl.

• Gere um ficheiro kubeconfig para configurar o acesso kubectl.

Peça um certificado através da CA com o modo ACME ativado

Se a autoridade de certificação estiver alojada no modo ACME, apresenta o URL do servidor ACME no respetivo estado depois de ficar pronta.

Recolha o URL do servidor ACME da CA no seu ambiente do Distributed Cloud:

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

Substitua o seguinte:

• CA_NAME: o nome da CA, que pode ser uma CA de raiz ou uma sub-CA
• USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador

Peça um certificado através da CA com o modo ACME desativado

Para criar um pedido de certificado com o modo ACME desativado, tem de criar e aplicar um recurso CertificateRequest à sua instância do Distributed Cloud air-gapped. Existem duas formas de o fazer:

• Crie um CertificateResource e inclua um CSR no recurso.
• Crie um CertificateResource através de uma chave privada gerada automaticamente pelo GDC e indique as configurações do certificado como valores personalizados.

Peça um certificado através de um CSR

1. Crie um recurso CertificateRequest e guarde-o como um ficheiro YAML com o nome cert-request.yaml. Use a sua chave privada para criar um pedido de assinatura de certificado (CSR) e adicione-o ao recurso.

   Opcionalmente, pode emitir o certificado com um conjunto pré-configurado de parâmetros X.509 introduzindo 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 espaço de nomes onde reside o projeto do utilizador
   CA_NAME	o nome da CA, que pode ser uma CA de raiz ou uma sub-CA
   CSR	o pedido de assinatura de certificado a assinar através da CA
   SECRET_NAME	o nome do segredo do Kubernetes que contém a chave privada e o certificado da CA assinado

   Substitua as seguintes variáveis opcionais:

   Variável	Descrição
   TEMPLATE_NAME	o nome do modelo de certificado predefinido que quer usar. Para ver uma lista dos modelos disponíveis e detalhes sobre conflitos, consulte o artigo Modelos de certificados predefinidos.
   VALIDITY_START_TIME	a hora a partir da qual o certificado é considerado válido. Este valor tem de estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2025-10-19T21:45:30Z). Se não for definido, o certificado é válido imediatamente após a emissão.
   VALIDITY_END_TIME	a hora em que o certificado expira. Este valor tem de estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2026-01-17T18:25:40Z). Se não for definido, o certificado expira 90 dias após a hora de início.
   SUBJECT_OVERRIDE	um assunto personalizado a usar no certificado emitido, substituindo as informações do assunto no CSR. Indique este valor como o assunto X.509 codificado em DER ASN.1 não processado.

2. Aplique o recurso personalizado à sua 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 ficheiro kubeconfig do servidor da API de gestão.

3. Valide a prontidão do pedido 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 o seguinte:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o ficheiro kubeconfig do servidor da API de gestão
   • USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador
   • CERT_REQ_NAME: o nome do recurso CertificateRequest

   O resultado é semelhante ao seguinte:

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

4. Obtenha o nome do segredo 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 o seguinte:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o ficheiro kubeconfig do servidor da API de gestão
   • USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador
   • CERT_REQ_NAME: o nome do recurso CertificateRequest

   O resultado mostra o SECRET_NAME que contém o certificado assinado:

   test-jwk-1
   

Peça um certificado através de uma chave gerada automaticamente

1. Crie um recurso CertificateRequest e guarde-o como um ficheiro YAML com o nome cert-request.yaml. Preencha os valores escolhidos para o certificado.

   Opcionalmente, pode emitir o certificado com um conjunto pré-configurado de parâmetros X.509 introduzindo 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 espaço de nomes onde reside o projeto do utilizador
   CA_NAME	o nome da CA, que pode ser uma CA de raiz ou uma sub-CA
   SECRET_NAME	o nome do segredo do Kubernetes que contém a chave privada e o certificado da CA assinado

   Substitua as seguintes variáveis opcionais. Tem de 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 usar no certificado
   LOCALITY	a localidade do certificado
   STATE	o estado ou a província a usar no certificado
   COUNTRY	o país do certificado
   DNS_NAMES	uma lista de dNSName subjectAltNames a definir no certificado
   IP_ADDRESS	uma lista de ipAddress subjectAltNames a definir no certificado
   RFC822_NAMES	uma lista de rfc822Name subjectAltNames a definir no certificado
   URIS	uma lista de uniformResourceIdentifier subjectAltNames a definir no certificado
   TEMPLATE_NAME	o nome do modelo de certificado predefinido que quer usar. Para ver uma lista dos modelos disponíveis e detalhes sobre conflitos, consulte o artigo Modelos de certificados predefinidos.
   VALIDITY_START_TIME	a hora a partir da qual o certificado é considerado válido. Este valor tem de estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2025-10-19T21:45:30Z). Se não for definido, o certificado é válido imediatamente após a emissão.
   VALIDITY_END_TIME	a hora em que o certificado expira. Este valor tem de estar no formato YYYY-MM-DDTHH:MM:SSZ (por exemplo, 2026-01-17T18:25:40Z). Se não for definido, o certificado expira 90 dias após a hora de início.
   SUBJECT_OVERRIDE	um assunto personalizado a usar no certificado emitido, substituindo as informações do assunto no CSR. Indique este valor como o assunto X.509 codificado em DER ASN.1 não processado.

2. Aplique o recurso personalizado à sua 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 ficheiro kubeconfig do servidor da API de gestão.

3. Valide a prontidão do pedido 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 o seguinte:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o ficheiro kubeconfig do servidor da API de gestão
   • USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador
   • CERT_REQ_NAME: o nome do recurso CertificateRequest

   O resultado é semelhante ao seguinte:

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

4. Obtenha o nome do segredo 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 o seguinte:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o ficheiro kubeconfig do servidor da API de gestão
   • USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador
   • CERT_REQ_NAME: o nome do recurso CertificateRequest

   O resultado mostra o SECRET_NAME que contém o certificado assinado:

   test-jwk-1
   

Liste os pedidos de certificados

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 o seguinte:

• MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o ficheiro kubeconfig do servidor da API de gestão
• USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador

Segue-se um exemplo de comando que usa o espaço de nomes agtest-project:

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

O resultado esperado é semelhante ao seguinte:

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

Elimine um certificado

Para eliminar um certificado, tem de eliminar o recurso personalizado CertificateRequest correspondente. Esta ação remove o recurso da base de dados do CAS.

1. Encontre o nome do CertificateRequest que quer eliminar. Pode listar os pedidos de certificados para ajudar a encontrar o nome.

2. Elimine o recurso CertificateRequest:

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

   Substitua o seguinte:

   • MANAGEMENT_API_SERVER_KUBECONFIG: o caminho para o ficheiro kubeconfig do servidor da API de gestão
   • USER_PROJECT_NAMESPACE: o nome do espaço de nomes onde reside o projeto do utilizador
   • CERT_REQ_NAME: o nome do recurso CertificateRequest

Limites e limpeza de pedidos de certificados

Para ajudar a manter a estabilidade do sistema e evitar uma utilização elevada de recursos, o CAS aplica limites ao número de recursos personalizados CertificateRequest e oferece uma funcionalidade de limpeza automática opcional.

Quota de pedidos de certificados

O CAS aplica uma quota ao número de recursos personalizados CertificateRequest por organização, com um limite predefinido de 5000. Exceder este limite pode prejudicar o desempenho do CAS e do servidor da API de gestão.

À medida que o número total de recursos CertificateRequest se aproxima da quota (por exemplo, a 80% e 90% do limite), são apresentados avisos no resultado do comando quando cria novos pedidos. Se tentar criar um CertificateRequest depois de a quota ser atingida, o pedido é recusado. Pode ver uma mensagem de erro semelhante à seguinte:

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 vir este erro, pode ter de eliminar recursos CertificateRequest antigos ou desnecessários. Para ajustar a quota, contacte um membro do grupo de operadores de infraestrutura na sua organização. Este pode substituir a quota seguindo as instruções no runbook PLATAUTH-G2102.

Limpeza automática

Pode ativar a limpeza automática para eliminar recursos CertificateRequest expirados. Esta funcionalidade ajuda a libertar recursos removendo-os após um período de tolerância configurável. O período de tolerância define o período entre a expiração de um certificado e a eliminação do recurso CertificateRequest.

A limpeza automática está desativada por predefinição. Um membro do grupo de operadores de infraestrutura na sua organização pode ativar esta funcionalidade e configurar o período de tolerância seguindo as instruções no runbook PLATAUTH-G2103. A funcionalidade permanece desativada se o período de tolerância não estiver definido ou estiver definido como zero.