Los roles le permiten cargar automáticamente vars, archivos, tareas, controladores y otros artefactos de Ansible relacionados en función de una estructura de archivo conocida. Una vez que agrupa su contenido en roles, puede reutilizarlos fácilmente y compartirlos con otros usuarios.

  • Estructura del directorio de roles
  • Almacenamiento y búsqueda de roles

  • Usando roles

    • Usar roles a nivel de juego
    • Incluyendo roles: reutilización dinámica
    • Importación de roles: reutilización estática

  • Validación de argumentos de rol

    • Formato de especificación
    • Especificación de muestra

  • Ejecutar un rol varias veces en un libro de jugadas

    • Pasando diferentes parámetros
    • Utilizando allow_duplicates: true

  • Usar dependencias de roles

    • Ejecutar dependencias de roles varias veces en un solo libro de jugadas
  • Incorporación de módulos y complementos en roles
  • Compartiendo roles: Ansible Galaxy

Estructura del directorio de roles

Un rol de Ansible tiene una estructura de directorio definida con siete directorios estándar principales. Debe incluir al menos uno de estos directorios en cada rol. Puede omitir cualquier directorio que no utilice el rol. Por ejemplo:

# playbooks
site.yml
webservers.yml
fooservers.yml
roles/
    common/
        tasks/
        handlers/
        library/
        files/
        templates/
        vars/
        defaults/
        meta/
    webservers/
        tasks/
        defaults/
        meta/

De forma predeterminada, Ansible buscará en cada directorio dentro de un rol un main.yml archivo para contenido relevante (también main.yaml y main):

  • tasks/main.yml – la lista principal de tareas que ejecuta el rol.
  • handlers/main.yml – manipuladores, que pueden utilizarse dentro o fuera de esta función.
  • library/my_module.py – módulos, que pueden utilizarse dentro de este rol (ver Incorporación de módulos y complementos en roles para más información).
  • defaults/main.yml – variables predeterminadas para el rol (ver Usando Variables para más información). Estas variables tienen la prioridad más baja de todas las variables disponibles y pueden ser fácilmente reemplazadas por cualquier otra variable, incluidas las variables de inventario.
  • vars/main.yml – otras variables para el rol (ver Usando Variables para más información).
  • files/main.yml – archivos que despliega el rol.
  • templates/main.yml – plantillas que despliega el rol.
  • meta/main.yml – metadatos para el rol, incluidas las dependencias del rol.

Puede agregar otros archivos YAML en algunos directorios. Por ejemplo, puede colocar tareas específicas de la plataforma en archivos separados y hacer referencia a ellas en el tasks/main.yml expediente:

# roles/example/tasks/main.yml
- name: Install the correct web server for RHEL
  import_tasks: redhat.yml
  when: ansible_facts['os_family']|lower == 'redhat'

- name: Install the correct web server for Debian
  import_tasks: debian.yml
  when: ansible_facts['os_family']|lower == 'debian'

# roles/example/tasks/redhat.yml
- name: Install web server
  ansible.builtin.yum:
    name: "httpd"
    state: present

# roles/example/tasks/debian.yml
- name: Install web server
  ansible.builtin.apt:
    name: "apache2"
    state: present

Los roles también pueden incluir módulos y otros tipos de complementos en un directorio llamado library. Para obtener más información, consulte Incorporación de módulos y complementos en roles debajo.

Almacenamiento y búsqueda de roles

De forma predeterminada, Ansible busca roles en dos ubicaciones:

  • en un directorio llamado roles/, relativo al archivo del libro de jugadas
  • en /etc/ansible/roles

Si almacena sus roles en una ubicación diferente, configure el roles_path opción de configuración para que Ansible pueda encontrar sus roles. La verificación de roles compartidos en una sola ubicación hace que sean más fáciles de usar en varios libros de jugadas. Ver Configuración de Ansible para obtener detalles sobre cómo administrar la configuración en ansible.cfg.

Alternativamente, puede llamar a un rol con una ruta completamente calificada:

---
- hosts: webservers
  roles:
    - role: '/path/to/my/roles/common'

Usando roles

Puede utilizar roles de tres formas:

  • en el nivel de juego con el roles opción: Ésta es la forma clásica de usar roles en una obra de teatro.
  • a nivel de tareas con include_role: Puede reutilizar roles dinámicamente en cualquier lugar del tasks sección de una obra de teatro usando include_role.
  • a nivel de tareas con import_role: Puede reutilizar roles de forma estática en cualquier lugar del tasks sección de una obra de teatro usando import_role.

