Como usar certificados SSL gerenciados pelo Google

Nesta página, mostramos como usar objetos da Entrada para criar balanceadores de carga externos com certificados SSL gerenciados pelo Google. Esses certificados são os de validação de domínio (DV, na sigla em inglês) que o Google provisiona, renova e gerencia nos seus nomes de domínio. Eles não representam sua identidade individual ou da organização.

Para saber como criar certificados gerenciados pelo Google com o Google Cloud, consulte Certificados gerenciados pelo Google.

Os certificados SSL gerenciados pelo Google do GKE são compatíveis com clusters públicos e privados.

Versões da API

Configure certificados SSL gerenciados pelo Google usando um recurso personalizado ManagedCertificate, disponível em diferentes versões da API, dependendo da sua versão do cluster do Google Kubernetes Engine (GKE):

  • A API ManagedCertificate v1beta2 está disponível nas versões 1.15 e posteriores do GKE.
  • A API ManagedCertificate v1 está disponível nas versões 1.17.9-gke.6300 e posteriores do GKE.

No momento, os clusters do GKE são compatíveis com a API ManagedCertificate v1beta1, mas essa versão da API está obsoleta e será removida das versões futuras do GKE. Recomenda-se usar uma versão mais recente da API.

Como migrar entre versões da API

Os objetos ManagedCertificate são promovidos automaticamente para uma versão mais recente da API quando atualizados em um cluster compatível com a versão mais recente da API. Os recursos são atualizados periodicamente, por isso você não precisa fazer nada para migrá-los.

Como criar uma Entrada com um certificado gerenciado do Google

Para configurar um certificado SSL gerenciado do Google e associá-lo a uma Entrada, é necessário:

  • Crie um objeto ManagedCertificate no mesmo namespace que a Entrada.
  • Associe o objeto ManagedCertificate a uma Entrada adicionando a anotação networking.gke.io/managed-certificates à Entrada. Essa anotação é uma lista separada por vírgulas de objetos ManagedCertificate.

Limitações

Os certificados gerenciados pelo Google são menos flexíveis do que os certificados conseguidos e gerenciados por você. Os certificados gerenciados pelo Google aceitam até 100 domínios não curingas. Ao contrário dos certificados autogerenciados, os certificados gerenciados pelo Google não têm suporte para domínios curinga.

Se você precisar de certificados autogerenciados ou se já tiver certificados SSL que quiser configurar na Entrada, consulte Como configurar o HTTPS (TLS) entre o cliente e o balanceador de carga.

O número e o tipo de certificados compatíveis com uma Entrada são definidos pelos limites dos certificados SSL gerenciados pelo Google.

Não há suporte para atualizações em certificados gerenciados pelo Google. Para mais informações, consulte Como atualizar manualmente um certificado gerenciado pelo Google.

Pré-requisitos

  • É preciso ser proprietário do nome de domínio. O nome do domínio não pode ter mais de 63 caracteres. É preciso usar o Google Domains ou outro registrador.
  • O cluster precisa ter o complemento HttpLoadBalancing ativado.
  • Seu "kubernetes.io/ingress.class" precisa ser "gce".
  • Aplique recursos Ingress e ManagedCertificate no mesmo projeto e namespace.
  • Crie um endereço IP externo reservado (estático). Reservar um endereço IP estático garante que ele continue sendo seu, mesmo que você exclua a Entrada. Se você não reservar um endereço, ele poderá ser alterado, exigindo a reconfiguração dos seus registros DNS de domínio. Use a Google Cloud CLI ou o console para criar um endereço IP reservado.

    gcloud

    Para criar um endereço IP reservado, execute o comando a seguir:

    gcloud compute addresses create ADDRESS_NAME --global
    

    Substitua ADDRESS_NAME pelo nome do endereço IP reservado que você está criando.

    Para encontrar o endereço IP estático que você criou, execute o seguinte comando:

    gcloud compute addresses describe ADDRESS_NAME --global
    

    A saída será assim:

    address: 203.0.113.32
    ...
    

    Console

    Para criar um endereço IP reservado, siga estas etapas:

    1. Acesse a página Endereços IP externos no console.

      Acessar Endereços IP externos

    2. Especifique um nome para o endereço IP (por exemplo, example-ip-address).

    3. Especifique se você quer um endereço IPv4 ou IPv6.

    4. Selecione a opção Global para Tipo.

    5. Clique em Reservar. O endereço IP é listado na coluna Endereço externo.

    Config Connector

    Observação: esta etapa requer o Config Connector. Siga estas instruções para instalar o Config Connector no cluster.

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeAddress
    metadata:
      name: example-ip-address
    spec:
      location: global
    Para implantar esse manifesto, faça o download dele para sua máquina como compute-address.yaml e execute:

    kubectl apply -f compute-address.yaml
    

