Руководство пользователя Galaxy

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

Используйте Galaxy, чтобы начать проект автоматизации с отличным контентом от сообщества Ansible. Galaxy предоставляет предварительно упакованные блоки работы, такие как роли, и, начиная с Galaxy 3.2, коллекции. Вы можете найти роли для подготовки инфраструктуры, развертывания приложений и всех задач, которые вы выполняете ежедневно. Формат коллекции предоставляет комплексный пакет автоматизации, который может включать несколько playbooks, роли, модули и плагины.

• Поиск коллекций в Galaxy
• Установка коллекций
  • Установка коллекции из Galaxy
  • Загрузка коллекции из Automation Hub
  • Установка более старой версии коллекции
  • Установка нескольких коллекций с помощью файла requirements
  • Настройка клиента ansible-galaxy
• Поиск ролей в Galaxy
  • Получение дополнительной информации о роли
• Установка ролей из Galaxy
  • Установка ролей
  • Установка определенной версии роли
  • Установка нескольких ролей из файла
  • Установка ролей и коллекций из одного файла requirements.yml
  • Установка нескольких ролей из нескольких файлов
  • Зависимости
  • Список установленных ролей
  • Удаление установленной роли

Поиск коллекций в Galaxy

Чтобы найти коллекции в Galaxy:

1. Нажмите значок Поиск в левом навигационном меню.
2. Установите фильтр на коллекцию.
3. Установите другие фильтры и нажмите ввод.

Galaxy отобразит список коллекций, соответствующих вашим критериям поиска.

Установка коллекций

Установка коллекции из Galaxy

Вы можете использовать команду ansible-galaxy collection install для установки коллекции на вашей системе.

Чтобы установить коллекцию, размещенную в Galaxy:

ansible-galaxy collection install my_namespace.my_collection

Вы также можете напрямую использовать tarball из вашей сборки:

ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections

При использовании параметра -p для указания пути установки, используйте одно из значений, настроенных в COLLECTIONS_PATHS, так как именно здесь Ansible ожидает найти коллекции. Если вы не укажете путь, ansible-galaxy collection install установит коллекцию в первом пути, определенном в COLLECTIONS_PATHS, который по умолчанию равен ~/.ansible/collections.

Вы также можете разместить коллекцию рядом с текущим playbook в структуре директорий collections/ansible_collections/.

play.yml
├── collections/
│   └── ansible_collections/
│               └── my_namespace/
│                   └── my_collection/<collection structure lives here>

Подробную информацию о структуре каталога коллекции см. в Структура коллекции.

Загрузка коллекции из Automation Hub

Чтобы загрузить коллекцию из Automation Hub с помощью команды ansible-galaxy, выполните следующие действия:

1. Получите свой токен API Automation Hub. Перейдите по адресу https://cloud.redhat.com/ansible/automation-hub/token/ и нажмите Получить токен API из выпадающего списка версий, чтобы скопировать свой токен API.
2. Настройте сервер Red Hat Automation Hub в параметре server_list в разделе [galaxy] вашего файла ansible.cfg.

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token

3. Загрузите коллекцию, размещенную в Automation Hub.

ansible-galaxy collection install my_namespace.my_collection

Установка более старой версии коллекции

По умолчанию ansible-galaxy устанавливает последнюю доступную коллекцию, но вы можете добавить идентификатор диапазона версий, чтобы установить конкретную версию.

Чтобы установить версию 1.0.0 коллекции:

ansible-galaxy collection install my_namespace.my_collection:1.0.0

Чтобы установить версию 1.0.0-beta.1 коллекции:

ansible-galaxy collection install my_namespace.my_collection:==1.0.0-beta.1

Чтобы установить коллекции, которые больше или равны 1.0.0 или меньше 2.0.0:

ansible-galaxy collection install my_namespace.my_collection:>=1.0.0,<2.0.0

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

• *: Любая версия, это значение используется по умолчанию, если диапазон не указан.
• !=: Версия не равна указанной.
• ==: Версия должна быть указанной.
• >=: Версия больше или равна указанной.
• >: Версия больше указанной.
• <=: Версия меньше или равна указанной.
• <: Версия меньше указанной.

Установка нескольких коллекций с помощью файла requirements

Вы также можете создать файл requirements.yml для установки нескольких коллекций одной командой. Этот файл представляет собой YAML-файл в формате:

---
collections:
# With just the collection name
- my_namespace.my_collection

# With the collection name, version, and source options
- name: my_namespace.my_other_collection
  version: 'version range identifiers (default: ``*``)'
  source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'

