Saltar al contenido
Curso yaml completo

Variables YAML: Guía Completa con Ejemplos 2026

24/06/2023

Actualizado el 07 de febrero de 2026

Dominar las variables YAML es un paso fundamental para cualquiera que trabaje con ficheros de configuración, especialmente en el mundo del IoT y la domótica. En 2026, donde la automatización es la norma, entender cómo usar variables te permitirá escribir código más limpio, mantenible y escalable. Este capítulo te guiará desde los conceptos básicos hasta las aplicaciones avanzadas, convirtiéndose en tu referencia definitiva.

Las variables nos ayudan a evitar la repetición (principio DRY: «Don’t Repeat Yourself») y a gestionar datos sensibles de forma segura, algo crucial en sistemas como Home Assistant. Si estás empezando, te recomiendo echar un vistazo a nuestro curso completo de YAML para asentar las bases.

¿Qué son realmente las «Variables» en YAML?

Aunque a menudo hablamos de «variables», YAML en su forma más pura no tiene un concepto de variable como un lenguaje de programación tradicional. En su lugar, utiliza un sistema de Anclas (&) y Alias (*) para reutilizar fragmentos de código. Sin embargo, en la práctica, la mayoría de las plataformas que usan YAML (como Home Assistant, Ansible o Docker) extienden su funcionalidad para permitir el uso de variables de una manera más intuitiva.

En este artículo cubriremos ambos conceptos: las anclas nativas de YAML y las variables específicas de cada plataforma, que son las que más usarás en tu día a día.

Sintaxis YAML Nativa: Anclas y Alias

La forma nativa de crear una «variable» o un valor reutilizable en YAML es mediante anclas. Defines un valor una vez con un ancla (&nombre_ancla) y luego lo reutilizas en cualquier otro lugar del mismo documento con un alias (*nombre_ancla).

Esto es increíblemente útil para centralizar valores que se repiten, como direcciones IP, nombres de usuario o configuraciones de dispositivos. La sintaxis YAML es muy estricta con la indentación, así que presta atención.

Ejemplo práctico: Imagina que tienes varios sensores en la misma habitación. En lugar de escribir «Salón» cada vez, puedes usar un ancla.

# Definimos un ancla para la ubicación
default_location: &location Salon

sensor_temperatura:
  name: "Temperatura Salón"
  location: *location
  
sensor_humedad:
  name: "Humedad Salón"
  location: *location

sensor_movimiento:
  name: "Movimiento Salón"
  location: *location

Si en el futuro decides cambiar el nombre de «Salón» a «Sala de Estar», solo tienes que modificarlo en un único lugar. Para profundizar en esta técnica, consulta nuestra guía sobre anclas y alias en YAML.

Variables YAML en Domótica: Home Assistant 2026

Donde realmente brilla el uso de variables es en plataformas como Home Assistant. Aquí, el concepto se expande para interactuar con el sistema, las plantillas y los ficheros externos, haciendo la configuración YAML mucho más potente.

Gestión de Secretos y Datos Sensibles

Nunca, bajo ningún concepto, debes escribir contraseñas, tokens o claves API directamente en tus archivos de configuración principales. Para eso, Home Assistant utiliza un fichero especial llamado secrets.yaml.

Dentro de tu configuration.yaml, puedes llamar a estas variables con la directiva !secret.

Ejemplo en secrets.yaml:

# Contiene información sensible
api_key_openweathermap: TU_API_KEY_AQUI
user_mqtt: mi_usuario_mqtt
password_mqtt: mi_contraseña_segura

Ejemplo de uso en configuration.yaml:

weather:
  - platform: openweathermap
    api_key: !secret api_key_openweathermap

mqtt:
  broker: core-mosquitto
  username: !secret user_mqtt
  password: !secret password_mqtt

Este método es esencial para poder compartir tu configuración sin exponer datos críticos. Aprende a configurarlo paso a paso en nuestra guía sobre el archivo secrets.yaml.

Variables en Plantillas YAML para Automatizaciones Dinámicas

Las plantillas YAML son el corazón de la automatización YAML en Home Assistant. Permiten crear respuestas y acciones dinámicas basadas en el estado de las entidades.

Imagina una automatización que te notifica cuando se abre una puerta. En lugar de crear una automatización para cada puerta, puedes usar una sola con variables de plantilla.

automation:
  - alias: "Notificación de puerta abierta"
    trigger:
      - platform: state
        entity_id:
          - binary_sensor.puerta_entrada
          - binary_sensor.puerta_terraza
        to: 'on'
    action:
      - service: notify.mobile_app_mi_telefono
        data:
          title: "¡Alerta de Seguridad!"
          message: "La {{ trigger.to_state.attributes.friendly_name }} se ha abierto."

En este ejemplo, {{ trigger.to_state.attributes.friendly_name }} es una variable que se sustituirá por el nombre amistoso del sensor que disparó la automatización («Puerta de Entrada» o «Puerta Terraza»).

Variables de Entorno en Docker y CI/CD

Fuera de la domótica, las variables de entorno son el método más común para parametrizar configuraciones, especialmente en contenedores con Docker.

Por ejemplo, al configurar Zigbee2MQTT a través de Docker Compose, puedes definir el puerto del coordinador Zigbee como una variable de entorno. Esto facilita la migración o el cambio de hardware sin tocar el archivo principal.

Ejemplo de docker-compose.yml:

version: '3.8'
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    environment:
      - TZ=${SYSTEM_TIMEZONE}
    ports:
      - 8080:8080
    devices:
      - /dev/ttyACM0:/dev/ttyACM0
    restart: unless-stopped

Aquí, ${SYSTEM_TIMEZONE} se leerá de un archivo .env en el mismo directorio o de las variables de entorno del sistema operativo, permitiendo una configuración flexible y portable.

Buenas Prácticas para el Uso de Variables YAML en 2026

  • Nombres Descriptivos: Usa nombres claros para tus anclas y variables (ej: &main_bedroom_light en lugar de &luz1).
  • Centraliza Valores Comunes: Si un valor se usa más de dos veces, conviértelo en un ancla.
  • Seguridad Primero: Utiliza siempre ficheros como secrets.yaml para información sensible. ¡Nunca subas claves a repositorios públicos!
  • Modulariza tu Configuración: Usa directivas como !include, !include_dir_list o !include_dict para dividir grandes archivos YAML en partes más manejables. Es una práctica estándar en configuraciones complejas de Home Assistant.
  • Comenta tu Código: Explica el propósito de tus variables más complejas. Tu «yo» del futuro te lo agradecerá.
  • Valida tu Sintaxis: Antes de desplegar, utiliza validadores online o las herramientas integradas en editores como Visual Studio Code para comprobar que la sintaxis YAML es correcta.

Dominar las variables en YAML te abrirá un nuevo mundo de posibilidades, permitiéndote crear configuraciones robustas, seguras y fáciles de mantener para todos tus proyectos de IoT y automatización.