YAML para Kubernetes: Padrões Essenciais de Manifestos

O Kubernetes é configurado inteiramente através de manifestos YAML. Cada pod, deployment, serviço e ingress é definido em YAML. Dominar estes padrões é essencial para qualquer pessoa que trabalhe com orquestração de contentores. Este guia abrange os tipos de recursos mais importantes com exemplos prontos para produção.

Os Quatro Campos Obrigatórios

Cada manifesto Kubernetes necessita de:

apiVersion: apps/v1      # Versão da API para este tipo de recurso
kind: Deployment          # Tipo de recurso
metadata:                 # Identificação do recurso
  name: my-app
  namespace: production
  labels:
    app: my-app
spec:                     # Especificação do estado desejado
  # ... configuração específica do recurso

Deployment

O recurso mais comum — gere um conjunto de pods idênticos:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  labels:
    app: api-server
    environment: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: myapp/api:v1.2.3
          ports:
            - containerPort: 8080
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: url
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5

Padrões Essenciais

Defina sempre pedidos e limites de recursos: Sem eles, um único pod pode consumir todos os recursos do nó.

Configure sempre sondas de saúde:

livenessProbe: Reinicia o pod se este deixar de responder
readinessProbe: Deixa de enviar tráfego até o pod estar pronto

Utilize tags de imagem específicas: Nunca utilize latest em produção — torna os rollbacks impossíveis.

Service

Expõe pods ao tráfego de rede:

apiVersion: v1
kind: Service
metadata:
  name: api-server
spec:
  type: ClusterIP
  selector:
    app: api-server
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP

Tipos de Service:

ClusterIP (predefinição): Acesso interno ao cluster apenas
NodePort: Expõe em cada IP de nó numa porta estática
LoadBalancer: Aprovisiona um balanceador de carga na nuvem
ExternalName: Mapeia para um nome DNS

ConfigMap e Secret

ConfigMap (dados não sensíveis)

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: "info"
  MAX_CONNECTIONS: "100"
  config.yaml: |
    server:
      port: 8080
      timeout: 30s

Secret (dados sensíveis)

apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
type: Opaque
stringData:
  url: "postgres://user:password@db:5432/myapp"
  api-key: "sk-1234567890"

Utilização em Pods

# Como variáveis de ambiente
env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: LOG_LEVEL

# Como ficheiro montado
volumes:
  - name: config
    configMap:
      name: app-config

Ingress

Encaminha tráfego HTTP externo para serviços:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.example.com
      secretName: tls-secret
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-server
                port:
                  number: 80

Horizontal Pod Autoscaler

Escala pods com base em CPU ou métricas personalizadas:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-server-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-server
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Erros Comuns

1. Erros de Indentação

A indentação YAML é crítica no Kubernetes. Um espaço mal colocado altera completamente a estrutura. Valide os seus manifestos com o nosso Validador YAML.

2. Discrepância de Labels

O seletor do Service deve corresponder exatamente às labels do Pod. Uma discrepância significa que o Service não consegue encontrar nenhum pod para encaminhar tráfego.

3. Limites de Recursos em Falta

Pods sem limites de recursos podem privar outras cargas de trabalho. Inclua sempre tanto pedidos (mínimo garantido) como limites (máximo permitido).

4. Tags de Imagem Mutáveis

Utilizar latest ou outras tags mutáveis torna os rollbacks impossíveis e as implementações imprevisíveis. Fixe versões específicas ou utilize digests imutáveis.

Manifestos Multi-Documento

Combine recursos relacionados num ficheiro utilizando --- como separador de documento:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  # ... especificação do deployment
---
apiVersion: v1
kind: Service
metadata:
  name: api-server
spec:
  # ... especificação do service

Para mais informações sobre padrões de sintaxe YAML, consulte o nosso tutorial de sintaxe YAML.

FAQ

Devo escrever YAML do Kubernetes à mão ou utilizar geradores?

Comece por escrever YAML à mão para compreender a estrutura. Para produção, utilize ferramentas como Helm (manifestos com template), Kustomize (personalização baseada em sobreposições) ou CDK8s (geração baseada em código). Estas ferramentas reduzem a repetição e permitem configuração específica por ambiente sem duplicar manifestos.

Como depuro erros de YAML no Kubernetes?

Utilize kubectl apply --dry-run=client -f manifest.yaml para validar sem aplicar. Para erros de sintaxe, kubectl explain deployment.spec.template.spec.containers mostra a estrutura esperada. As ferramentas kubeval e kubeconform validam contra os esquemas da API do Kubernetes antes da implementação.

Recursos Relacionados

Validador YAML — Valide manifestos do Kubernetes
YAML para Docker Compose — Padrões YAML do Docker
Boas Práticas de Linting YAML — Detete erros antes de implementar