kubernetes-patterns

Padrões Kubernetes

Padrões Kubernetes de nível de produção para implantar, gerenciar e depurar workloads de forma confiável.

Quando Ativar

• Escrevendo manifestos Kubernetes (Deployments, Services, Ingress, Jobs)
• Configurando requests/limits de recursos, probes de liveness/readiness
• Configurando RBAC, namespaces ou ServiceAccounts
• Gerenciando configuração e segredos no K8s
• Depurando CrashLoopBackOff, OOMKilled, pods pendentes ou erros de pull de imagem
• Configurando HPA (Horizontal Pod Autoscaler) ou PodDisruptionBudgets
• Revisando YAML do K8s para segurança ou correção

Quando Usar

O mesmo que Quando Ativar acima. Este alias satisfaz as convenções de formato de skill do repositório. Use esta skill sempre que estiver escrevendo, revisando ou depurando YAML e workloads do Kubernetes.

Como Funciona

Esta skill fornece padrões YAML de nível de produção prontos para copiar e colar e comandos de depuração kubectl organizados por tarefa:

1. Template de Deployment — Um Deployment de produção totalmente configurado com contexto de segurança, estratégia de atualização rolling, todos os três tipos de probe, limites de recursos e injeção de ambiente a partir de ConfigMap/Secret.
2. Probes — Tabela de decisão para startup vs liveness vs readiness, com a matemática correta de failureThreshold × periodSeconds.
3. Services & Ingress — Padrões de ClusterIP, LoadBalancer e Ingress com TLS e anotações de cert-manager.
4. ConfigMaps & Secrets — Orientação sobre envFrom, montagem de arquivo e segredos externos.
5. Gerenciamento de recursos — Regras práticas de requests vs limits por tipo de workload (API web, JVM, worker, sidecar).
6. RBAC — Cadeia de ServiceAccount → Role → RoleBinding com privilégio mínimo.
7. HPA & PDB — Configurações de autoscaling e segurança durante drenagem de nós.
8. Jobs & CronJobs — Padrões de workloads únicos e agendados com restartPolicy correta.
9. Cheatsheet kubectl — Comandos para logs, exec, rollback, port-forward, dry-run e diagnóstico de erros comuns.
10. Antipadrões & checklist — O que NÃO fazer e um checklist de segurança/confiabilidade/observabilidade.

Exemplos

Veja as seções abaixo para exemplos completos e executáveis. Referências rápidas:

Tarefa	Ir para
YAML completo de Deployment de produção	Padrões Principais de Workload
Configuração de probes	Probes
Configuração RBAC com privilégio mínimo	RBAC
Depurar um CrashLoopBackOff	Cheatsheet de Depuração kubectl
Autoscaling	HPA

---

Padrões Principais de Workload

Deployment — Template de Produção

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: my-namespace
  labels:
    app: my-app
    version: "1.0.0"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1          # Permite 1 pod extra durante a atualização
      maxUnavailable: 0    # Nunca reduz abaixo da contagem desejada
  template:
    metadata:
      labels:
        app: my-app
        version: "1.0.0"
    spec:
      # Contexto de segurança no nível do pod
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001

      # Desligamento gracioso
      terminationGracePeriodSeconds: 30

      containers:
        - name: my-app
          image: ghcr.io/org/my-app:1.0.0   # Nunca use :latest
          imagePullPolicy: IfNotPresent

          ports:
            - containerPort: 8080
              protocol: TCP

          # Requests E limits de recursos são ambos obrigatórios
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"

          # Contexto de segurança do contêiner
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL

          # Probes (veja a seção Probes abaixo)
          startupProbe:
            httpGet:
              path: /health
              port: 8080
            failureThreshold: 30
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 0
            periodSeconds: 30
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
            failureThreshold: 2

          # Ambiente a partir de ConfigMap e Secret
          envFrom:
            - configMapRef:
                name: my-app-config
          env:
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: my-app-secrets
                  key: db-password

          # Diretório tmp gravável quando readOnlyRootFilesystem: true
          volumeMounts:
            - name: tmp
              mountPath: /tmp

      volumes:
        - name: tmp
          emptyDir: {}

