Solución de Conflictos de Precedencia de Variables en Configuraciones de Ansible

Los problemas de precedencia de variables generalmente se manifiestan como una pregunta simple: "¿Por qué Ansible usó ese valor?" Un puerto es 8080 cuando esperabas 80. Un rol despliega la versión 1.6 aunque el playbook dice 1.5. Un trabajo de CI pasa -e environment=prod, y de repente la mitad de tu cuidadosa estructura de inventario deja de importar.

La solución rara vez es memorizar cada línea de la tabla de precedencia de Ansible. La solución es reducir las posibles fuentes, inspeccionar el valor en el host afectado y mover la variable a la capa correcta. Esta guía se centra en ese flujo de trabajo.

Entendiendo la Precedencia de Variables en Ansible

Ansible evalúa las variables en un orden específico, conocido como el orden de precedencia de variables. El valor que aparece más tarde en esta lista anula cualquier valor definido anteriormente para la misma variable. Es esencial recordar este orden al solucionar problemas.

Aquí hay una forma simplificada de pensar sobre las fuentes comunes, desde más fáciles de anular hasta más difíciles de anular:

Valores por Defecto del Rol: Variables definidas en el archivo defaults/main.yml de un rol. Tienen la precedencia más baja y están destinadas a valores predeterminados que se pueden anular fácilmente.
Variables de Inventario (todo o grupo): Variables definidas en archivos de inventario usando la palabra clave vars: para grupos específicos o todos los hosts.
Variables de Inventario (host): Variables definidas directamente para un host específico dentro del archivo de inventario.
Variables del Playbook: Variables definidas usando la palabra clave vars: directamente dentro de un playbook.
Variables del Rol: Variables definidas en el archivo vars/main.yml de un rol. Tienen mayor precedencia que los valores por defecto.
Include Vars y Archivos Vars: Variables cargadas explícitamente por un play o una tarea.
Variables a Nivel de Tarea, Variables de Bloque, Resultados Registrados y Hechos: Pueden afectar tareas posteriores y pueden ser fáciles de pasar por alto porque viven dentro del flujo de ejecución.
Variables Set Fact: Variables definidas usando el módulo set_fact tienen alta precedencia para la ejecución actual.
Extra Vars: Variables pasadas en la línea de comandos usando -e o --extra-vars son intencionalmente muy fuertes y anulan casi todo lo demás.

Este es un modelo de trabajo, no la tabla completa. La documentación oficial de Ansible tiene la lista exhaustiva, incluyendo parámetros de roles, parámetros de include, comportamiento de plugins de inventario y otros casos extremos. Para depuración en producción, compara tu caso con las reglas oficiales de precedencia de variables.

Escenarios Comunes de Conflictos de Variables y Soluciones

Veamos algunos escenarios comunes donde pueden ocurrir conflictos de precedencia de variables y cómo diagnosticarlos y resolverlos.

Escenario 1: Variables de Grupo vs. Variables de Host

A menudo, puedes definir una configuración general para un grupo de servidores (por ejemplo, app_servers) y luego una configuración específica para un servidor dentro de ese grupo (por ejemplo, webserver01).

Ejemplo de Inventario (inventory.ini):

[app_servers]
webserver01.example.com
webserver02.example.com

[databases]
dbserver01.example.com

[app_servers:vars]
http_port = 8080

[webserver01.example.com:vars]
http_port = 80

Resultado Esperado: Para webserver01.example.com, http_port debería ser 80. Para webserver02.example.com, que está en app_servers pero no está definido específicamente, http_port debería ser 8080.

Problema: Si http_port no se comporta como se espera, el problema probablemente es un malentendido sobre qué definición está tomando Ansible.

Pasos de Diagnóstico:

Usa el módulo debug: Agrega una tarea debug en tu playbook para mostrar explícitamente el valor de la variable.
```
- name: Mostrar http_port
  debug:
    msg: "El http_port para este host es {{ http_port }}"
```
Usa ansible-inventory --host <nombrehost>: Esta utilidad de línea de comandos muestra todas las variables asociadas con un host específico, incluyendo su precedencia.
```
ansible-inventory --host webserver01.example.com --list --yaml
```
Busca la variable http_port y nota dónde está definida. La salida a menudo indicará la fuente de la variable.

Solución: En este caso, las variables de host ([webserver01.example.com:vars]) tienen mayor precedencia que las variables de grupo ([app_servers:vars]), por lo que http_port = 80 anulará correctamente http_port = 8080 para webserver01.example.com.

Escenario 2: Variables del Playbook vs. Variables del Rol

Puedes definir una configuración en la sección vars de tu playbook y también en un rol que el playbook incluye.

Ejemplo de Playbook (deploy_app.yml):

--- 
- name: Desplegar Aplicación Web
  hosts: webservers
  vars:
    app_version: "1.5"
    db_host: "prod.db.local"
  roles:
    - common
    - webapp

