Como usar certificados SSL gerenciados pelo Google

Nesta página, mostramos como usar as Entradas 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, consulte esta página.

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 GKE:

A API ManagedCertificate v1beta2 está disponível nas versões 1.15 e posteriores do cluster do GKE.
A API ManagedCertificate v1 está disponível nas versões 1.17.9-gke.6300 e posteriores do cluster 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 recursos 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

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

criar um objeto ManagedCertificate;
associar o objeto ManagedCertificate a uma Entrada adicionando uma anotação networking.gke.io/managed-certificates à Entrada. Essa anotação é uma lista separada por vírgulas de recursos ManagedCertificate, cert1,cert2,cert3, por exemplo.

Limitações

Os certificados gerenciados pelo Google são menos flexíveis do que os certificados conseguidos e gerenciados por você. Os certificados gerenciados aceitam até 100 domínios não curingas, enquanto certificados autogerenciados são compatíveis com curingas.

Se você precisar de certificados autogerenciados ou se já tiver certificados SSL que gostaria de configurar na Entrada, consulte a documentação da Entrada.

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

Não há suporte para atualizações em certificados gerenciados pelo Google.

Para alterações manuais com tempo de inatividade mínimo, siga as etapas da seção 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.
Seu "kubernetes.io/ingress.class" precisa ser "gce".
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 ferramenta de linha de comando gcloud ou o Console do Cloud 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
```
em que address-name é o 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 resposta é semelhante a:
```
address: 203.0.113.32
...
```
Console
1. Acesse a página Reservar um endereço estático, no Console do Cloud.
  Acessar a página "Reservar um endereço estático"
2. Especifique um nome para esse endereço IP (por exemplo, example-ip-address).
3. Especifique se o endereço é IPv4 ou IPv6. O exemplo a seguir usa um endereço IPv4.
4. Selecione a opção Global para o tipo de endereço.
5. Clique em Reservar para reservar o IP.
6. 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.

Ver no GitHub
```
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 o certificado gerenciado

Crie um recurso ManagedCertificate. Esse recurso especifica os domínios para os quais o certificado SSL será criado. Domínios com caracteres curinga não são compatíveis.

Este é um exemplo de manifesto ManagedCertificate:

Observação: se você executar um cluster em que a API ManagedCertificate v1 não está disponível, use a versão mais antiga da API, v1beta2.
```
apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
  name: certificate-name
spec:
  domains:
    - domain-name1
    - domain-name2
```
em que:
- certificate-name é o nome do recurso ManagedCertificate;
- domain-name1 e domain-name2 são seus nomes de domínio (por exemplo, example.com, mail.example.com e www.example.com).
Salve o manifesto como um arquivo chamado certificate-name.yaml e, em seguida, crie o recurso com o comando a seguir:
```
kubectl apply -f certificate-name.yaml
```
Observação: para que esse recurso ManagedCertificate se torne Active, ele precisa ser anexado a um recurso de entrada (consulte a etapa 3). Em outras palavras, ManagedCertificate não precisa ser Active para ser anexado a uma Entrada.
Crie um serviço NodePort para publicar o aplicativo na Internet.

Veja a seguir um exemplo de arquivo de manifesto do serviço:
```
apiVersion: v1
kind: Service
metadata:
  name: service-name
spec:
  selector:
    key: value
  type: NodePort
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
```
Este exemplo de especificação seleciona pods para incluir no serviço usando o selector. Consulte a documentação do NodePort para detalhes sobre como configurar o Serviço.

Salve o manifesto como um arquivo chamado service-name.yaml e, em seguida, crie o Serviço com o comando a seguir:
```
kubectl apply -f service-name.yaml
```
Crie uma Entrada e vincule-a ao ManagedCertificate criado anteriormente.