Ключ version может принимать тот же формат идентификаторов диапазонов, что и в документации выше.

Также могут быть указаны роли и помещены под ключом roles. Значения следуют тому же формату, что и файл requirements, используемый в более старых версиях Ansible.

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: 1.9.6

collections:
  # Install a collection from Ansible Galaxy.
  - name: geerlingguy.php_roles
    version: 0.9.3
    source: https://galaxy.ansible.com

Настройка клиента ansible-galaxy

По умолчанию ansible-galaxy использует https://galaxy.ansible.com в качестве сервера Galaxy (как указано в файле ansible.cfg в разделе GALAXY_SERVER).

Вы можете настроить его на использование других серверов (таких как Red Hat Automation Hub или пользовательский сервер Galaxy) следующим образом:

• Установите список серверов в параметре GALAXY_SERVER_LIST в настройках конфигурации файл конфигурации.
• Используйте аргумент командной строки --server для ограничения до отдельного сервера.

Чтобы настроить список серверов Galaxy в ansible.cfg, выполните следующие действия:

1. Добавьте параметр server_list в раздел [galaxy] с одним или несколькими именами серверов.
2. Создайте новый раздел для каждого имени сервера.
3. Установите параметр url для каждого имени сервера.

Для Automation Hub вам также необходимо:

1. Установите параметр auth_url для каждого имени сервера.
2. Установите токен API для каждого имени сервера. Перейдите по адресу https://cloud.redhat.com/ansible/automation-hub/token/ и нажмите Получить токен API из выпадающего списка версий, чтобы скопировать свой токен API.

Следующий пример показывает, как настроить несколько серверов:

[galaxy]
server_list = automation_hub, my_org_hub, release_galaxy, test_galaxy

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token

token=my_ah_token

[galaxy_server.my_org_hub]
url=https://automation.my_org/
username=my_user
password=my_pass

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token

[galaxy_server.test_galaxy]
url=https://galaxy-dev.ansible.com/
token=my_test_token

Настройки конфигурации списка серверов Galaxy

Параметр GALAXY_SERVER_LIST представляет собой список идентификаторов серверов в приоритетном порядке. При поиске коллекции процесс установки будет осуществлять поиск в указанном порядке, например automation_hub в первую очередь, затем my_org_hub, release_galaxy, и, наконец, test_galaxy до тех пор, пока коллекция не будет найдена. Фактический экземпляр Galaxy определяется в разделе [galaxy_server.{{ id }}], где {{ id }} — это идентификатор сервера, определённый в списке. Этот раздел может содержать следующие ключи:

• url: URL экземпляра galaxy для подключения, это обязательно.
• token: Ключ маркера для аутентификации на экземпляре Galaxy, взаимно исключающий с username
• username: Имя пользователя для базовой аутентификации на экземпляре Galaxy, взаимно исключающий с token
• password: Пароль для базовой аутентификации
• auth_url: URL сервера Keycloak ‘token_endpoint’, если используется SSO-аутентификация (например, Automation Hub). Взаимно исключающий с username. auth_url требует token.

Помимо определения в файле ansible.cfg, эти параметры сервера можно определить как переменные среды. Переменная среды имеет вид ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}, где {{ id }} — это заглавные буквы идентификатора сервера, а {{ key }} — это ключ для определения. Например, я могу определить token для release_galaxy путём установки ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token.

Для операций, в которых используется только один сервер Galaxy, т. е. publish, info, login, используется первая запись в server_list, если не был передан явный сервер в качестве аргумента командной строки.

Поиск ролей в Galaxy

Искать в базе данных Galaxy по тегам, платформам, автору и нескольким ключевым словам. Например:

$ ansible-galaxy search elasticsearch --author geerlingguy

Команда поиска вернёт список первых 1000 результатов, соответствующих вашему поиску:

Found 2 roles matching your search:

Name                              Description
----                              -----------
geerlingguy.elasticsearch         Elasticsearch for Linux.
geerlingguy.elasticsearch-curator Elasticsearch curator for Linux.

Получение дополнительной информации о роли

Используйте команду info для просмотра подробной информации о конкретной роли:

$ ansible-galaxy info username.role_name

Это возвращает всё, что найдено в Galaxy для роли:

Role: username.role_name
    description: Installs and configures a thing, a distributed, highly available NoSQL thing.
    active: True
    commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57
    commit_message: Adding travis
    commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab
    company: My Company, Inc.
    created: 2015-12-08T14:17:52.773Z
    download_count: 1
    forks_count: 0
    github_branch:
    github_repo: repo_name
    github_user: username
    id: 6381
    is_valid: True
    issue_tracker_url:
    license: Apache
    min_ansible_version: 1.4
    modified: 2015-12-08T18:43:49.085Z
    namespace: username
    open_issues_count: 0
    path: /Users/username/projects/roles
    scm: None
    src: username.repo_name
    stargazers_count: 0
    travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master
    version:
    watchers_count: 1

Установка ролей из Galaxy

Команда ansible-galaxy поставляется с Ansible и позволяет устанавливать роли из Galaxy или непосредственно из системы управления версиями, основанной на git. Вы также можете использовать её для создания новой роли, удаления ролей или выполнения задач на веб-сайте Galaxy.

Инструмент командной строки по умолчанию взаимодействует с API веб-сайта Galaxy, используя адрес сервера https://galaxy.ansible.com. Поскольку проект Galaxy является открытым проектом с исходным кодом, вы можете запускать свой собственный внутренний сервер Galaxy и переопределить адрес сервера по умолчанию. Вы можете сделать это с помощью опции –server или задав значение сервера Galaxy в файле ansible.cfg. Сведения о настройке значения в файле ansible.cfg см. в GALAXY_SERVER.

Установка ролей

Используйте команду ansible-galaxy для скачивания ролей с веб-сайта Galaxy

$ ansible-galaxy install namespace.role_name

Настройка места установки ролей

По умолчанию Ansible загружает роли в первую доступную директорию в стандартном списке путей ~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles. Это устанавливает роли в домашнем каталоге пользователя, выполняющего ansible-galaxy.

Вы можете переопределить это с помощью одной из следующих опций:

• Установите переменную среды ANSIBLE_ROLES_PATH в вашей сессии.
• Определите roles_path в файле ansible.cfg.
• Используйте опцию --roles-path для команды ansible-galaxy.

Следующий пример демонстрирует использование --roles-path для установки роли в текущую рабочую директорию:

$ ansible-galaxy install --roles-path . geerlingguy.apache

Установка определённой версии роли

Когда сервер Galaxy импортирует роль, он импортирует любые git-теги, соответствующие формату семантической версии, как версии. В свою очередь, вы можете загрузить определённую версию роли, указав один из импортированных тегов.

Чтобы увидеть доступные версии для роли:

1. Найдите роль на странице поиска Galaxy.
2. Нажмите на имя, чтобы просмотреть дополнительные сведения, включая доступные версии.

Вы также можете перейти напрямую к роли, используя /<namespace>/<имя роли>. Например, чтобы просмотреть роль geerlingguy.apache, перейдите по адресу https://galaxy.ansible.com/geerlingguy/apache.

Чтобы установить определённую версию роли из Galaxy, добавьте запятую и значение тега выпуска GitHub. Например:

$ ansible-galaxy install geerlingguy.apache,v1.0.0

Также возможно указать напрямую git-репозиторий и указать имя ветки или хеш коммита как версию. Например, следующее установит определённый коммит:

$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25

Установка нескольких ролей из файла

Вы можете установить несколько ролей, включив их в файл requirements.yml. Формат файла — YAML, а расширение файла должно быть .yml или .yaml.

Используйте следующую команду для установки ролей, включённых в requirements.yml:

$ ansible-galaxy install -r requirements.yml

Опять же, расширение важно. Если расширение .yml опущен, CLI ansible-galaxy предполагает, что файл находится в более старом, ныне устаревшем, формате «basic».

В каждом файле роли будет содержаться один или несколько из следующих атрибутов:

src

Источник роли. Используйте формат namespace.role_name, если скачиваете из Galaxy; в противном случае укажите URL, указывающий на репозиторий в системе управления версиями, основанной на git. См. примеры ниже. Этот атрибут является обязательным.

scm

Укажите SCM. На данный момент разрешены только git или hg. См. примеры ниже. По умолчанию используется git.

version:

Версия роли для скачивания. Укажите значение тега выпуска, хеш коммита или имя ветки. По умолчанию используется ветка, установленная по умолчанию в репозитории, в противном случае по умолчанию используется master.

name:

Скачивайте роль в определённое имя. По умолчанию используется имя Galaxy при скачивании из Galaxy, в противном случае используется имя репозитория.

Используйте следующий пример в качестве руководства для указания ролей в requirements.yml:

# from galaxy
- name: yatesr.timezone

