Al fin después de tanto trabajar pudimos dar con la contestación de este enigma que tantos lectores de nuestro sitio tienen. Si tienes alguna información que aportar puedes dejar tu conocimiento.
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 usarse 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 deltasks
sección de una obra de teatro usandoinclude_role
. - a nivel de tareas con
import_role
: Puede reutilizar roles de forma estática en cualquier lugar deltasks
sección de una obra de teatro usandoimport_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 elmeta/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:5000tags: typeA -role: foo_app_instance vars:dir:'/opt/b'app_port:5001tags: 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, poniéndolas a disposición de 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:5000tags: 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 roles
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-de-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 descripción breve de una línea del punto de entrada.
- los
short_description
es mostrado poransible-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.
- El tipo de datos de la opción. El valor predeterminado es
- requerido
-
- Solo es necesario si
true
. - Si falta, la opción no es necesaria.
- Solo es necesario si
- defecto
-
- Si
required
es falso / faltante,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.
- Si
- 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
.
- Especifica el tipo de datos para los elementos de la lista cuando el tipo es
- 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 pointmain:short_description: The main entry point for the myapp role. options:myapp_int:type:"int"required:falsedefault:42description:"The integer value, defaulting to 42."myapp_str:type:"str"required:truedescription:"The string value"# roles/maypp/tasks/alternate.yml entry pointalternate:short_description: The alternate entry point for the myapp role. options:myapp_int:type:"int"required:falsedefault:1024description:"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.
Usar dependencias de roles
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 través 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 usar el mismo mecanismo para incrustar y distribuir complementos en un rol, usando 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 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
Si estás de acuerdo, tienes la opción de dejar una noticia acerca de qué te ha gustado de este tutorial.