Guia para Gerenciar Múltiplos Clusters Kubernetes com kubectl config

Gerenciar múltiplos clusters Kubernetes é normal quando você tem desenvolvimento, homologação, produção ou clusters em mais de uma nuvem. O risco é simples: um comando pode atingir o cluster errado se seu contexto não estiver claro.

Este guia mostra como usar kubectl config para inspecionar contextos, alternar clusters, definir namespaces e organizar múltiplos arquivos kubeconfig.

Entendendo o Arquivo Kubeconfig

Antes de mergulhar nos comandos kubectl config, é essencial entender o arquivo kubeconfig. Este arquivo armazena informações sobre seus clusters, usuários e os contextos que os vinculam. O kubectl usa este arquivo para autenticar e especificar com qual cluster interagir. Por padrão, o kubectl procura o arquivo kubeconfig em $HOME/.kube/config.

Dentro deste arquivo, você encontrará três seções principais:

clusters: Define os clusters Kubernetes, incluindo seus endpoints do servidor API e autoridades certificadoras.
users: Armazena credenciais de autenticação, como certificados de cliente e tokens.
contexts: Associa um cluster, um usuário e, opcionalmente, um namespace. Um contexto fornece uma maneira conveniente de agrupar essas configurações, permitindo que o kubectl alterne facilmente entre diferentes combinações de cluster/usuário.

Gerenciando Contextos com `kubectl config`

Contextos são a principal forma de o kubectl gerenciar sua conexão com diferentes clusters Kubernetes. Eles atuam como atalhos, permitindo que você alterne entre eles com um único comando.

Visualizando Contextos Disponíveis

Para ver todos os contextos disponíveis em seu arquivo kubeconfig atual, use o seguinte comando:

kubectl config get-contexts

Este comando exibirá uma lista de contextos, juntamente com o cluster, usuário e namespace associados a cada um. O contexto atualmente ativo será marcado com um asterisco (*).

Exemplo de Saída:

CURRENT   NAME                 CLUSTER              AUTHINFO       NAMESPACE
*         my-dev-context       my-dev-cluster       dev-user       default
          my-prod-context      my-prod-cluster      prod-user      production
          staging-context      staging-cluster      staging-user   staging

Obtendo o Contexto Atual

Para verificar rapidamente qual contexto você está usando atualmente, execute:

kubectl config current-context

Isso exibirá o nome do contexto ativo.

Alternando Contextos

Alternar para um contexto diferente é simples. Use o subcomando use-context seguido pelo nome do contexto que deseja ativar:

kubectl config use-context <nome-do-contexto>

Por exemplo, para alternar para my-prod-context do exemplo acima:

kubectl config use-context my-prod-context

Após executar este comando, os comandos subsequentes do kubectl serão direcionados ao cluster especificado em my-prod-context.

Definindo um Contexto

Você também pode definir um contexto específico para um cluster e usuário sem necessariamente torná-lo o padrão para uso futuro. Isso é útil para operações temporárias.

kubectl config set-context <nome-do-contexto> --cluster=<nome-do-cluster> --user=<nome-do-usuario> --namespace=<nome-do-namespace>

Se você omitir --namespace, o namespace padrão do cluster será usado.

Gerenciando Clusters e Usuários

Embora os contextos sejam usados para alternar, você também pode gerenciar diretamente as configurações de cluster e usuário às quais os contextos se referem.

Visualizando Informações do Cluster

Para listar todos os clusters configurados:

kubectl config get-clusters

Para visualizar detalhes de um cluster específico:

kubectl config view --minify -o jsonpath='{.clusters[?(@.name=="<nome-do-cluster>")].cluster}'

Substitua <nome-do-cluster> pelo nome real do seu cluster.

Visualizando Informações do Usuário

Para listar todos os usuários configurados:

kubectl config get-users

Adicionando e Modificando Configurações

Você pode adicionar novos clusters, usuários e contextos, ou modificar os existentes:

Adicionar um novo cluster:

kubectl config set-cluster <nome-do-cluster> --server=<url-do-servidor-api> --certificate-authority=<caminho-para-o-arquivo-ca> --embed-certs=true

Adicionar um novo usuário:

kubectl config set-credentials <nome-do-usuario> --client-certificate=<caminho-para-o-arquivo-de-certificado> --client-key=<caminho-para-o-arquivo-de-chave> --embed-certs=true

Adicionar um novo contexto:

kubectl config set-context <nome-do-contexto> --cluster=<nome-do-cluster> --user=<nome-do-usuario> --namespace=<nome-do-namespace>

Gerenciando Múltiplos Arquivos Kubeconfig

Para maior segurança e organização, especialmente ao lidar com muitos clusters ou credenciais sensíveis, é uma boa prática manter seus arquivos kubeconfig separados. O kubectl pode gerenciar múltiplos arquivos kubeconfig usando a variável de ambiente KUBECONFIG ou a flag --kubeconfig.

Usando a Variável de Ambiente `KUBECONFIG`

Você pode especificar uma lista de arquivos kubeconfig para carregar. O kubectl mescla esses arquivos. Se o mesmo cluster, usuário ou contexto nomeado aparecer em mais de um arquivo, a precedência de mesclagem depende da ordem dos arquivos em KUBECONFIG, então use nomes únicos para evitar surpresas.

Para definir esta variável para sua sessão atual do shell:

export KUBECONFIG=~/.kube/config:~/.kube/config-dev:~/.kube/config-prod

Para tornar isso persistente, adicione a linha export ao arquivo de perfil do seu shell (por exemplo, ~/.bashrc, ~/.zshrc).

Usando a Flag `--kubeconfig`

Alternativamente, você pode especificar um arquivo kubeconfig específico para um único comando kubectl:

kubectl --kubeconfig=~/.kube/config-dev get pods

Isso é útil para comandos avulsos ou quando você quer ter certeza absoluta de qual arquivo está sendo usado.

Melhores Práticas para Gerenciamento de Múltiplos Clusters

Use Arquivos Separados: Armazene configurações para diferentes ambientes (dev, staging, prod) ou provedores de nuvem em arquivos kubeconfig distintos (por exemplo, config-dev, config-staging, config-prod).
Aproveite o KUBECONFIG: Defina a variável de ambiente KUBECONFIG no perfil do seu shell para mesclar e gerenciar facilmente vários arquivos sem mesclagem manual.
Nomes de Contexto Descritivos: Use nomes claros e descritivos para seus contextos (por exemplo, aws-prod-us-east-1, gke-dev-eu-west-2) para evitar confusão.
Consciência de Namespace: Esteja sempre atento ao namespace em que está operando. Use a flag --namespace ou defina-o em seu contexto para direcionar o namespace correto.
Audite Regularmente: Revise periodicamente seus contextos e configurações de cluster para garantir que estejam atualizados e seguros.
Proteja Seu Kubeconfig: Trate seus arquivos kubeconfig como credenciais sensíveis. Restrinja as permissões de arquivo e evite enviá-los para o controle de versão.

Consideração Final

Incorpore verificações de contexto ao seu fluxo de trabalho. Execute kubectl config current-context antes de comandos arriscados, use nomes de contexto descritivos, defina namespaces intencionalmente e mantenha as credenciais de produção fora de sessões casuais do shell quando não precisar delas.