Fazer a rotação das credenciais do cluster

Planejar e fazer a rotação das credenciais do cluster regularmente é fundamental para manter os clusters em um estado íntegro. Este documento mostra como fazer rotações de credenciais e oferece práticas recomendadas para planejar rotações regulares.

Este documento é destinado a especialistas em segurança responsáveis pelo ciclo de vida das credenciais em clusters do GKE. Para saber mais sobre papéis comuns e exemplos de tarefas que referenciamos no Google Cloud conteúdo, consulte Funções e tarefas comuns do usuário do GKE.

Sobre rotações de credenciais no GKE

A autoridade certificadora (AC) raiz do cluster tem um ciclo de vida limitado. Quando a AC expira, todas as credenciais que foram assinadas por ela deixam de ser válidas, incluindo o certificado de cliente do cluster (do campo de API MasterAuth), a chave e o certificado do servidor de API e os certificados de cliente do kubelet. O ciclo de vida da credencial do cluster depende de quando você criou o cluster ou quando fez a rotação das credenciais pela última vez. Para mais detalhes, consulte o ciclo de vida da credencial.

É possível revogar e emitir novamente essas credenciais executando um dos seguintes tipos de rotação.

  • Rotação de credenciais:

    • Faz a rotação do endereço IP que o plano de controle usa para o servidor da API Kubernetes.
    • Faz a rotação da AC raiz do cluster.
    • Faz a rotação das chaves da conta de serviço do Kubernetes, que são usadas para assinar e verificar as credenciais da conta de serviço.
    • Faz a rotação da AC da camada de agregação.

  • Rotação de endereço IP:

    • Faz a rotação do endereço IP que o plano de controle usa para o servidor da API Kubernetes.
    • Faz a rotação da AC raiz do cluster.

Para esses dois tipos de rotação, os nós precisam ser recriados antes de poderem usar novas credenciais.

É necessário iniciar e concluir uma rotação de credenciais para o cluster antes da data de validade das credenciais atuais.

Quando realizar uma rotação de credenciais

Faça rotações de credenciais regularmente e antes da data de validade atual das credenciais. As rotações de credenciais exigem a recriação dos nós para o uso das novas credenciais, o que pode ser prejudicial para as cargas de trabalho em execução. Planeje os períodos de manutenção e execute as rotações durante as janelas de manutenção para evitar inatividade inesperada da carga de trabalho ou clientes da API não responsivos fora do cluster.

Para saber mais sobre como a disponibilidade de manutenção afeta a rotação de credenciais do cluster e que tipo de interrupção o cluster sofre durante as etapas de uma rotação, consulte a linha da rotação de credenciais na tabela de mudanças manuais que recriam os nós usando uma estratégia de upgrade de nós e respeitando as políticas de manutenção. O GKE depende da disponibilidade de recursos para atualizar os nós. Para saber mais sobre as atualizações de nós, consulte Planejar interrupções de atualização de nós.

Ciclo de vida da credencial do cluster

O ciclo de vida da credencial do cluster geralmente depende de quando o cluster foi criado ou quando as credenciais foram giradas mais recentemente:

  • Os clusters criados antes de outubro de 2021 têm um ciclo de vida de AC de cinco anos.
  • Os clusters criados após outubro de 2021 têm um ciclo de vida de AC de 30 anos.
  • Os clusters girados após janeiro de 2022 têm um ciclo de vida de AC de 30 anos.

Encontrar clusters com credenciais expiradas ou prestes a expirar

Se as credenciais do cluster expirarem nos próximos 180 dias ou as credenciais do cluster já expiraram, o GKE fornecerá orientação com um insight e uma recomendação para explicar que você precisa executar uma rotação de credenciais para esse cluster. Essa orientação inclui a data de validade das credenciais. Acesse essas orientações no Google Cloud console. Também é possível consultar estas orientações com a CLI gcloud ou a API Recommender, especificando o CLUSTER_CA_EXPIRATION subtipo.

Se você receber um insight e uma recomendação para um cluster, será necessário realizar uma rotação de credenciais ou o GKE iniciará uma rotação de credenciais automaticamente até 30 dias após a data de validade da CA atual, conforme explicado na próxima seção. Depois que a rotação de credenciais for concluída, pode levar até 36 horas para que o insight e a recomendação sejam resolvidos.