---

Probes — Liveness, Readiness, Startup

Entender quando usar cada probe é crítico:

Probe	Ação em Falha	Uso
startupProbe	Mata o contêiner se for lento para iniciar	Apps de inicialização lenta (JVM, Python)
livenessProbe	Reinicia o contêiner	Detecção de deadlock / processo travado
readinessProbe	Remove dos endpoints do Service	Indisponibilidade temporária (reconexão DB)

# Padrão correto: startupProbe cobre inicialização lenta,
# então liveness/readiness assumem o controle
startupProbe:
  httpGet:
    path: /health
    port: 8080
  failureThreshold: 30  # 30 * 5s = 150s de tempo máximo de inicialização
  periodSeconds: 5

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  periodSeconds: 30
  failureThreshold: 3   # 3 * 30s = 90s antes de reiniciar

readinessProbe:
  httpGet:
    path: /ready         # Endpoint separado: verifica DB, cache, etc.
    port: 8080
  periodSeconds: 10
  failureThreshold: 2

# ERRADO: initialDelaySeconds sem startupProbe
# Se o app leva 60s para iniciar, configure uma startupProbe
livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 60   # RUIM: Espera arbitrária, condição de corrida

---

Services e Ingress

Tipos de Service

# ClusterIP (padrão) — apenas interno
apiVersion: v1
kind: Service
metadata:
  name: my-app
  namespace: my-namespace
spec:
  selector:
    app: my-app
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP
  type: ClusterIP

# LoadBalancer — tráfego externo (provedores de nuvem)
spec:
  type: LoadBalancer
  ports:
    - port: 443
      targetPort: 8080

Ingress com TLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  namespace: my-namespace
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - myapp.example.com
      secretName: my-app-tls
  rules:
    - host: myapp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80

---

ConfigMaps e Secrets

ConfigMap — Configuração não sensível

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-app-config
  namespace: my-namespace
data:
  LOG_LEVEL: "info"
  APP_ENV: "production"
  MAX_CONNECTIONS: "100"
  # Montar como arquivo para configuração complexa
  app.yaml: |
    server:
      port: 8080
      timeout: 30s

# Montar ConfigMap como arquivo
volumes:
  - name: config
    configMap:
      name: my-app-config
      items:
        - key: app.yaml
          path: app.yaml
volumeMounts:
  - name: config
    mountPath: /etc/app
    readOnly: true

Secrets — Dados sensíveis

# Criar secret a partir de literal (CLI, depois armazenar em Vault/SOPS)
kubectl create secret generic my-app-secrets \
  --from-literal=db-password='s3cr3t' \
  --namespace=my-namespace \
  --dry-run=client -o yaml | kubectl apply -f -

apiVersion: v1
kind: Secret
metadata:
  name: my-app-secrets
  namespace: my-namespace
type: Opaque
# Valores são codificados em base64 (NÃO criptografados — use Sealed Secrets ou ESO para criptografia real)
data:
  db-password: czNjcjN0  # base64 de 's3cr3t'

Importante: Secrets Kubernetes brutos são apenas codificados em base64, não criptografados em repouso, a menos que seu cluster tenha criptografia configurada. Use Sealed Secrets ou External Secrets Operator para produção.

---

Requests e Limits de Recursos

resources:
  requests:       # O scheduler usa isso para posicionar o pod
    cpu: "100m"   # 100 millicores = 0.1 CPU
    memory: "128Mi"
  limits:         # O contêiner é morto/acima disso
    cpu: "500m"
    memory: "256Mi"

Regras práticas:

Tipo de Workload	Request de CPU	Request de Memória	Observações
API Web	100–250m	128–256Mi	Definir limits 2-4x os requests
Worker/consumidor	250–500m	256–512Mi	Memory limit = request para previsibilidade
App JVM	500m–1	512Mi–2Gi	Deixar margem acima de -Xmx para overhead da JVM
Sidecar	10–50m	32–64Mi	Manter mínimo

