Теория: Устройство ролей

В этом уроке мы разберем то, как устроены роли внутри, что поможет эффективнее их анализировать и создавать свои в случае необходимости.

Роли можно изучать на базе существующих, открыв их, например, на Github. А можно создать новую роль с нуля, чтобы увидеть, базовую структуру, которая туда была заложена. Пойдем по второму пути и создадим новую роль с помощью команды ansible-galaxy.

ansible-galaxy role init role_name

Выполнять саму команду генерации можно в любом месте, если планируется эту роль добавлять на Github и публиковать в Ansible Galaxy. Но можно пойти и по другому пути. Если разместить содержимое роли в директории roles в корне проекта где запускается Ansible, то появится возможность использовать эту роль напрямую, без необходимости публиковать ее в Galaxy.

# Пример структуры Хекслет
├── Makefile
├── development.yml
├── inventory
├── files
├── group_vars
│   ├── all.yml
│   ├── evaluators.yml
├── kubernetes.repo
├── pull.yml
├── requirements.yml
├── roles # <- Роли, которые мы создали сами
│   ├── consul
│   ├── cronner
│   ├── datadog
│   ├── docker
│   ├── evaluator
│   ├── slack
│   └── user
├── templates

Команда выше создаст базовую структуру роли, добавив в нее файлы и директории, необходимые для работы роли. Всего 8 директорий.

tree role_name
role_name
├── README.md
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml

8 directories, 8 files

Из всех файлов в структуре выше, обязательными являются только meta/main.yml и tasks/main.yml. Остальные появляются в зависимости от обстоятельств. Вот их предназначение:

• defaults: содержит значения переменных по умолчанию. Эти значения могут быть изменены во время использования роли в плейбуке.
• files: сюда добавляются любые необходимые файлы, которые нужны роли.
• handlers: обработчики, которые могут быть использованы ролью.
• meta: содержит метаданные роли. Сюда входит лицензия, информация о платформе зависимости и многое другое.
• tasks: задачи роли, которые выполняются во время ее запуска.
• templates: шаблоны роли.
• tests: тесты роли.
• vars: переменные роли.
• README.md: описание, которое будет использоваться как документация.

Метаданные

Метаданные выполняют несколько задач. Во-первых, они описывают роль и помогают ее найти в Ansible Galaxy. Во-вторых, с их помощью указываются зависимости, другие роли, которые используются внутри этой.

# meta/main.yml
galaxy_info:
  author: your name
  description: your role description
  company: your company (optional)
  license: license (GPL-2.0-or-later, MIT, etc)
  min_ansible_version: 2.1

  # Provide a list of supported platforms, and for each platform a list of versions.
  # If you don't wish to enumerate all versions for a particular platform, use 'all'.
  # To view available platforms and versions (or releases), visit:
  # https://galaxy.ansible.com/api/v1/platforms/
  #
  # platforms:
  # - name: Fedora
  #   versions:
  #   - all
  #   - 25

  galaxy_tags: []
    # List tags for your role here, one per line. A tag is a keyword that describes
    # and categorizes the role. Users find roles by searching for tags. Be sure to
    # remove the '[]' above, if you add tags to this list.

dependencies: []
  # List your role dependencies here, one per line. Be sure to remove the '[]' above,
  # if you add dependencies to this list.

Задачи и обработчики

Файл tasks/main.yml, представляет собой playbook, который будет запущен на выполнение при включении роли в playbook проекта или другой роли. По умолчанию этот файл пустой. Ожидается, что мы добавим сюда необходимые задачи.

Если задач станет много, то их можно будет разбить на разные файлы внутри директории tasks. main.yml будет точкой входа, которая включает в себя все эти файлы. Принцип разделения по файлам может быть разным, один из классических примеров это разные файлы с задачами под разные платформы.

# role_name/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'

# role_name/tasks/redhat.yml
- ansible.builtin.yum:
    name: "httpd"
    state: present

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

Если задачам роли нужны обработчики, то они добавляются в директорию handlers/main.yml. Ansible автоматически их найдет и подключит.

Переменные роли

Для определения переменных, Ansible предлагает два разных варианта: директорию defaults и директорию vars. И там и там хранятся переменные, которые роль использует для своей работы. Разница между этими директориями заключается в том, что в vars хранятся переменные, которые нужны роли для ее работы, но пользователю про них знать не нужно, это внутренние переменные. defaults же содержит переменные, которые пользователь роли может или должен задать при использовании этой роли. Типичный пример параметра по умолчанию, это номер версии устанавливаемой программы. Обычно его можно поменять, без необходимости менять внутренности роли.

# Пример роли nginxinc.nginx

# ansible-role-nginx/vars/main.yml

# Supported NGINX Open Source distributions
# https://nginx.org/en/docs/install.html
nginx_supported_distributions:
  almalinux:
    name: AlmaLinux
    versions: [8, 9]
    architectures: [x86_64, aarch64, s390x]
  alpine:
    name: Alpine Linux
    versions: [3.15, 3.16, 3.17, 3.18]
    architectures: [x86_64, aarch64]

# ansible-role-nginx/defaults/main.yml

nginx_type: opensource
nginx_install_source_build_tools: true
nginx_install_source_pcre: false
nginx_install_source_openssl: true
nginx_install_source_zlib: false

Шаблоны и файлы

Остальные директории могут содержать типовые файлы, которые встречаются в playbook. Структура этих директорий никак не специфицирована. Все файлы внутри них раскладываются так как удобно создателю роли.