Fazer a rotação das credenciais do cluster

Autopilot Standard

Nesta página, explicamos como alternar as credenciais do cluster do GKE. Planejar e alternar regularmente as credenciais do cluster é crucial para manter os clusters em um estado íntegro. Nesta página, você vai aprender a fazer rotações de credenciais. Você também vai aprender sobre as práticas recomendadas para planejar rotações regulares.

Esta página é destinada 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 mencionamos no conteúdo do Google Cloud , consulte Tarefas e funções de usuário comuns 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. A vida útil das credenciais do cluster depende de quando você criou o cluster ou quando fez a última rotação das credenciais. Para mais detalhes, confira o ciclo de vida da credencial.

Execute uma rotação de credenciais para revogar e emitir novas credenciais para o cluster. Essa operação faz a rotação da chave privada da AC do cluster e requer a recriação dos nós para o uso das novas credenciais. É necessário iniciar e concluir uma rotação de credenciais para o cluster antes da data de validade das credenciais atuais. Além da rotação de credenciais, ocorre também a execução de uma rotação de IPs.

Quando realizar uma rotação de credenciais

Importante: planeje e execute rotações de credenciais com bastante antecedência com relação à data de validade da AC raiz do cluster. O cluster entra no estado DEGRADED sete dias antes da data de validade das credenciais atuais. Essa é sua última oportunidade de fazer a rotação das credenciais antes que o cluster e as cargas de trabalho se tornem irrecuperáveis.

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 qual tipo de interrupção o cluster sofre durante as etapas de uma rotação, consulte a linha de 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 atualizações de nós, consulte Planejar interrupções de atualização de nós.

Ciclo de vida das credenciais do cluster

O ciclo de vida das credenciais do cluster geralmente depende de quando o cluster foi criado ou quando as credenciais foram trocadas mais recentemente:

• Os clusters criados antes de outubro de 2021 têm um ciclo de vida de CA de cinco anos.
• Os clusters criados após outubro de 2021 têm um ciclo de vida de CA de 30 anos.
• Os clusters rotacionados após aproximadamente janeiro de 2022 têm um tempo de vida 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 console do Google Cloud . Também é possível consultar estas orientações com a CLI gcloud ou a API Recommender, especificando o subtipo CLUSTER_CA_EXPIRATION.

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, se a CA do cluster expirar em 6 de janeiro de 2024 e você não alternar suas credenciais até 5 de dezembro de 2023. O GKE inicia uma rotação automática a partir de 7 de dezembro de 2023 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, mas o GKE se reserva o direito de realizar etapas em até 30 dias após o vencimento para girar as credenciais, independente da disponibilidade de manutenção. Em 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 vai continuar tentando concluir a rotação até a data de validade das credenciais. Depois disso, o cluster se torna 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 vão funcionar 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.

Aviso: as rotações automáticas iniciadas pelo GKE são uma medida de emergência para a prevenção contra interrupções. Não dependa apenas delas, pois essa é uma medida preventiva de emergência para evitar interrupções completas e pode ser bloqueada pela disponibilidade de manutenção e restrições relacionadas. Para saber mais sobre essas restrições, consulte Janela de manutenção que impede a conclusão da atualização do nó.

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 CLI do Google Cloud para essa tarefa, instale e inicialize a gcloud CLI. 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.
  Observação: em instalações prévias da gcloud CLI, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na gcloud CLI como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

• Verifique se você tem um cluster do Autopilot ou Standard. Se precisar de um, crie um cluster do Autopilot.

Verificar o ciclo de vida da credencial

Recomendamos que você verifique o ciclo de vida da credencial antes e depois de executar uma rotação de credenciais para saber a validade da CA 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 inicia uma rotação automaticamente, o GKE executa essas etapas automaticamente, incluindo a tentativa de concluir a rotação. Em cada etapa, se o prazo de validade do cluster for superior a 30 dias, o GKE vai respeitar a disponibilidade de manutenção. Durante as rotações automáticas antes do vencimento do cluster, o GKE se reserva o direito de ignorar a disponibilidade de manutenção para evitar que o cluster se torne irrecuperável. Em 30 dias, o GKE ignora a disponibilidade de manutenção na 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 vai falhar, mas o GKE vai continuar tentando até que as credenciais expirem e o cluster não possa mais ser recuperado. Planeje rastrear e concluir manualmente as rotações de credenciais 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.

Cuidado: em clusters padrão zonais, que têm um plano de controle de nó único, esse comando causa um breve período de inatividade do servidor da API do cluster. Os clusters do Autopilot e os clusters padrão regionais têm nós de plano de controle replicados e não apresentam inatividade.

Recriar nós

Aviso: erros de recriação de nós podem ocorrer se uma rotação for tentada depois que a CA do cluster já tiver expirado. Esse erro é indicado por registros que contêm a seguinte mensagem: x509: certificate has expired or is not yet valid. Para tentar se recuperar desse erro, conclua a rotação, crie novos pools de nós, migre suas cargas de trabalho e exclua os pools de nós antigos. No entanto, como os clusters com CAs expirados geralmente não podem ser recuperados, esse esforço pode falhar, e talvez seja necessário criar um novo cluster.

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 prossiga. 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:

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

  gcloud container clusters upgrade CLUSTER_NAME \
      --location=LOCATION \
      --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.

Observação: quando o GKE recria nós durante uma rotação de credenciais, esses nós têm certificados da autoridade de certificação (CA) anterior e da nova CA. Esse é o comportamento esperado para reduzir o risco de interrupções durante a rotação. Depois que a rotação de credenciais for concluída, todos os nós novos e existentes terão apenas certificados da nova CA.

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

Observação: se você estiver usando a API Kubernetes Certificates, também precisará emitir novos certificados.

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 as credenciais estáticas da ServiceAccount que existem no seu 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, seu cluster não terá credenciais estáticas de ServiceAccount.

Observação: se você armazenar credenciais estáticas em repositórios de gerenciamento de secrets externos ao GKE, também será necessário verificar as credenciais nessas ferramentas.

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

Cuidado: em clusters padrão zonais, que têm um plano de controle de nó único, esse comando causa um breve período de inatividade do servidor da API do cluster. Os clusters do Autopilot e os clusters padrão regionais têm nós de plano de controle replicados e não apresentam inatividade.

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 automaticamente a rotação. No entanto, o GKE pode ignorar essa disponibilidade 30 dias antes da expiração para evitar que o cluster se torne irrecuperável. Se a conclusão da rotação falhar inicialmente e ela tiver sido iniciada há pelo menos sete dias, o GKE tentará concluir a rotação até a data de expiração das credenciais. Depois disso, o cluster não poderá ser recuperado.

A seguir

• Saiba sobre o objeto de chave secreta do Kubernetes.
• Saiba como resolver problemas do GKE.