Usar roles a nivel de juego

La forma clásica (original) de usar roles es con el roles opción para una obra determinada:

---
- hosts: webservers
  roles:
    - common
    - webservers

Cuando usa el roles opción en el nivel de juego, para cada rol ‘x’:

  • Si existe roles / x / tasks / main.yml, Ansible agrega las tareas en ese archivo a la obra.
  • Si existe roles / x / handlers / main.yml, Ansible agrega los controladores en ese archivo a la obra.
  • Si existe roles / x / vars / main.yml, Ansible agrega las variables en ese archivo a la obra.
  • Si existe roles / x / defaults / main.yml, Ansible agrega las variables en ese archivo a la obra.
  • Si existe roles / x / meta / main.yml, Ansible agrega cualquier dependencia de rol en ese archivo a la lista de roles.
  • Cualquier copia, secuencia de comandos, plantilla o tareas incluidas (en el rol) puede hacer referencia a archivos en roles / x / {archivos, plantillas, tareas} / (el directorio depende de la tarea) sin tener que establecer una ruta relativa o absoluta.

Cuando usa el roles opción en el nivel de juego, Ansible trata los roles como importaciones estáticas y los procesa durante el análisis del libro de jugadas. Ansible ejecuta su libro de jugadas en este orden:

  • Alguna pre_tasks definido en la obra.
  • Cualquier controlador activado por pre_tasks.
  • Cada rol enumerado en roles:, en el orden indicado. Cualquier dependencia de rol definida en el meta/main.yml ejecutar primero, sujeto a filtros de etiquetas y condicionales. Ver Usar dependencias de roles para más detalles.
  • Alguna tasks definido en la obra.
  • Cualquier controlador desencadenado por los roles o tareas.
  • Alguna post_tasks definido en la obra.
  • Cualquier controlador activado por post_tasks.

Nota

Si usa etiquetas con tareas en un rol, asegúrese de etiquetar también sus pre_tasks, post_tasks y dependencias de roles y transmítalas también, especialmente si las tareas previas / posteriores y las dependencias de roles se usan para monitorear el control de la ventana de interrupción o el equilibrio de carga. Ver Etiquetas para obtener detalles sobre cómo agregar y usar etiquetas.

Puede pasar otras palabras clave al roles opción:

---
- hosts: webservers
  roles:
    - common
    - role: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
      tags: typeA
    - role: foo_app_instance
      vars:
        dir: '/opt/b'
        app_port: 5001
      tags: typeB

Cuando agrega una etiqueta al role opción, Ansible aplica la etiqueta a TODAS las tareas dentro del rol.

Cuando usas vars: dentro de roles: sección de un libro de jugadas, las variables se agregan a las variables del juego, haciéndolas disponibles para todas las tareas dentro del juego antes y después del rol. Este comportamiento se puede cambiar DEFAULT_PRIVATE_ROLE_VARS.

Incluyendo roles: reutilización dinámica

Puede reutilizar roles dinámicamente en cualquier lugar del tasks sección de una obra de teatro usando include_role. Mientras que los roles agregados en un roles La sección se ejecuta antes que cualquier otra tarea en un libro de jugadas, los roles incluidos se ejecutan en el orden en que están definidos. Si hay otras tareas antes de una include_role tarea, las otras tareas se ejecutarán primero.

Para incluir un rol:

---
- hosts: webservers
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: "this task runs before the example role"

    - name: Include the example role
      include_role:
        name: example

    - name: Print a message
      ansible.builtin.debug:
        msg: "this task runs after the example role"

Puede pasar otras palabras clave, incluidas variables y etiquetas, al incluir roles:

---
- hosts: webservers
  tasks:
    - name: Include the foo_app_instance role
      include_role:
        name: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
      tags: typeA
  ...

Cuando agrega un etiqueta a una include_role tarea, Ansible aplica la etiqueta only a la inclusión en sí. Esto significa que puedes pasar --tags para ejecutar solo las tareas seleccionadas del rol, si esas tareas tienen la misma etiqueta que la declaración de inclusión. Ver Ejecución selectiva de tareas etiquetadas en archivos reutilizables para detalles.

