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.

Apresentamos a API v1beta2

Os certificados gerenciados são um recurso Beta disponível em todas as versões do Google Kubernetes Engine (GKE). Em clusters com planos de controle que executam versões do GKE anteriores à 1.16.5-gke.1, os certificados gerenciados estão disponíveis na versão v1beta1 e não são compatíveis com vários nomes alternativos do assunto (SANs) por certificado.

No GKE 1.16.5-gke.1 e posteriores, os certificados gerenciados estão disponíveis na versão v1beta2 e são compatíveis com até 100 SANs por certificado. A versão v1beta1 ainda está disponível.

Como migrar da API v1beta1 para v1beta2

A diferença entre v1beta1 e v1beta2 está apenas na validação, permitindo mais nomes de domínio por certificado. O número da versão foi atualizado para destacar claramente a diferença, evitando alterações silenciosas nas regras de validação e os equívocos que isso poderia provocar.

A migração dos recursos da v1beta1 para a versão v1beta2 é automática, quando são atualizados. Os recursos são atualizados automaticamente. Depois que a versão v1beta1 é removida, nenhum novo recurso pode ser criado nessa versão.

Como criar um Ingress 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.
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:
```
apiVersion: networking.gke.io/v1beta2
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
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/v1beta1
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.

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árias entradas), você deve criar um único recurso ManagedCertificate e anexá-lo 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 for resolvido para endereços IPv4 e IPv6 configurados com diferentes recursos de Entrada, você precisará criar um único recurso ManagedCertificate e anexá-lo à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.

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. Os certificados gerenciados em clusters que executam versões de GKE anteriores a 1.16.5-gke.1 aceitam apenas um domínio.

`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 recurso 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 ele poderá ser excluído.

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.