Como configurar múltiplos contextos e namespaces no kubectl

1. Introdução aos contextos e namespaces no Kubernetes

No ecossistema Kubernetes, um contexto é um conjunto de parâmetros que define qual cluster, qual usuário e qual namespace serão utilizados por padrão pelo kubectl. Já um namespace é um mecanismo de isolamento lógico dentro de um cluster, permitindo organizar recursos e controlar acesso.

Gerenciar múltiplos contextos e namespaces é essencial para profissionais que trabalham com ambientes distintos (desenvolvimento, homologação, produção) ou com múltiplos clusters. Sem essa habilidade, o risco de executar comandos no ambiente errado aumenta significativamente, podendo causar indisponibilidade ou perda de dados.

O arquivo ~/.kube/config é o coração dessa configuração. Ele armazena todas as definições de clusters, credenciais de usuários e contextos, permitindo alternar entre ambientes com comandos simples.

2. Estrutura do arquivo kubeconfig

O kubeconfig é um arquivo YAML composto por três seções principais:

  • clusters: define os endpoints dos clusters Kubernetes
  • users: contém as credenciais de autenticação
  • contexts: associa um cluster, um usuário e opcionalmente um namespace

Para visualizar o conteúdo atual:

kubectl config view

Exemplo de estrutura básica:

apiVersion: v1
kind: Config
current-context: dev-cluster
clusters:
- cluster:
    server: https://192.168.1.100:6443
  name: dev-cluster
- cluster:
    server: https://192.168.1.200:6443
  name: prod-cluster
users:
- name: dev-user
  user:
    token: eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9...
- name: prod-user
  user:
    client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
contexts:
- context:
    cluster: dev-cluster
    user: dev-user
    namespace: development
  name: dev-context
- context:
    cluster: prod-cluster
    user: prod-user
    namespace: production
  name: prod-context

3. Criando e gerenciando contextos

Para criar um novo contexto, utilize kubectl config set-context. O comando associa um cluster, um usuário e um namespace a um nome de contexto:

kubectl config set-context staging-context \
  --cluster=staging-cluster \
  --user=staging-user \
  --namespace=staging-namespace

É possível editar manualmente o arquivo ~/.kube/config para maior controle:

# Adicionando um contexto manualmente no arquivo kubeconfig
contexts:
- context:
    cluster: homolog-cluster
    user: homolog-user
    namespace: homolog-ns
  name: homolog-context

Para atualizar um contexto existente com um novo namespace:

kubectl config set-context dev-context --namespace=frontend-dev

4. Alternando entre contextos

A troca de contexto é feita com kubectl config use-context:

kubectl config use-context prod-context

Para verificar qual contexto está ativo no momento:

kubectl config current-context

Listando todos os contextos disponíveis:

kubectl config get-contexts

A saída mostra asterisco (*) ao lado do contexto atual, além dos namespaces configurados em cada contexto.

5. Trabalhando com namespaces dentro de contextos

Cada contexto pode ter um namespace padrão. Para configurar ou alterar esse namespace:

kubectl config set-context dev-context --namespace=backend-dev

Para alterar o namespace do contexto atual sem recriar o contexto:

kubectl config set-context --current --namespace=temporary-ns

Listando todos os namespaces disponíveis no cluster:

kubectl get namespaces

É importante notar que a alteração do namespace via --namespace em comandos individuais não persiste na configuração:

kubectl get pods --namespace=monitoring

6. Técnicas avançadas de gerenciamento

Mesclando múltiplos arquivos kubeconfig

Quando se trabalha com múltiplos clusters, é comum receber arquivos kubeconfig separados. Para mesclá-los:

export KUBECONFIG=~/.kube/config:~/.kube/prod-config:~/.kube/staging-config
kubectl config view --flatten > ~/.kube/config-merged
mv ~/.kube/config-merged ~/.kube/config

Usando aliases para alternar rapidamente

Crie aliases no shell para facilitar a troca:

alias kdev='kubectl config use-context dev-context'
alias kprod='kubectl config use-context prod-context'
alias kctx='kubectl config current-context'
alias kns='kubectl config set-context --current --namespace'

Script bash para gerenciar contextos

#!/bin/bash
# Script para alternar entre contextos com menu interativo

select_context() {
  echo "Selecione o contexto:"
  select context in $(kubectl config get-contexts -o name); do
    if [ -n "$context" ]; then
      kubectl config use-context "$context"
      echo "Contexto alterado para: $context"
      break
    else
      echo "Opção inválida"
    fi
  done
}

select_namespace() {
  echo "Selecione o namespace:"
  select ns in $(kubectl get namespaces -o name | cut -d/ -f2); do
    if [ -n "$ns" ]; then
      kubectl config set-context --current --namespace="$ns"
      echo "Namespace alterado para: $ns"
      break
    else
      echo "Opção inválida"
    fi
  done
}

case "${1:-context}" in
  context) select_context ;;
  namespace) select_namespace ;;
  *) echo "Uso: $0 {context|namespace}" ;;
esac

7. Boas práticas e resolução de problemas

Segurança e versionamento

Nunca versionar arquivos kubeconfig com tokens ou certificados em repositórios públicos. Utilize ferramentas como kubelogin ou plugins de autenticação para evitar expor credenciais.

Para equipes, padronize nomes de contextos:

cliente-ambiente-regiao
exemplo: empresa-prod-us-east

Depurando erros comuns

Contexto ausente: ao tentar usar um contexto que não existe:

kubectl config use-context inexistente
# error: no context exists with the name: "inexistente"

Solução: verifique contextos disponíveis com kubectl config get-contexts.

Namespace inválido: ao configurar um namespace que não existe no cluster:

kubectl config set-context dev --namespace=inexistente
# O comando aceita, mas ao executar kubectl get pods:
# Error from server (NotFound): namespaces "inexistente" not found

Solução: crie o namespace primeiro com kubectl create namespace inexistente ou corrija para um namespace válido.

Problemas de merge: ao mesclar arquivos, podem ocorrer conflitos de nomes de contextos. Use --flatten para resolver:

kubectl config view --flatten --minify > novo-config

Referências