Puede incluir condicionalmente un rol:

---
- hosts: webservers
  tasks:
    - name: Include the some_role role
      include_role:
        name: some_role
      when: "ansible_facts['os_family'] == 'RedHat'"

Importación de roles: reutilización estática

Puede reutilizar roles estáticamente en cualquier lugar del tasks sección de una obra de teatro usando import_role. El comportamiento es el mismo que usar el roles palabra clave. Por ejemplo:

---
- hosts: webservers
  tasks:
    - name: Print a message
      ansible.builtin.debug:
        msg: "before we run our role"

    - name: Import the example role
      import_role:
        name: example

    - name: Print a message
      ansible.builtin.debug:
        msg: "after we ran our role"

Puede pasar otras palabras clave, incluidas variables y etiquetas, al importar roles:

---
- hosts: webservers
  tasks:
    - name: Import the foo_app_instance role
      import_role:
        name: foo_app_instance
      vars:
        dir: '/opt/a'
        app_port: 5000
  ...

Cuando agrega una etiqueta a un import_role declaración, Ansible aplica la etiqueta a all tareas dentro del rol. Ver Herencia de etiquetas: agregar etiquetas a varias tareas para detalles.

Validación de argumentos de rol

A partir de la versión 2.11, puede optar por habilitar la validación del argumento del rol en función de una especificación de argumento definida en el rol. meta/main.yml expediente. Cuando se define esta especificación de argumento, se inserta una nueva tarea al comienzo de la ejecución del rol que validará los parámetros proporcionados para el rol contra la especificación. Si los parámetros fallan en la validación, el rol fallará en la ejecución.

Nota

Cuando la validación del argumento de rol se usa en un rol que ha definido dependencias, la validación de esas dependencias se ejecutará antes que el rol dependiente, incluso si la validación del argumento falla para el rol dependiente.

Formato de especificación

La especificación del argumento del rol debe definirse en un nivel superior argument_specs bloque dentro del rol meta/main.yml expediente. Todos los campos están en minúsculas.

nombre-punto-entrada
  • El nombre del punto de entrada del rol.
  • Esto debería ser main en el caso de un punto de entrada no especificado.
  • Este será el nombre base del archivo de tareas a ejecutar, sin .yml o .yaml extensión de archivo.
Breve descripción
  • Una breve descripción de una línea del punto de entrada.
  • los short_description es mostrado por ansible-doc -t role -l.
descripción
  • Una descripción más larga que puede contener varias líneas.
autor
  • Nombre de los autores del punto de entrada.
  • Utilice una lista de varias líneas si hay más de un autor.
opciones
  • Las opciones a menudo se denominan “parámetros” o “argumentos”. Esta sección define esas opciones.
  • Para cada opción de rol (argumento), puede incluir:
nombre-opción
  • El nombre de la opción / argumento.
descripción
  • Explicación detallada de lo que hace esta opción. Debe estar escrito en oraciones completas.
escribe
  • El tipo de datos de la opción. El valor predeterminado es str.
  • Si una opción es de tipo list, elements debe especificarse.
requerido
  • Solo es necesario si true.
  • Si falta, la opción no es necesaria.
defecto
  • Si required es falso / falta, default se puede especificar (se asume ‘nulo’ si falta).
  • Asegúrese de que el valor predeterminado en los documentos coincida con el valor predeterminado en el código. El valor predeterminado real para la variable de función siempre vendrá de defaults/main.yml.
  • El campo predeterminado no debe aparecer como parte de la descripción, a menos que requiera información o condiciones adicionales.
  • Si la opción es un valor booleano, puede usar cualquiera de los valores booleanos reconocidos por Ansible: (como verdadero / falso o sí / no). Elija el que se lea mejor en el contexto de la opción.
opciones
  • Lista de valores de opciones.
  • Debería estar ausente si está vacío.
elementos
  • Especifica el tipo de datos para los elementos de la lista cuando el tipo es list.
subopciones
  • Si esta opción toma un dictado o una lista de dictados, puede definir la estructura aquí.

Especificación de muestra

# roles/myapp/meta/main.yml
---
argument_specs:
  # roles/myapp/tasks/main.yml entry point
  main:
    short_description: The main entry point for the myapp role.
    options:
      myapp_int:
        type: "int"
        required: false
        default: 42
        description: "The integer value, defaulting to 42."

      myapp_str:
        type: "str"
        required: true
        description: "The string value"

  # roles/maypp/tasks/alternate.yml entry point
  alternate:
    short_description: The alternate entry point for the myapp role.
    options:
      myapp_int:
        type: "int"
        required: false
        default: 1024
        description: "The integer value, defaulting to 1024."

