Solicitar um certificado

Nesta página, descrevemos as etapas para solicitar um certificado usando o Certificate Authority Service (CAS).

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

Antes de começar

Antes de solicitar um certificado, verifique se você tem as permissões necessárias e um arquivo kubeconfig.

Permissões necessárias

Para receber as permissões necessárias para solicitar um certificado, peça ao 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). Para mais informações sobre os papéis, consulte Definições de papéis.

Receber o arquivo kubeconfig

Para executar comandos no servidor da API Management, faça o seguinte:

  1. Faça login e gere o arquivo kubeconfig do servidor da API Management, se você não tiver um.

  2. Use o caminho para o arquivo kubeconfig do servidor da API Management para substituir MANAGEMENT_API_SERVER_KUBECONFIG nestas instruções.

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.

    Opcionalmente, 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 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 para o 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. Receba 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.

    Opcionalmente, 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 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 usado 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 para o 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. Receba 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.