Política de automação do GKE para evitar interrupções no cluster

Para evitar que o cluster entre em um estado irrecuperável após a data de validade das credenciais atuais, o GKE inicia automaticamente uma rotação de credenciais 30 dias antes da data de validade atual da AC. Por exemplo, a AC do cluster expira em 6 de janeiro de 2024 e você não faz a rotação das credenciais até 5 de dezembro de 2023. O GKE inicia uma rotação automática em 7 de dezembro de 2023 ou depois e tenta concluir essa rotação sete dias após o início da operação. Essa rotação automática será uma última tentativa de evitar a interrupção do cluster e levará em conta o seguinte:

  • As rotações automáticas geralmente respeitam as janelas ou exclusões de manutenção. No entanto, o GKE reserva o direito de executar etapas em até 30 dias após a expiração para girar as credenciais, independentemente da disponibilidade de manutenção. Em até 30 dias, o GKE ignora a disponibilidade de manutenção para a primeira etapa, que é iniciar a rotação.
  • Se a disponibilidade de manutenção impedir que o GKE conclua a rotação inicialmente, o GKE continuará tentando concluir a rotação até a data de validade das credenciais. Depois disso, o cluster se tornará irrecuperável.
  • Quando a rotação de credenciais é concluída, as credenciais expiradas são revogadas. Os clientes da API Kubernetes fora do cluster, como o kubectl em ambientes locais, não funcionarão até que você os configure para usar as novas credenciais.
  • A recriação do pool de nós durante a rotação pode causar interrupções nas cargas de trabalho em execução.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

Verificar o ciclo de vida da credencial

Verifique o ciclo de vida da credencial antes e depois de executar uma rotação de credenciais para saber a validade da AC raiz do cluster.

Para verificar a vida útil da credencial de um único cluster, execute o seguinte comando:

gcloud container clusters describe CLUSTER_NAME \
    --location LOCATION \
    --format "value(masterAuth.clusterCaCertificate)" \
    | base64 --decode \
    | openssl x509 -noout -dates

O resultado será assim:

notBefore=Mar 17 16:45:34 2023 GMT
notAfter=Mar  9 17:45:34 2053 GMT

Se você executar esse comando após iniciar uma rotação de credenciais, a saída será o ciclo de vida do certificado original. Esse certificado permanece válido até que você conclua a rotação. Depois de concluir a rotação, a saída será a vida útil do novo certificado.

Para verificar a vida útil da credencial de todos os clusters em um projeto, execute o seguinte comando:

gcloud container clusters list --project PROJECT_ID \
    --format="value(name,masterAuth.clusterCaCertificate)" | \
while read -r cluster ca; do \
    expiry_date=$(echo -e "$ca" | base64 --decode | openssl x509 -noout -enddate | awk -F'=' '{print $2}'); \
    printf "%-40s  | %s\n" "$cluster" "$expiry_date" ; \
done | \
column -t | \
awk -F',' 'BEGIN{print "Cluster Name    |  Certificate Expiry Date"} {print}'

Fazer uma rotação de credenciais

Qualquer rotação de credenciais envolve as seguintes etapas:

  1. Inicie a rotação: o plano de controle começa a ser exibido em um novo endereço IP além do endereço IP original. Novas credenciais são emitidas para cargas de trabalho e para o plano de controle.
  2. Recriar nós: o GKE recria os nós do cluster para que eles usem o novo endereço IP e as novas credenciais, respeitando a disponibilidade de janelas de manutenção e exclusões. Também é possível recriar manualmente os nós executando um upgrade da versão deles para a mesma versão do GKE que já executam.
  3. Atualizar clientes de API: depois de iniciar a rotação, atualize todos os clientes de API de cluster, como máquinas de desenvolvimento, usando kubectl para se comunicar com o plano de controle usando o novo endereço IP.
  4. Conclua a rotação: o plano de controle deixa de atender ao tráfego no endereço IP original. As credenciais antigas serão revogadas, incluindo todas as credenciais estáticas atuais das contas de serviço do Kubernetes.