Ejecutar un rol varias veces en un libro de jugadas

Ansible solo ejecuta cada rol una vez, incluso si lo define varias veces, a menos que los parámetros definidos en el rol sean diferentes para cada definición. Por ejemplo, Ansible solo ejecuta el rol foo una vez en una obra de teatro como esta:

---
- hosts: webservers
  roles:
    - foo
    - bar
    - foo

Tiene dos opciones para obligar a Ansible a ejecutar un rol más de una vez.

Pasando diferentes parámetros

Puede pasar diferentes parámetros en cada definición de rol como:

---
- hosts: webservers
  roles:
    - { role: foo, vars: { message: "first" } }
    - { role: foo, vars: { message: "second" } }

o

---
- hosts: webservers
  roles:
    - role: foo
      vars:
        message: "first"
    - role: foo
      vars:
        message: "second"

En este ejemplo, debido a que cada definición de rol tiene diferentes parámetros, Ansible ejecuta foo dos veces.

Utilizando allow_duplicates: true

Agregar allow_duplicates: true al meta/main.yml archivo para el puesto:

# playbook.yml
---
- hosts: webservers
  roles:
    - foo
    - foo

# roles/foo/meta/main.yml
---
allow_duplicates: true

En este ejemplo, Ansible ejecuta foo dos veces porque lo hemos habilitado explícitamente para hacerlo.

Usando rol dependencias

Las dependencias de roles le permiten incorporar automáticamente otros roles cuando usa un rol. Ansible no ejecuta dependencias de roles cuando incluye o importa un rol. Debes usar el roles palabra clave si desea que Ansible ejecute dependencias de roles.

Las dependencias de roles se almacenan en el meta/main.yml archivo dentro del directorio de roles. Este archivo debe contener una lista de roles y parámetros para insertar antes del rol especificado. Por ejemplo:

# roles/myapp/meta/main.yml
---
dependencies:
  - role: common
    vars:
      some_parameter: 3
  - role: apache
    vars:
      apache_port: 80
  - role: postgres
    vars:
      dbname: blarg
      other_parameter: 12

Ansible siempre ejecuta las dependencias de roles antes que el rol que las incluye. Ansible también ejecuta dependencias de roles recursivas. Si un rol depende de un segundo rol y el segundo rol depende de un tercer rol, Ansible ejecuta el tercer rol, luego el segundo rol y luego el primer rol.

Ejecutar dependencias de roles varias veces en un solo libro de jugadas

Ansible trata las dependencias de roles duplicados como roles duplicados enumerados en roles:: Ansible solo ejecuta las dependencias de roles una vez, incluso si se definen varias veces, a menos que los parámetros, las etiquetas o cuando la cláusula definida en el rol sean diferentes para cada definición. Si dos roles en un libro de jugadas enumeran un tercer rol como dependencia, Ansible solo ejecuta esa dependencia de rol una vez, a menos que pase diferentes parámetros, etiquetas, cláusula when o use allow_duplicates: true en el rol dependiente (tercero). Ver Dependencias de roles de Galaxy para más detalles.

Nota

La deduplicación de roles no consulta la firma de invocación de los roles principales. Además, al usar vars: en lugar de parámetros de rol, hay un efecto secundario al cambiar el alcance de las variables. Utilizando vars: da como resultado que esas variables tengan un alcance en el nivel de juego. En el siguiente ejemplo, usando vars: causaría n ser definido como 4 a lo largo de toda la obra, incluidos los roles nombrados antes.

Además de lo anterior, los usuarios deben tener en cuenta que la deduplicación de roles ocurre antes de la evaluación de variables. Esto significa que Evaluación perezosa puede hacer que las invocaciones de roles aparentemente diferentes sean equivalentes, evitando que el rol se ejecute más de una vez.

Por ejemplo, un rol llamado car depende de un rol llamado wheel como sigue:

---
dependencies:
  - role: wheel
    n: 1
  - role: wheel
    n: 2
  - role: wheel
    n: 3
  - role: wheel
    n: 4

