Documentos múltiples (---)

Un archivo de YAML puede contener varios documentos independientes separados por la línea especial ---. Cada bloque funciona como un documento distinto, lo que ayuda a agrupar configuraciones relacionadas sin dividirlas en múltiples archivos.

8.1 ¿Cuándo usar documentos múltiples?

  • Agrupar configuraciones relacionadas que comparten contexto.
  • Definir varios recursos de Kubernetes (Pods, Services, Deployments) en un solo archivo.
  • Manejar configuraciones complejas donde conviene centralizar todo en un fichero.

8.2 Ejemplo simple

---
producto:
  codigo: 1
  descripcion: Teclado
  precio: 15000
---
producto:
  codigo: 2
  descripcion: Mouse
  precio: 9000

Cada bloque separado por --- representa un documento distinto. Algunos parsers leerán solo el primero, mientras que otros procesarán todos.

8.3 Ejemplo en Kubernetes

En Kubernetes es habitual definir varios recursos en una sola entrega.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mi-config
data:
  DB_HOST: localhost
  DB_PORT: "5432"
---
apiVersion: v1
kind: Service
metadata:
  name: mi-servicio
spec:
  selector:
    app: mi-app
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mi-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mi-app
  template:
    metadata:
      labels:
        app: mi-app
    spec:
      containers:
        - name: mi-app
          image: mi-app:1.0
          ports:
            - containerPort: 8080

De esta forma podemos aplicar todo con un solo comando: kubectl apply -f recursos.yaml.

8.4 Separador final (...)

Además de ---, YAML define ... para indicar explícitamente el final de un documento. Aunque es opcional, puede ser útil en flujos donde se encadenan múltiples documentos.

---
nombre: Juan
edad: 30
...
---
nombre: Laura
edad: 25
...

8.5 Buenas prácticas

  • Usa --- para separar documentos relacionados manteniendo un orden lógico (ej.: ConfigMaps → Services → Deployments).
  • Documenta con comentarios qué representa cada bloque para facilitar el mantenimiento.
  • No mezcles configuraciones sin relación; dividir en varios archivos puede ser más claro.
  • Comprueba que la herramienta que procesará el archivo soporte múltiples documentos.

8.6 Ventajas

  • Agrupar múltiples configuraciones en un solo archivo.
  • Facilitar despliegues en entornos DevOps con un único apply o carga.
  • Reducir la cantidad de archivos sueltos y mejorar la organización.

8.7 Limitaciones

  • No todos los parsers YAML admiten múltiples documentos.
  • Un archivo demasiado extenso puede volverse difícil de leer si contiene muchos bloques.

En resumen, con --- podemos gestionar varios documentos en un mismo archivo YAML, una técnica clave en Kubernetes, Docker Compose avanzado y pipelines CI/CD donde conviene centralizar configuraciones.

Retornar