Quando você inicia uma rotação de credenciais ou quando o GKE automaticamente inicia uma rotação, o GKE executa essas etapas automaticamente, incluindo a tentativa de concluir a rotação. Em cada etapa, se a expiração do cluster for maior que 30 dias, o GKE respeitará a disponibilidade de manutenção. Durante as rotações automáticas antes da expiração do cluster, o GKE reserva o direito de ignorar a disponibilidade de manutenção para evitar que o cluster se torne irrecuperável. Em até 30 dias, o GKE ignora a disponibilidade de manutenção para a primeira etapa, que é iniciar a rotação.

Se você não concluir uma rotação de credencial no prazo de sete dias após iniciá-la, o GKE tentará concluí-la para você. Se algum nó no cluster ainda usar as credenciais anteriores, a operação de conclusão automática falhará, mas o GKE continuará tentando concluir até que as credenciais expirem e o cluster se torne irrecuperável. Planeje e conclua manualmente as rotações de credencial que você iniciar. Para substituir os bloqueadores de disponibilidade de manutenção, execute os comandos em cada uma das seções a seguir para acionar manualmente essas fases do processo de rotação. Não dependa da conclusão automática, que é uma medida de melhor esforço.

Iniciar a rotação

Para iniciar uma rotação de credenciais, execute o seguinte comando:

gcloud container clusters update CLUSTER_NAME \
    --location LOCATION \
    --start-credential-rotation

Esse comando cria novas credenciais, emite essas credenciais para o plano de controle e configura o plano para ser exibido em dois endereços IP: o original e o novo.

Reiniciar componentes no cluster com conexões de longa duração

Depois de iniciar uma rotação de endereço IP ou de credencial, a autoridade certificadora (AC) do cluster também será girada. Alguns componentes no cluster que mantêm conexões TLS de longa duração, por exemplo, metrics-server e konnectivity-agent, podem não confiar automaticamente na nova AC do cluster.

Essa situação pode fazer com que essas conexões falhem ao se comunicar com nós ou outros endpoints de cluster, e você poderá ver erros de handshake de TLS nos registros de componentes, como x509: certificate signed by unknown authority.

Se você observar esses erros após iniciar uma rotação, talvez seja necessário reiniciar os pods manualmente. Uma reinicialização força o pod a reinicializar a conexão e carregar os novos certificados de AC do cluster. Por exemplo, para reiniciar o metrics-server e o konnectivity-agent, execute os seguintes comandos:

kubectl rollout restart deployment metrics-server -n kube-system
kubectl rollout restart deployment konnectivity-agent -n kube-system

Recriar nós

Depois de reconfigurar o servidor de API para disponibilizar em um novo endereço IP, o GKE atualiza automaticamente os nós para usar o novo endereço IP e as credenciais, se houver disponibilidade de manutenção. O GKE faz upgrade de todos os nós para a mesma versão do GKE que os nós já executam, o que recria os nós. Para mais informações, consulte Upgrades do pool de nós.

Por padrão, o GKE conclui as rotações de credenciais automaticamente sete dias após o início da operação. Se uma janela de manutenção ativa ou exclusão no cluster impedir que o GKE recrie alguns nós durante esse período de sete dias, a rotação de credenciais não será concluída inicialmente. No entanto, o GKE continua tentando recriar os nós e concluir a rotação até que a disponibilidade de manutenção permita que o GKE continue. Durante eventos importantes como o Google Cloud Next, o GKE também pode pausar as recriações automáticas de nós para que você não tenha interrupções.

Se você usar exclusões de manutenção ou janelas de manutenção que possam resultar em uma rotação com falha, force o GKE a recriar os nós seguindo uma destas etapas:

  • Em clusters do Autopilot, faça upgrade manual do plano de controle:

    gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --master \
    --cluster-version=VERSION

    Substitua VERSION pela mesma versão do GKE que o cluster já usa.

  • Em clusters padrão, faça upgrade manual de cada pool de nós.

Para mais informações, consulte mudanças manuais que respeitam as políticas de manutenção do GKE.

Verificar o progresso da recriação do pool de nós

  1. Para monitorar a operação de rotação, execute o seguinte comando:

    gcloud container operations list \
    --filter="operationType=UPGRADE_NODES AND status=RUNNING" \
    --format="value(name)"

    Esse comando retorna o ID da operação de upgrade do nó.

  2. Para pesquisar a operação, passe o código da operação para o seguinte comando:

    gcloud container operations wait OPERATION_ID

