YAML para Kubernetes: Patrones Esenciales de Manifiestos
Kubernetes se configura completamente a través de manifiestos YAML. Cada pod, deployment, service e ingress se define en YAML. Dominar estos patrones es esencial para cualquiera que trabaje con orquestación de contenedores. Esta guía cubre los tipos de recursos más importantes con ejemplos listos para producción.
Los Cuatro Campos Obligatorios
Cada manifiesto de Kubernetes necesita:
apiVersion: apps/v1 # API version for this resource type
kind: Deployment # Resource type
metadata: # Resource identification
name: my-app
namespace: production
labels:
app: my-app
spec: # Desired state specification
# ... resource-specific configuration
Deployment
El recurso más común — administra un 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
Patrones Clave
Siempre establece requests y limits de recursos: Sin ellos, un solo pod puede consumir todos los recursos del nodo.
Siempre configura sondas de salud:
livenessProbe: Reinicia el pod si deja de responderreadinessProbe: Deja de enviar tráfico hasta que el pod esté listo
Usa tags de imagen específicos: Nunca uses latest en producción — hace imposibles los rollbacks.
Service
Expone los pods al tráfico de red:
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 (predeterminado): Solo acceso interno al clúster
- NodePort: Expone en cada IP de nodo en un puerto estático
- LoadBalancer: Aprovisiona un balanceador de carga en la nube
- ExternalName: Mapea a un nombre DNS
ConfigMap y Secret
ConfigMap (datos no sensibles)
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
LOG_LEVEL: "info"
MAX_CONNECTIONS: "100"
config.yaml: |
server:
port: 8080
timeout: 30s
Secret (datos sensibles)
apiVersion: v1
kind: Secret
metadata:
name: db-credentials
type: Opaque
stringData:
url: "postgres://user:password@db:5432/myapp"
api-key: "sk-1234567890"
Uso en Pods
# As environment variables
env:
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: app-config
key: LOG_LEVEL
# As a mounted file
volumes:
- name: config
configMap:
name: app-config
Ingress
Enruta el tráfico HTTP externo a los 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 basándose en CPU o 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
Errores Comunes
1. Errores de Indentación
La indentación YAML es crítica en Kubernetes. Un espacio mal colocado cambia la estructura completamente. Valida tus manifiestos con nuestro Validador YAML.
2. Discrepancia de Labels
El selector del Service debe coincidir exactamente con los labels del Pod. Una discrepancia significa que el Service no puede encontrar pods a los cuales enrutar tráfico.
3. Limits de Recursos Faltantes
Los pods sin limits de recursos pueden privar de recursos a otras cargas de trabajo. Siempre incluye tanto requests (mínimo garantizado) como limits (máximo permitido).
4. Tags de Imagen Mutables
Usar latest u otros tags mutables hace imposibles los rollbacks y los despliegues impredecibles. Fija versiones específicas o usa digests inmutables.
Manifiestos Multi-Documento
Combina recursos relacionados en un archivo usando --- como separador de documentos:
apiVersion: apps/v1
kind: Deployment
metadata:
name: api-server
spec:
# ... deployment spec
---
apiVersion: v1
kind: Service
metadata:
name: api-server
spec:
# ... service spec
Para más información sobre patrones de sintaxis YAML, consulta nuestro tutorial de sintaxis YAML.
FAQ
¿Debería escribir YAML de Kubernetes a mano o usar generadores?
Comienza escribiendo YAML a mano para entender la estructura. Para producción, usa herramientas como Helm (manifiestos con plantillas), Kustomize (personalización basada en overlays) o CDK8s (generación basada en código). Estas herramientas reducen la repetición y permiten configuración específica por entorno sin duplicar manifiestos.
¿Cómo depuro errores en YAML de Kubernetes?
Usa kubectl apply --dry-run=client -f manifest.yaml para validar sin aplicar. Para errores de sintaxis, kubectl explain deployment.spec.template.spec.containers muestra la estructura esperada. Las herramientas kubeval y kubeconform validan contra los esquemas de la API de Kubernetes antes del despliegue.
Recursos Relacionados
- Validador YAML — Valida manifiestos de Kubernetes
- YAML para Docker Compose — Patrones YAML de Docker
- Mejores Prácticas de Linting YAML — Detecta errores antes del despliegue