YAML para Kubernetes: Padrões Essenciais de Manifesto
O Kubernetes é configurado inteiramente por meio de manifestos YAML. Cada pod, deployment, service e ingress é definido em YAML. Dominar esses padrões é essencial para qualquer pessoa que trabalhe com orquestração de contêineres. Este guia aborda os tipos de recursos mais importantes com exemplos prontos para produção.
Os Quatro Campos Obrigatórios
Todo manifesto do Kubernetes precisa 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 — gerencia 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 Importantes
Sempre defina requests e limits de recursos: Sem eles, um único pod pode consumir todos os recursos do nó.
Sempre configure probes de integridade:
livenessProbe: Reinicia o pod se ele parar de responderreadinessProbe: Para de enviar tráfego até que o pod esteja pronto
Use tags de imagem específicas: Nunca use latest em produção — isso torna 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 (padrão): Acesso apenas dentro do cluster
- NodePort: Expõe no IP de cada nó em uma porta estática
- LoadBalancer: Provisiona 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"
Uso em Pods
# Como variáveis de ambiente
env:
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: app-config
key: LOG_LEVEL
# Como arquivo montado
volumes:
- name: config
configMap:
name: app-config
Ingress
Roteia tráfego HTTP externo para services:
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 posicionado altera toda a estrutura. Valide seus manifestos com nosso Validador YAML.
2. Labels Incompatíveis
O selector do Service deve corresponder exatamente aos labels do Pod. Uma incompatibilidade significa que o Service não consegue encontrar pods para direcionar o tráfego.
3. Limits de Recursos Ausentes
Pods sem limits de recursos podem prejudicar outros workloads. Sempre inclua tanto requests (mínimo garantido) quanto limits (máximo permitido).
4. Tags de Imagem Mutáveis
Usar latest ou outras tags mutáveis torna rollbacks impossíveis e deploys imprevisíveis. Fixe versões específicas ou use digests imutáveis.
Manifestos Multi-Documento
Combine recursos relacionados em um único arquivo usando --- como separador de documentos:
apiVersion: apps/v1
kind: Deployment
metadata:
name: api-server
spec:
# ... spec do deployment
---
apiVersion: v1
kind: Service
metadata:
name: api-server
spec:
# ... spec do service
Para saber mais sobre padrões de sintaxe YAML, veja nosso tutorial de sintaxe YAML.
FAQ
Devo escrever YAML do Kubernetes manualmente ou usar geradores?
Comece escrevendo YAML manualmente para entender a estrutura. Para produção, use ferramentas como Helm (manifestos com templates), Kustomize (personalização baseada em overlays) ou CDK8s (geração baseada em código). Essas ferramentas reduzem a repetição e permitem configurações específicas por ambiente sem duplicar manifestos.
Como depuro erros de YAML no Kubernetes?
Use 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 schemas da API do Kubernetes antes do deploy.
Recursos Relacionados
- Validador YAML — Valide manifestos Kubernetes
- YAML para Docker Compose — Padrões YAML para Docker
- Boas Práticas de Linting YAML — Detecte erros antes do deploy