Fazer a rotação das credenciais do cluster

Nesta página, explicamos como executar uma rotação de credenciais em clusters do Google Kubernetes Engine (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. Para mais detalhes, consulte Ciclo de vida da AC raiz do cluster.

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

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.

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 gcloud CLI 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 AC do cluster expirar em 6 de janeiro de 2024 e você não alternar suas credenciais até 5 de dezembro de 2023, o GKE vai iniciar uma rotação automática a partir de 7 de dezembro de 2023 e conclui 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 ignoram as janelas de manutenção ou exclusões de manutenção configuradas
  • 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.

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.

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 gcloud components update.

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 \
    --region REGION_NAME \
    --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 \
    | awk 'NR>1 {print "echo; echo Validity for cluster " $1 " in location " $2 ":;\
         gcloud container clusters describe --project PROJECT_ID " $1 " --location " $2 " \
         --format \"value(masterAuth.clusterCaCertificate)\" \
         | base64 --decode | openssl x509 -noout -dates"}' \
    | bash

Fazer uma rotação de credenciais

A 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 credencial, o GKE recria os nós para você. No entanto, durante eventos importantes como o Google Cloud Next, podemos pausar as recriações automáticas de nós para que você não tenha interrupções. 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 conclusão automática falhará. Planeje e conclua manualmente as rotações de credencial depois de iniciar a 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 \
    --region REGION_NAME \
    --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.

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.

  • Se você usar exclusões de manutenção ou janelas de manutenção que possam resultar em uma rotação com falha, faça upgrade do cluster manualmente para forçar a recriação do nó:

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

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

    Para mais informações, consulte avisos sobre janelas de manutenção.

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 \
    --region REGION_NAME

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 depois de concluir a rotação.

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 \
    --region=REGION_NAME \
    --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.

A seguir