Como configurar um certificado gerenciado pelo Google

  1. Criar um objeto ManagedCertificate. Este recurso especifica o domínio do certificado SSL. Domínios com caracteres curinga sem suporte.

    O manifesto a seguir descreve um objeto ManagedCertificate. Salve o manifesto como managed-cert.yaml.

    apiVersion: networking.gke.io/v1
    kind: ManagedCertificate
    metadata:
      name: managed-cert
    spec:
      domains:
        - DOMAIN_NAME1
        - DOMAIN_NAME2
    

    Substitua:

    • DOMAIN_NAME1 e DOMAIN_NAME2: nomes de domínio que você tem. Por exemplo, example.com e www.example.com.
  2. Aplique o manifesto ao cluster:

    kubectl apply -f managed-cert.yaml
    
  3. Crie um Serviço do tipo NodePort para expor seu aplicativo na Internet.

    O manifesto a seguir descreve um serviço do tipo NodePort. Salve o manifesto como mc-service.yaml.

    apiVersion: v1
    kind: Service
    metadata:
      name: mc-service
    spec:
      selector:
        app: mc-service
      type: NodePort
      ports:
        - protocol: TCP
          port: 80
          targetPort: 8080
    
  4. Aplique o manifesto ao cluster:

    kubectl apply -f mc-service.yaml
    
  5. Crie um Ingress.

    O manifesto a seguir descreve uma entrada que usa o ManagedCertificate criado. Salve o manifesto com managed-cert-ingress.yaml.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: managed-cert-ingress
      annotations:
        kubernetes.io/ingress.global-static-ip-name: ADDRESS_NAME
        networking.gke.io/managed-certificates: managed-cert
        kubernetes.io/ingress.class: "gce"
    spec:
      defaultBackend:
        service:
          name: mc-service
          port:
            number: SERVICE_PORT
    

    Substitua:

    • ADDRESS_NAME: o nome do endereço IP reservado.
    • SERVICE_PORT: o valor de ports.port no manifesto do serviço.
  6. Aplique o manifesto ao cluster:

    kubectl apply -f managed-cert-ingress.yaml
    
  7. Consiga o endereço IP do balanceador de carga.

    kubectl get ingress
    

    A saída será assim:

    NAME              HOSTS     ADDRESS         PORTS     AGE
    example-ingress   *         203.0.113.32     80       54s
    

    O endereço IP do balanceador de carga está listado na coluna ADDRESS. Se você estiver usando um endereço IP estático reservado, ele será o endereço do balanceador de carga.

    Se o endereço não estiver listado, aguarde até que a Entrada conclua a configuração.

  8. Configure os registros DNS dos seus domínios apontando para o endereço IP do balanceador de carga. Se você usa o Cloud DNS, consulte Como gerenciar registros para mais detalhes.

  9. Aguarde a conclusão do provisionamento do certificado gerenciado pelo Google. Isso pode levar até 60 minutos. Verifique o status do certificado usando o seguinte comando:

    kubectl describe managedcertificate managed-cert
    

    A saída será assim:

    Name:         managed-cert
    Namespace:    default
    Labels:       <none>
    Annotations:  <none>
    API Version:  networking.gke.io/v1
    Kind:         ManagedCertificate
    (...)
    Spec:
     Domains:
       DOMAIN_NAME1
       DOMAIN_NAME2
    Status:
     CertificateStatus: Active
    (...)
    

    O valor do campo Status.CertificateStatus indica que o certificado é provisionado. Se Status.CertificateStatus não for Active, o certificado ainda não será provisionado.

  10. Acesse seus domínios usando o prefixo https:// para verificar se o SSL está funcionando. O navegador indica que a conexão é segura e é possível ver os detalhes do certificado.