Ejemplo de Rol (webapp/vars/main.yml):

app_version: "1.6"
db_host: "shared.db.local"

Resultado Esperado: Cuando este playbook se ejecute, ¿cuáles serán app_version y db_host?

Pasos de Diagnóstico:

Módulo debug: Como antes, usa el módulo debug para inspeccionar los valores.

- name: Mostrar app_version y db_host
  debug:
    msg: "Versión de App: {{ app_version }}, Host de DB: {{ db_host }}"

Examina la estructura del rol: Asegúrate de que vars/main.yml sea parte del rol incluido y que no haya otros archivos vars/main.yml dentro de las dependencias del rol que puedan tener precedencia.

Solución: Según las reglas de precedencia, las Variables del Rol (webapp/vars/main.yml) tienen mayor precedencia que las Variables del Playbook (vars: en deploy_app.yml). Por lo tanto:

app_version será 1.6.
db_host será shared.db.local.

Si pretendías que las variables del playbook tuvieran prioridad, necesitarías mover estas definiciones a un nivel de precedencia más alto, como extra_vars o usar vars_files con una precedencia más alta.

Escenario 3: Anulación con `extra-vars`

Las variables de línea de comandos (extra-vars) tienen una precedencia muy alta y pueden anular casi todo lo demás.

Ejemplo de Inventario (inventory.ini):

[webservers]
webserver01.example.com

[webservers:vars]
http_port = 8080

Ejemplo de Playbook (configure_web.yml):

--- 
- name: Configurar Servidor Web
  hosts: webservers
  tasks:
    - name: Mostrar http_port
      debug:
        msg: "El http_port es {{ http_port }}"

Ejecutando el playbook:

Sin extra-vars:
```
ansible-playbook -i inventory.ini configure_web.yml
```
Salida: El http_port será 8080 (de vars de grupo).

Con extra-vars:

ansible-playbook -i inventory.ini configure_web.yml -e "http_port=80"

Salida: El http_port será 80.

Pasos de Diagnóstico: Siempre verifica si se están usando extra-vars, especialmente en ejecuciones complejas u orquestadas, ya que son una causa común de valores de variables inesperados.

Solución: Ten en cuenta extra-vars. Si necesitas anular valores programáticamente o para ejecuciones específicas, extra-vars es el camino a seguir. Si no quieres que anulen, asegúrate de que no se estén pasando o ajusta tu playbook/inventario para priorizar otras fuentes de variables si es necesario (aunque esto generalmente no se recomienda ya que debilita la previsibilidad).

Técnicas Avanzadas de Solución de Problemas

Al tratar con problemas complejos de precedencia de variables, las siguientes técnicas pueden ser invaluables:

ansible-inventory --host: Úsalo para variables derivadas del inventario antes de que se ejecute el play.
```
ansible-inventory -i inventory.ini --host webserver01.example.com --yaml
```
Esto no mostrará los valores creados posteriormente por las tareas, pero es la forma más rápida de verificar el comportamiento del inventario, group_vars y host_vars.

Tareas debug dirigidas: Usa debug dentro del play cuando un valor pueda provenir de un rol, include, resultado registrado o set_fact.

- name: Mostrar configuraciones de aplicación resueltas
  ansible.builtin.debug:
    msg:
      app_version: "{{ app_version | default('indefinido') }}"
      db_host: "{{ db_host | default('indefinido') }}"

--skip-tags y --limit: Al depurar, intenta aislar el problema. Ejecuta el playbook con --limit para apuntar solo al host problemático. Usa --skip-tags para deshabilitar tareas o roles que podrían estar estableciendo variables involuntariamente.
Orden de vars_files: Si estás usando vars_files en tu playbook, su orden importa. Ansible los carga en el orden especificado, y los archivos posteriores pueden anular variables definidas en archivos anteriores.
```
- name: Desplegar App
  hosts: webservers
  vars_files:
    - vars/common_settings.yml
    - vars/environment_specific.yml # Esto anulará common_settings.yml si las variables se superponen
```

Mejores Prácticas para Gestionar Variables

Para minimizar los conflictos de precedencia de variables:

Sé Explícito: Evita definir la misma variable en demasiados lugares. Si una variable es verdaderamente global, considera group_vars/all.yml o group_vars/all/.
Usa Nombres Descriptivos: Usa nombres claros y únicos para tus variables para reducir la posibilidad de colisiones de nombres accidentales.
Documenta tus Variables: Lleva un registro de dónde están definidas las variables importantes y cuál es su alcance previsto.
Aprovecha los Valores por Defecto del Rol: Usa valores por defecto del rol para configuraciones no críticas que están destinadas a ser anuladas. Esto hace que los roles sean más flexibles.
Comprende el Orden: Mantén una nota mental (¡o física!) del orden de precedencia. Cuando una variable no sea lo que esperas, consulta el orden.
Prueba de Forma Incremental: Al introducir nuevas definiciones de variables o modificar las existentes, prueba tus playbooks a pequeña escala primero.