Os pools de nós são recriados um a um, e cada um tem uma operação própria. Se você tiver vários pools de nós, use estas instruções para pesquisar cada operação.

Atualizar clientes da API

Depois de iniciar a rotação de credenciais, atualize todos os clientes da API fora do cluster (como kubectl nas máquinas do desenvolvedor) para usar as novas credenciais e apontar para o novo endereço IP do plano de controle.

Para atualizar os clientes de API, execute o seguinte comando para cada um deles:

gcloud container clusters get-credentials CLUSTER_NAME \
    --location LOCATION

Atualizar as credenciais da conta de serviço do Kubernetes

Se você usa credenciais estáticas para ServiceAccounts no cluster, alterne para credenciais de curta duração. A conclusão da rotação invalida as credenciais atuais da ServiceAccount. Se você não quiser usar credenciais de curta duração, recrie as credenciais estáticas para todas as ServiceAccounts no cluster antes de concluir a rotação.

Para encontrar credenciais estáticas da ServiceAccount que existem no cluster, execute o seguinte comando:

kubectl get secrets --all-namespaces --field-selector type=kubernetes.io/service-account-token

Se a saída desse comando for No resources found, o cluster não terá credenciais estáticas da ServiceAccount.

Atualizar endereços IP fixados no código e regras de firewall

Se você fixou no código o endereço IP do plano de controle no ambiente ou se tem regras de firewall que segmentam o endereço IP do plano de controle, atualize os endereços para o novo endereço IP. Se você concluir a rotação sem atualizar endereços IP nos aplicativos e nas regras de firewall, esses recursos poderão sofrer interrupções quando o GKE parar de atender ao endereço IP do plano de controle anterior.

Completar a rotação

Depois de atualizar os clientes da API fora do cluster, conclua a rotação para configurar o plano de controle para ser exibido apenas com as novas credenciais e o novo endereço IP:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --complete-credential-rotation

Se a rotação de credenciais não for concluída e retornar uma mensagem de erro semelhante a esta, consulte Erro 400: o pool de nós requer recriação:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400, message=Node pool "test-pool-1" requires recreation.

O GKE respeita a disponibilidade de manutenção ao concluir a rotação automaticamente. No entanto, o GKE pode ignorar essa disponibilidade em até 30 dias após a expiração para evitar que o cluster se torne irrecuperável. Se a conclusão da rotação falhar inicialmente e a rotação tiver sido iniciada há pelo menos sete dias, o GKE tentará concluir a rotação até a data de validade das credenciais. Depois disso, o cluster se tornará irrecuperável. É possível tentar recuperar o cluster seguindo as etapas em a seção Recuperar um cluster após a expiração da AC.

Recuperar um cluster após a expiração da AC

Após a data de validade da AC do cluster, um cluster poderá se tornar irrecuperável. Se você tentar iniciar uma rotação de credenciais após a data de validade da AC, o GKE poderá falhar ao criar novos pools de nós. A seguinte mensagem aparece nos registros:

x509: certificate has expired or is not yet valid

É possível tentar recuperar manualmente o cluster desse estado. No entanto, como os clusters com ACs expiradas geralmente são irrecuperáveis, esse esforço pode falhar e talvez seja necessário criar um novo cluster. Para tentar recuperar o cluster, siga estas etapas:

  1. Inicie uma rotação de credenciais. Se uma rotação de credenciais já estiver em andamento, pule esta etapa.
  2. Conclua a rotação. O plano de controle do GKE deixa de usar a AC anterior e usa exclusivamente a nova AC.

  3. Crie novos pools de nós para substituir os atuais.

    Se a criação do pool de nós falhar com uma mensagem de erro IP_SPACE_EXHAUSTED_WITH_DETAILS, exclua os pools de nós atuais antes de criar novos. Quando você exclui um pool de nós, os endereços IP ficam disponíveis para uso em novos pools de nós.

  4. Migre as cargas de trabalho para os novos pools de nós.

  5. Atualize os clientes da API Kubernetes para usar as novas credenciais e o novo endereço IP do plano de controle.

  6. Atualize as credenciais estáticas da conta de serviço do Kubernetes para usar tokens assinados pela nova AC.

Se o cluster ainda estiver irrecuperável após a conclusão dessas etapas, então crie um novo cluster.

A seguir