Como migrar para certificados gerenciados pelo Google com base em certificados autogerenciados

Ao migrar uma Entrada, fazendo a transição de certificados SSL autogerenciados para certificados SSL gerenciados pelo Google, não exclua nenhum certificado SSL autogerenciado antes que os certificados SSL gerenciados pelo Google estejam ativos. Após o provisionamento bem-sucedido dos certificados SSL gerenciados pelo Google, eles ficarão automaticamente ativos. Depois que os certificados SSL gerenciados pelo Google estiverem ativos, será possível excluir os certificados SSL autogerenciados.

Use estas instruções para migrar de certificados autogerenciados para certificados SSL gerenciados pelo Google.

  1. Adicione um novo certificado gerenciado pelo Google ao Ingress, conforme descrito na seção Como configurar um certificado gerenciado pelo Google.
  2. Aguarde até que o status do recurso de certificado gerenciado pelo Google esteja Ativo. Use o comando a seguir para verificar o status do certificado:

    kubectl describe managedcertificate managed-cert
    
  3. Quando o status estiver Active, atualize a Entrada para remover as referências ao certificado autogerenciado.

Como remover um certificado gerenciado pelo Google

Para remover um certificado gerenciado pelo Google do cluster, é necessário excluir o objeto ManagedCertificate e remover a anotação da Entrada que se refere a ele.

  1. Exclua o objeto ManagedCertificate:

    kubectl delete -f managed-cert.yaml
    

    A saída será assim:

    managedcertificate.networking.gke.io "managed-cert" deleted
    
  2. Remova a anotação da Entrada:

    kubectl annotate ingress managed-cert-ingress networking.gke.io/managed-certificates-
    

    Observe o sinal de menos - no final do comando.

  3. Libere o endereço IP estático que você reservou para o balanceador de carga.

    Use a Google Cloud CLI, o console ou o Config Connector para liberar um endereço IP reservado.

    gcloud

    Use o seguinte comando para liberar o endereço IP reservado:

    gcloud compute addresses delete ADDRESS_NAME --global
    

    Substitua ADDRESS_NAME pelo nome do endereço IP.

    Console

    Para liberar o endereço IP reservado, siga estas etapas:

    1. Acesse a página Endereços IP externos no console.

      Acessar Endereços IP externos

    2. Marque a caixa de seleção ao lado do endereço IP que você quer liberar.

    3. Clique em Liberar endereço IP.

    Config Connector

    Observação: esta etapa requer o Config Connector. Siga estas instruções para instalar o Config Connector no cluster.

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeAddress
    metadata:
      name: example-ip-address
    spec:
      location: global

    Para implantar esse manifesto, faça o download dele para sua máquina como compute-address.yaml e execute:

    kubectl delete -f compute-address.yaml
    

Solução de problemas

Nesta seção, apresentamos informações sobre como resolver problemas com certificados gerenciados do Google.

Verifique eventos nos recursos ManagedCertificate e Entrada

Se você exceder o número de certificados permitidos, um evento com um motivo TooManyCertificates será adicionado ao ManagedCertificate. Verifique os eventos em um objeto ManagedCertificate usando o comando a seguir:

kubectl describe managedcertificate CERTIFICATE_NAME

Substitua CERTIFICATE_NAME pelo nome do ManagedCertificate.

Se você anexar um ManagedCertificate v1 inexistente a uma Entrada, um evento com um motivo MissingCertificate será adicionado à Entrada. Verifique os eventos em uma Entrada usando o seguinte comando:

kubectl describe ingress INGRESS_NAME

Substitua INGRESS_NAME pelo nome da sua Entrada.

Certificado gerenciado não provisionado quando o domínio resolve para endereços IP de vários balanceadores de carga

Quando o domínio estiver resolvido para endereços IP de vários balanceadores de carga (vários objetos de Entrada), crie um único objeto ManagedCertificate e anexe-o a todos os objetos de Entrada. Se, em vez disso, você criar muitos objetos ManagedCertificate e anexar cada um deles a uma Entrada separada, a autoridade de certificação talvez não consiga verificar a propriedade do domínio, e alguns dos certificados podem não ser provisionado. Para que a verificação seja bem-sucedida, o certificado precisa estar visível para todos os endereços IP onde seu domínio é resolvido.

Especificamente, quando seu domínio resolver para endereços IPv4 e IPv6 configurados com diferentes recursos de Entrada, crie um único recurso ManagedCertificate e anexe-o às duas entradas.

Comunicação interrompida entre certificados gerenciados do Google e a Entrada

Os certificados gerenciados se comunicam com a Entrada usando a anotaçãoingress.gcp.kubernetes.io/pre-shared-cert Essa comunicação poderá ser interrompida se você, por exemplo:

  • Execute um processo automatizado que limpa a anotação ingress.gcp.kubernetes.io/pre-shared-cert.
  • Armazene um snapshot da Entrada e depois exclua e restaure a Entrada a partir do snapshot. Enquanto isso, um recurso SslCertificate listado na anotação ingress.gcp.kubernetes.io/pre-shared-cert pode ter sido excluído. A entrada não funcionará se faltar algum certificado anexado a ele.

Se a comunicação entre certificados gerenciados do Google e a Entrada for interrompida, exclua o conteúdo da anotação ingress.gcp.kubernetes.io/pre-shared-cert e aguarde a reconciliação do sistema. Para evitar recorrência, verifique se a anotação não foi modificada ou excluída por engano.

Erros de validação ao criar um certificado gerenciado do Google

As definições de ManagedCertificate são validadas antes da criação do objeto ManagedCertificate. Se a validação falhar, o objeto ManagedCertificate não será criado e uma mensagem de erro será impressa. As diferentes mensagens de erro e suas causas são explicadas abaixo:

spec.domains in body should have at most 100 items

Seu manifesto ManagedCertificate lista mais de 100 domínios no campo spec.domains. Os certificados gerenciados do Google são compatíveis com até 100 domínios.

spec.domains in body should match '^(([a-zA-Z0-9]+|[a-zA-Z0-9][-a-zA-Z0-9]*[a-zA-Z0-9])\.)+[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]\.?$'

Você especificou um nome de domínio inválido ou um nome de domínio curinga no campo spec.domains. O objeto ManagedCertificate não tem suporte para domínios curinga (por exemplo, *.example.com).

spec.domains in body should be at most 63 chars long

Você especificou um nome de domínio longo demais. Certificados gerenciados do Google são compatíveis com nomes de domínio com, no máximo, 63 caracteres.

Como atualizar manualmente um certificado gerenciado pelo Google

Para atualizar manualmente o certificado de modo que o certificado do domínio antigo continue funcionando até que o novo seja provisionado, siga estas etapas:

  1. Crie um ManagedCertificate para o novo domínio.
  2. Adicione o nome do ManagedCertificate à anotação networking.gke.io/managed-certificates na entrada usando uma lista separada por vírgulas. Não remova o nome antigo do certificado.
  3. Aguarde até que o ManagedCertificate fique ativo.
  4. Desanexe o certificado antigo da Entrada e exclua-o.

Quando você cria um ManagedCertificate, o Google Cloud cria um certificado SSL gerenciado pelo Google. Não é possível atualizar o certificado. Se você atualizar o ManagedCertificate, o Google Cloud excluirá e recriará o certificado SSL gerenciado pelo Google.

A seguir