Y el wheel el rol depende de dos roles: tire y brake. los meta/main.yml for wheel entonces contendría lo siguiente:

---
dependencies:
  - role: tire
  - role: brake

Y el meta/main.yml por tire y brake contendría lo siguiente:

---
allow_duplicates: true

El orden de ejecución resultante sería el siguiente:

tire(n=1)
brake(n=1)
wheel(n=1)
tire(n=2)
brake(n=2)
wheel(n=2)
...
car

Usar allow_duplicates: true con dependencias de roles, debe especificarlo para el rol dependiente, no para el rol principal. En el ejemplo anterior, allow_duplicates: true aparece en el meta/main.yml de El tire y brake roles. los wheel el rol no requiere allow_duplicates: true, porque cada instancia definida por car utiliza diferentes valores de parámetros.

Nota

Ver Usando Variables para obtener detalles sobre cómo Ansible elige entre los valores de las variables definidos en diferentes lugares (herencia y alcance de la variable).

Incorporación de módulos y complementos en roles

Si escribe un módulo personalizado (consulte ¿Deberías desarrollar un módulo?) o un complemento (ver Desarrollando complementos), es posible que desee distribuirlo como parte de un rol. Por ejemplo, si escribe un módulo que ayuda a configurar el software interno de su empresa y desea que otras personas de su organización utilicen este módulo, pero no desea decirles a todos cómo configurar la ruta de la biblioteca de Ansible, puede incluir el módulo. en su rol internal_config.

Para agregar un módulo o un complemento a un rol: Junto con la estructura de ‘tareas’ y ‘controladores’ de un rol, agregue un directorio llamado ‘biblioteca’ y luego incluya el módulo directamente dentro del directorio ‘biblioteca’.

Suponiendo que tuvieras esto:

roles/
    my_custom_modules/
        library/
            module1
            module2

El módulo se podrá utilizar en el rol en sí, así como en cualquier rol que se llame después este rol, de la siguiente manera:

---
- hosts: webservers
  roles:
    - my_custom_modules
    - some_other_role_using_my_custom_modules
    - yet_another_role_using_my_custom_modules

Si es necesario, también puede incrustar un módulo en un rol para modificar un módulo en la distribución principal de Ansible. Por ejemplo, puede utilizar la versión de desarrollo de un módulo en particular antes de que se publique en versiones de producción copiando el módulo e incrustando la copia en un rol. Utilice este enfoque con precaución, ya que las firmas de API pueden cambiar en los componentes principales y no se garantiza que esta solución funcione.

Se puede utilizar el mismo mecanismo para incrustar y distribuir complementos en una función, utilizando el mismo esquema. Por ejemplo, para un complemento de filtro:

roles/
    my_custom_filter/
        filter_plugins
            filter1
            filter2

Estos filtros se pueden usar en una plantilla de Jinja en cualquier rol llamado después de ‘my_custom_filter’.

Compartiendo roles: Ansible Galaxy

Ansible Galaxy es un sitio gratuito para buscar, descargar, calificar y revisar todo tipo de roles de Ansible desarrollados por la comunidad y puede ser una excelente manera de impulsar sus proyectos de automatización.

El cliente ansible-galaxy está incluido en Ansible. El cliente Galaxy le permite descargar roles de Ansible Galaxy y también proporciona un excelente marco predeterminado para crear sus propios roles.

Leer el Documentación de Ansible Galaxy página para más información

Ver también

Guía del usuario de Galaxy

Cómo crear nuevos roles, compartir roles en Galaxy, administración de roles

Sintaxis de YAML

Más información sobre la sintaxis de YAML

Trabajar con libros de jugadas

Revise las características básicas del idioma de Playbook

Consejos y trucos

Consejos y trucos para libros de jugadas

Usando Variables

Variables en libros de jugadas

Condicionales

Condicionales en los libros de jugadas

Bucles

Bucles en los libros de jugadas

Etiquetas

Usar etiquetas para seleccionar u omitir roles / tareas en libros de jugadas largos

Índice de colección

Explore colecciones, módulos y complementos existentes

¿Deberías desarrollar un módulo?

Ampliando Ansible escribiendo sus propios módulos

Ejemplos de GitHub Ansible

Archivos completos del libro de jugadas de la fuente del proyecto de GitHub

Lista de correo

¿Preguntas? ¿Ayudar? Ideas? Pasa por la lista de Grupos de Google