Kubernetes no dia a dia - kubectl, Namespaces, ConfigMaps e Secrets

1. Retomando: de conceitos a comandos

Na primeira parte desta série vimos o que é o Kubernetes, o problema que ele resolve e os três conceitos fundamentais — Pods, Deployments e Services — aplicando-os em um Deployment mínimo de Nginx. Agora que a base teórica está posta, o foco deste artigo é prático: o kubectl no dia a dia, como organizar recursos com namespaces, como gerenciar configuração e segredos com ConfigMaps e Secrets, e um primeiro deploy de uma aplicação real (não só um Nginx de exemplo).

2. kubectl além do apply e do get

O artigo anterior já usou kubectl apply e kubectl get. No dia a dia, alguns outros comandos aparecem o tempo todo:

# Descrever um recurso em detalhes (eventos, status, configuração completa)
kubectl describe pod nginx-7d9f8c6b4-x2z9k

# Ver os logs de um container dentro de um Pod
kubectl logs nginx-7d9f8c6b4-x2z9k
kubectl logs -f nginx-7d9f8c6b4-x2z9k    # segue o log em tempo real

# Abrir um shell dentro de um container em execução
kubectl exec -it nginx-7d9f8c6b4-x2z9k -- bash

# Remover um recurso
kubectl delete -f nginx-deployment.yaml

# Encaminhar uma porta local para um Pod, sem precisar expor um Service externo
kubectl port-forward pod/nginx-7d9f8c6b4-x2z9k 8080:80

kubectl describe costuma ser o primeiro comando rodado ao investigar um Pod que não sobe como esperado — a seção Events no final da saída normalmente aponta a causa (imagem não encontrada, falta de recursos no cluster, falha no readiness probe, etc.) antes mesmo de olhar os logs da aplicação.

3. Organizando recursos com Namespaces

Um namespace é uma forma de dividir um cluster em espaços lógicos isolados — times, ambientes (dev, staging, prod) ou aplicações diferentes podem viver em namespaces separados, com nomes de recursos que não colidem entre si e (com as políticas certas) sem visibilidade de rede umas nas outras.

# Criar um namespace
kubectl create namespace minha-app

# Listar todos os namespaces do cluster
kubectl get namespaces

# Aplicar um manifesto em um namespace específico
kubectl apply -f deployment.yaml -n minha-app

# Listar recursos de um namespace específico
kubectl get pods -n minha-app

# Listar recursos de TODOS os namespaces
kubectl get pods -A

Sem indicar -n, todo comando kubectl opera no namespace default — o que funciona para experimentos, mas rapidamente vira confusão em um cluster real com várias aplicações. A prática recomendada é sempre criar um namespace por aplicação ou por time, e declará-lo explicitamente nos manifestos:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: minha-app
spec:
  # ...

4. ConfigMaps: configuração fora da imagem

Uma boa prática de containers (reforçada também na série de Docker deste blog) é nunca hardcodar configuração dentro da imagem — ela deve poder rodar em qualquer ambiente, recebendo a configuração de fora. O ConfigMap é o objeto do Kubernetes para isso: um conjunto de pares chave-valor não sensíveis, injetados em Pods como variáveis de ambiente ou arquivos.

apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
  namespace: minha-app
data:
  LOG_LEVEL: "info"
  FEATURE_FLAG_NOVO_CHECKOUT: "true"

Consumindo o ConfigMap em um Deployment, como variáveis de ambiente:

spec:
  containers:
    - name: api
      image: minha-app/api:1.0
      envFrom:
        - configMapRef:
            name: api-config

5. Secrets: configuração sensível

Secrets têm a mesma forma de uso que ConfigMaps, mas são destinados a dados sensíveis — senhas, tokens, chaves de API. A diferença mais importante não é técnica (por padrão, o conteúdo de um Secret só é codificado em base64, não criptografado) e sim de intenção: o Kubernetes trata Secrets de forma diferente em alguns pontos (não fica visível por padrão em kubectl describe, por exemplo), e é o objeto certo para integrar com soluções de criptografia em repouso ou cofres externos (Vault, AWS Secrets Manager) em clusters de produção.

# Criar um Secret diretamente pela CLI, sem escrever a senha em um YAML versionado
kubectl create secret generic api-db-credentials \
  --from-literal=DB_USER=app \
  --from-literal=DB_PASSWORD='troque-por-um-valor-real' \
  -n minha-app

Consumindo o Secret, também como variáveis de ambiente:

spec:
  containers:
    - name: api
      image: minha-app/api:1.0
      envFrom:
        - configMapRef:
            name: api-config
        - secretRef:
            name: api-db-credentials

Um ponto importante — e que volta com força no Artigo 3 desta série, sobre GitOps: nunca commitar um Secret com valores reais em texto plano em um repositório Git, nem mesmo privado. Ferramentas como Sealed Secrets ou integrações com cofres externos existem exatamente para permitir versionar segredos com segurança dentro de um fluxo GitOps.

6. Um deploy real: API com configuração e banco

Juntando os conceitos, um exemplo mais próximo de uma aplicação real: uma API que lê configuração de um ConfigMap, credenciais de um Secret, e é exposta dentro do cluster por um Service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: minha-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: minha-app/api:1.0
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: api-config
            - secretRef:
                name: api-db-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: minha-app
spec:
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 8080

kubectl apply -f api-deployment.yaml
kubectl rollout status deployment/api -n minha-app

kubectl rollout status acompanha o deploy até todas as réplicas ficarem prontas (ou aponta o erro, se alguma falhar) — útil tanto em terminal manual quanto como passo de verificação em um pipeline de CI/CD.

7. Conclusão e próximos passos

Com kubectl describe/logs/exec para investigar, namespaces para organizar, e ConfigMaps/Secrets para separar configuração do código da aplicação, já é possível fazer deploys reais de forma organizada em um cluster Kubernetes. Até aqui, porém, todo kubectl apply foi rodado à mão, a partir da máquina de quem está operando o cluster — o que não escala bem para times e não deixa rastro confiável do que foi aplicado e quando. No próximo artigo, a série entra em GitOps: o que é, por que faz sentido tratar infraestrutura como código versionado, e uma introdução ao ArgoCD para aplicar automaticamente o que está em um repositório Git ao cluster.

Imagem de capa: Logo oficial do Kubernetes — repositório kubernetes/kubernetes

Referências:

1. Kubernetes Documentation — kubectl Reference
2. Kubernetes Documentation — Namespaces
3. Kubernetes Documentation — ConfigMaps
4. Kubernetes Documentation — Secrets