Inicio / Plantilla de Deployment

Plantilla YAML de Deployment de Kubernetes explicada

Guía de referencia · cada campo, para qué sirve y qué pasa si lo dejas por defecto.

Un Deployment es el recurso que usa la inmensa mayoría de aplicaciones sin estado en Kubernetes: le dices cuántas réplicas de tu Pod quieres y con qué imagen, y el controlador se encarga de mantener ese número corriendo, sustituyendo Pods que fallan y aplicando actualizaciones de forma controlada. Este es un ejemplo mínimo pero completo:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mi-app
  labels:
    app: mi-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mi-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
  template:
    metadata:
      labels:
        app: mi-app
    spec:
      containers:
        - name: mi-app
          image: nginx:1.25
          ports:
            - containerPort: 80
              protocol: TCP
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 250m
              memory: 256Mi

Campo por campo

apiVersion: apps/v1 — la versión estable de la API donde vive Deployment desde Kubernetes 1.9. No hay razón para usar otra en un clúster moderno.

spec.replicas — cuántos Pods idénticos quieres corriendo a la vez. Si más adelante añades un HorizontalPodAutoscaler apuntando a este Deployment, este número se convierte en un mínimo/punto de partida que el HPA puede modificar automáticamente.

spec.selector.matchLabels — el criterio que usa el Deployment para saber qué Pods son «suyos». Debe coincidir exactamente con las labels definidas en spec.template.metadata.labels. Es un campo inmutable: si lo cambias después de crear el Deployment, Kubernetes rechazará la actualización.

spec.strategy — cómo se sustituyen los Pods viejos por los nuevos al actualizar la imagen. RollingUpdate (el valor por defecto) va reemplazando Pods progresivamente, controlando cuántos puede haber de más (maxSurge) y cuántos pueden faltar (maxUnavailable) durante la transición. Recreate borra todos los Pods antiguos antes de crear los nuevos — útil solo cuando tu app no soporta dos versiones corriendo a la vez.

spec.template — la plantilla del Pod que el Deployment va a crear. Todo lo que va dentro (imagen, puertos, variables de entorno, recursos) es exactamente lo mismo que definirías en un Pod suelto, pero aquí se replica automáticamente.

resources.requests / resources.limits — requests es lo que el Pod pide para poder ser programado en un nodo (el scheduler solo coloca el Pod en un nodo que tenga esa CPU/memoria libre); limits es el techo que el kubelet hace cumplir — si el Pod supera el límite de memoria, se reinicia (OOMKilled); si supera el de CPU, simplemente se le limita (throttling), no se mata.

Errores habituales al escribir un Deployment a mano

• Olvidar que selector y las labels del template deben coincidir letra por letra — es la causa más común de un Deployment que crea Pods pero un Service que nunca los encuentra.
• Mezclar tabuladores y espacios en el YAML — Kubernetes (como cualquier parser YAML estándar) rechaza los tabuladores en la indentación.
• No poner resources.limits — sin ellos, un Pod con una fuga de memoria puede consumir toda la memoria del nodo y afectar a otros Pods.

Si prefieres no escribirlo a mano, nuestro generador de manifiestos de Kubernetes construye este mismo YAML a partir de un formulario, con la indentación garantizada y sin campos obligatorios olvidados.

← Volver al generador