Veja a seguir um exemplo de manifesto de Entrada:
```
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-name
  annotations:
    kubernetes.io/ingress.global-static-ip-name: address-name
    networking.gke.io/managed-certificates: certificate-name
    kubernetes.io/ingress.class: "gce"
spec:
  backend:
    serviceName: service-name
    servicePort: service-port
```
em que:
- ingress-name é o nome do objeto de Entrada.
- address-name é o nome do endereço IP reservado.
- certificate-name é o nome do certificado.
- service-name é o nome do serviço que você criou na etapa anterior.
- service-port é a porta especificada no manifesto do serviço. Esse deve ser o valor do campo port, não targetPort.
Salve o manifesto como um arquivo chamado ingress-name.yaml e, em seguida, use o comando a seguir para criar a Entrada:
```
kubectl apply -f ingress-name.yaml
```
Observação: o balanceador de carga pode levar de 10 a 20 minutos para começar a funcionar.
Pesquise o endereço IP do balanceador de carga criado na etapa anterior. Use o seguinte comando para conseguir o endereço IP do balanceador de carga:
```
kubectl get ingress
```
A resposta é semelhante a:
```
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.
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 o guia Como gerenciar registros para mais detalhes.

Observação: antes de continuar, aguarde até que os registros DNS configurados sejam propagados.
Aguarde o provisionamento do certificado gerenciado. Isso pode levar até 15 minutos Verifique o status do certificado com o seguinte comando:
```
kubectl describe managedcertificate certificate-name
```
Depois que um certificado for provisionado com sucesso, o valor do campo Status.CertificateStatus será Active. O exemplo a seguir mostra que a saída de kubectl describe, depois da aprovação do certificado, é provisionada com êxito:
```
Name:         certificate-name
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  networking.gke.io/v1
Kind:         ManagedCertificate
(...)
Spec:
  Domains:
    domain-name1
    domain-name2
Status:
  CertificateStatus: Active
(...)
```
Acesse seus domínios usando o prefixo https:// para verificar se o SSL está funcionando. Seu navegador indicará que a conexão é segura e que é possível visualizar 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.

Adicione um novo certificado gerenciado à Entrada, conforme descrito na seção Como configurar o certificado gerenciado.
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 certificate-name
```
Quando o status estiver Ativo, atualize a Entrada para remover as referências ao certificado autogerenciado.

Como remover um certificado gerenciado

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

Exclua o recurso ManagedCertificate com kubectl:

kubectl delete -f certificate-name.yaml

A seguinte saída será exibida:

managedcertificate.networking.gke.io "certificate-name" deleted

Remova a anotação da Entrada:

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

Observe o sinal de menos (-) no final do comando.

Libere o endereço IP estático que você reservou para o balanceador de carga:
gcloud
Com a ferramenta de linha de comando gcloud:
```
gcloud compute addresses delete address-name --global
```
em que address-name é o nome do endereço IP.
Console
1. Acesse a página Endereços IP externos no Console do Cloud.
  Acessar a página "Endereços IP externos"
2. Marque a caixa ao lado do endereço IP a ser liberado.
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.

Ver no GitHub
```
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.

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 v1. Use o comando a seguir para verificar os eventos de um objeto ManagedCertificate:

kubectl describe managedcertificate certificate-name

em que:

certificate-name é o nome do objeto ManagedCertificate.

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

kubectl describe ingress ingress-name

em que:

ingress-name é o nome do objeto de 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 resolver para endereços IP de vários balanceadores de carga (várias entradas), crie um único recurso ManagedCertificate e anexe-o a todas as entradas. Se, em vez disso, você criar muitos recursos ManagedCertificate e anexar cada um deles a uma Entrada separada, a autoridade de certificação talvez não consiga verificar a propriedade do seu domínio e provisionar alguns dos seus certificados. 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 e a Entrada

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

executar um processo automatizado que limpa a anotação kubernetes.io/pre-shared-cert;
armazenar um snapshot da Entrada, desativá-lo e restaurar a Entrada do snapshot. Enquanto isso, um recurso SslCertificate listado na anotação pre-shared-cert da Entrada pode ter sido excluído. A Entrada tem semântica de tudo ou nada e não funcionará se faltar algum dos certificados anexados a ela.

Se a comunicação entre certificados gerenciados e a Entrada for interrompida, exclua o conteúdo da anotação 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

As definições do ManagedCertificate são validadas antes da criação do recurso ManagedCertificate. Se a validação falhar, o recurso 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 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 recurso ManagedCertificate não é compatível com domínios de caractere 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 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:

Crie um novo certificado gerenciado para o novo domínio.
Anexe-o à Entrada sem remover o certificado antigo.
Aguarde até que o status seja "Active".
Desanexe o certificado antigo da Entrada e exclua-o.

A seguir

Saiba mais sobre certificados gerenciados pelo Google
Saiba mais sobre balanceadores de carga HTTP(S) no Google Cloud.
Saiba como usar vários certificados SSL no balanceamento de carga HTTP(S) com Ingress.