# ERRADO: Sem requests ou limits — agendamento imprevisível, evicções OOM
containers:
  - name: app
    image: myapp:latest
    # Faltando resources: {} — isso é perigoso em produção

# ERRADO: Limits sem requests — requests assumem o valor dos limits, super-reserva capacidade
resources:
  limits:
    cpu: "2"
    memory: "1Gi"
  # requests ausentes — assumirão os valores dos limits

---

RBAC — Roles e ServiceAccounts

Princípio do Menor Privilégio

Dois padrões dependendo se o app chama a API do Kubernetes:

Padrão A — App NÃO precisa da API do Kubernetes (maioria dos apps)

Desabilitar a montagem automática de token no ServiceAccount. A Role/RoleBinding não são necessárias.

# ServiceAccount com token desabilitado — padrão mais seguro
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app-sa
  namespace: my-namespace
automountServiceAccountToken: false   # Nenhum token da API K8s injetado nos pods

# Referência no Deployment — sem token, sem acesso à API
spec:
  template:
    spec:
      serviceAccountName: my-app-sa
      automountServiceAccountToken: false   # Garantia dupla: também definido no nível do pod

Padrão B — App PRECISA da API do Kubernetes (operadores, controladores, observadores de configuração)

Habilitar o token e conceder apenas as permissões realmente necessárias.

# 1. ServiceAccount — habilitar token para esta SA
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app-sa
  namespace: my-namespace
automountServiceAccountToken: true    # Token necessário: app chama a API K8s

# 2. Role — conceder apenas o que o app precisa (escopo no namespace)
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: my-app-role
  namespace: my-namespace
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "watch"]    # Somente leitura, recurso específico
  - apiGroups: [""]
    resources: ["secrets"]
    resourceNames: ["my-app-secrets"]  # Restrito a um secret específico pelo nome
    verbs: ["get"]

# 3. Vincular Role ao ServiceAccount
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: my-app-rolebinding
  namespace: my-namespace
subjects:
  - kind: ServiceAccount
    name: my-app-sa
    namespace: my-namespace
roleRef:
  kind: Role
  apiGroup: rbac.authorization.k8s.io
  name: my-app-role

# 4. Referenciar SA no Deployment
spec:
  template:
    spec:
      serviceAccountName: my-app-sa
      # automountServiceAccountToken assume true da SA — token é injetado

---

Horizontal Pod Autoscaler (HPA)

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
  namespace: my-namespace
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2      # Sempre pelo menos 2 para HA
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70    # Escalar para cima quando CPU média > 70%
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

O HPA requer que resources.requests seja definido em todos os contêineres — ele calcula a utilização como current / request.

---

PodDisruptionBudget (PDB)

Evitar que muitos pods caiam durante drenagem de nós ou atualizações rolling:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: my-app-pdb
  namespace: my-namespace
spec:
  minAvailable: 2           # OU use maxUnavailable: 1
  selector:
    matchLabels:
      app: my-app

---

Namespaces e Multitenência

# Criar namespace com quotas de recursos
kubectl create namespace my-namespace

# Aplicar ResourceQuota para limitar o consumo do namespace
kubectl apply -f - <<EOF
apiVersion: v1
kind: ResourceQuota
metadata:
  name: my-namespace-quota
  namespace: my-namespace
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 4Gi
    limits.cpu: "8"
    limits.memory: 8Gi
    pods: "20"
EOF

---

Jobs e CronJobs

# Job único (migração de DB, processamento de dados)
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  namespace: my-namespace
spec:
  backoffLimit: 3          # Tentar novamente até 3 vezes em caso de falha
  ttlSecondsAfterFinished: 3600   # Auto-excluir após 1h
  template:
    spec:
      restartPolicy: OnFailure    # Nunca para Jobs (não Always)
      containers:
        - name: migrate
          image: ghcr.io/org/my-app:1.0.0
          command: ["python", "manage.py", "migrate"]