# from GitHub
- src: https://github.com/bennojoy/nginx

# from GitHub, overriding the name and specifying a specific tag
- name: nginx_role
  src: https://github.com/bennojoy/nginx
  version: master

# from a webserver, where the role is packaged in a tar.gz
- name: http-role-gz
  src: https://some.webserver.example.com/files/master.tar.gz

# from a webserver, where the role is packaged in a tar.bz2
- name: http-role-bz2
  src: https://some.webserver.example.com/files/master.tar.bz2

# from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
- name: http-role-xz
  src: https://some.webserver.example.com/files/master.tar.xz

# from Bitbucket
- src: git+https://bitbucket.org/willthames/git-ansible-galaxy
  version: v1.4

# from Bitbucket, alternative syntax and caveats
- src: https://bitbucket.org/willthames/hg-ansible-galaxy
  scm: hg

# from GitLab or other git-based scm, using git+ssh
- src: git@gitlab.company.com:mygroup/ansible-base.git
  scm: git
  version: "0.1"  # quoted, so YAML doesn't parse this as a floating-point value

Установка ролей и коллекций из одного файла requirements.yml

Вы можете установить роли и коллекции из одного файла требований, с некоторыми оговорками.

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: 1.9.6

collections:
  # Install a collection from Ansible Galaxy.
  - name: geerlingguy.php_roles
    version: 0.9.3
    source: https://galaxy.ansible.com

Установка нескольких ролей из нескольких файлов

Для крупных проектов директива include в файле requirements.yml предоставляет возможность разделять большой файл на несколько меньших файлов.

Например, проект может иметь файл requirements.yml и файл webserver.yml.

Ниже представлено содержимое файла webserver.yml:

# from github
- src: https://github.com/bennojoy/nginx

# from Bitbucket
- src: git+http://bitbucket.org/willthames/git-ansible-galaxy
  version: v1.4

Следующее показывает содержимое файла requirements.yml , который теперь включает файл webserver.yml:

# from galaxy
- name: yatesr.timezone
- include: <path_to_requirements>/webserver.yml

Чтобы установить все роли из обоих файлов, передайте корневой файл, в данном случае requirements.yml в командной строке следующим образом:

$ ansible-galaxy install -r requirements.yml

Зависимости

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

Зависимости ролей указываются в файле meta/main.yml путём предоставления списка ролей. Если источником роли является Galaxy, вы можете просто указать роль в формате namespace.role_name. Вы также можете использовать более сложный формат в requirements.yml, позволяющий предоставить src, scm, version, и name.

Следующий пример файла meta/main.yml с зависимыми ролями:

---
dependencies:
  - geerlingguy.java

galaxy_info:
  author: geerlingguy
  description: Elasticsearch for Linux.
  company: "Midwestern Mac, LLC"
  license: "license (BSD, MIT)"
  min_ansible_version: 2.4
  platforms:
  - name: EL
    versions:
    - all
  - name: Debian
    versions:
    - all
  - name: Ubuntu
    versions:
    - all
  galaxy_tags:
    - web
    - system
    - monitoring
    - logging
    - lucene
    - elk
    - elasticsearch

Теги наследуются вниз по цепочке зависимостей. Для того, чтобы теги применялись к роли и всем её зависимостям, тег должен быть применён к роли, а не ко всем задачам внутри роли.

Роли, перечисленные в качестве зависимостей, подлежат условиям и фильтрации тегов и могут не выполняться полностью в зависимости от применённых тегов и условий.

Если источником роли является Galaxy, укажите роль в формате namespace.role_name:

dependencies:
  - geerlingguy.apache
  - geerlingguy.ansible

В качестве альтернативы вы можете указать зависимости ролей в сложном формате, используемом в requirements.yml, следующим образом:

dependencies:
  - name: geerlingguy.ansible
  - name: composer
    src: git+https://github.com/geerlingguy/ansible-role-composer.git
    version: 775396299f2da1f519f0d8885022ca2d6ee80ee8

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

Список установленных ролей

Используйте list для отображения имени и версии каждой установленной роли в roles_path.

$ ansible-galaxy list
  - ansible-network.network-engine, v2.7.2
  - ansible-network.config_manager, v2.6.2
  - ansible-network.cisco_nxos, v2.7.1
  - ansible-network.vyos, v2.7.3
  - ansible-network.cisco_ios, v2.7.0

Удаление установленной роли

Используйте remove для удаления роли из roles_path:

$ ansible-galaxy remove namespace.role_name