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 responder
• readinessProbe: 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

---

🛠️ Pruébalo ahora: YAML Formatter | YAML Linter — 100% gratis, todo se procesa en tu navegador. Sin subir datos.

---