Una Rutina de Depuración que Realmente Funciona

Cuando una variable es incorrecta, no empieces moviéndola. Primero demuestra de dónde proviene el valor actual.

Normalmente empiezo con la ejecución más pequeña posible:

ansible-playbook -i inventory.ini deploy_app.yml --limit webserver01.example.com --check -vv

--limit elimina el ruido de otros hosts. --check es útil cuando el play lo soporta, aunque no todos los módulos pueden predecir cambios completamente. -vv da más contexto sin convertir la salida en un muro de detalles internos. Si el valor sigue siendo confuso, agrega una tarea de depuración temporal inmediatamente antes de la tarea que se comporta incorrectamente.

Coloca la depuración cerca de la tarea que falla. Un valor puede cambiar durante un play, especialmente si el rol usa include_vars, set_fact o register. Una tarea de depuración al inicio del play puede mostrar el valor correcto, mientras que una tarea de depuración dentro del rol muestra el valor después de haber sido sobrescrito.

Por ejemplo:

- name: Mostrar app_version antes de renderizar plantilla
  ansible.builtin.debug:
    var: app_version

- name: Renderizar configuración de app
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/app/app.conf

Si la salida de depuración es correcta pero la salida de la plantilla es incorrecta, el problema puede estar dentro de la plantilla, no en la precedencia. Quizás la plantilla hace referencia a app.version en lugar de app_version, o un filtro predeterminado oculta un valor indefinido:

version={{ app_version | default('latest') }}

Esa línea puede hacer que una variable faltante parezca un valor deliberado. Los valores predeterminados son útiles, pero pueden ocultar errores cuando se usan para configuraciones requeridas.

A continuación, inspecciona el inventario:

ansible-inventory -i inventory.ini --host webserver01.example.com --yaml
ansible-inventory -i inventory.ini --graph

La vista del host muestra las variables de inventario combinadas que Ansible ve antes de la ejecución de la tarea. La vista de gráfico muestra la pertenencia a grupos. La pertenencia a grupos importa porque un host puede heredar variables de múltiples grupos. Si dos grupos hermanos definen la misma variable, el resultado depende de la carga del inventario y las reglas de prioridad del grupo. En esa situación, confiar en el accidente es un problema de mantenimiento.

Si realmente necesitas que un grupo gane sobre otro, usa ansible_group_priority en la fuente de inventario que define los grupos. Mejor aún, evita la colisión y elige un nombre de variable que refleje la intención:

nginx_listen_port: 80
app_healthcheck_port: 8080

Eso es más claro que un http_port genérico reutilizado en roles no relacionados.

Desconfía de extra-vars. En sistemas CI/CD, los valores a menudo son inyectados por plantillas de pipeline o scripts envoltorio. Busca en la definición del trabajo -e, --extra-vars y archivos pasados con la sintaxis @:

ansible-playbook site.yml -e @release-vars.yml -e app_version=1.6

Las vars adicionales están diseñadas para ser contundentes. Si un pipeline pasa app_version=1.6, no esperes que el inventario o los valores por defecto del rol lo anulen. La solución más limpia es dejar de pasar el valor cuando no debería ser forzado, o renombrarlo a algo intencionalmente específico de la ejecución, como release_app_version.

Los roles merecen un cuidado especial. defaults/main.yml es para valores que se espera que el llamador anule. vars/main.yml es para valores que el rol posee principalmente. Si pones configuración ordinaria en vars/main.yml, los usuarios del rol tendrán dificultades para cambiarla desde el inventario o las vars del play. En muchos roles reales, mover un valor de vars/main.yml a defaults/main.yml es la solución correcta porque restaura el contrato del rol.

También presta atención a los bucles include_vars:

- name: Cargar configuraciones de entorno
  ansible.builtin.include_vars:
    file: "vars/{{ env }}.yml"

Este es un patrón útil, pero significa que el valor depende de env, el contenido del archivo incluido y el punto en el play donde se ejecuta el include. Si env proviene de vars adicionales, el include puede cargar silenciosamente un archivo diferente al esperado.

El hábito a largo plazo más confiable es darle a cada variable un hogar:

Valores por defecto del rol para el comportamiento ajustable del rol.
Inventario y group_vars para diferencias de entorno y host.
Vars del play para valores locales a un play.
Variables registradas para la salida de comandos que pertenece a la ejecución actual.
Vars adicionales para anulaciones deliberadas únicas, especialmente entradas de release.

Cuando una variable no encaja en uno de esos hogares, haz una pausa antes de agregarla. La mayoría de los errores de precedencia comienzan como una conveniencia: "Lo definiré aquí por ahora". Tres meses después, nadie recuerda qué "aquí" gana.