Ansible Galaxy

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

Веб-сайт
Командная утилита

Веб-сайт

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

Вы также можете использовать этот сайт для совместного использования созданных вами ролей. Авторизовавшись на сайте с помощью учетной записи GitHub, вы можете импортировать роли, делая их доступными для сообщества Ansible. Импортированные роли становятся доступными в индексе поиска Galaxy и отображаются на сайте, что позволяет пользователям находить и загружать их.

Подробнее см. страницу "О сайте".

Командная утилита

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

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

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

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

$ ansible-galaxy install username.role_name

roles_path

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

Вы можете переопределить это, установив переменную окружения ANSIBLE_ROLES_PATH в вашей сессии, определяя roles_path в файле ansible.cfg, или используя опцию --roles-path.

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

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

См. также

Настройка Ansible: Все о конфигурационных файлах

Версия

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

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

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

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

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

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

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

$ ansible-galaxy install -r requirements.yml

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

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

src: Источник роли. Используйте формат username.role_name, если скачиваете из Galaxy; в противном случае укажите URL, ведущий к репозиторию в системе управления версиями Git. Смотрите примеры ниже. Этот атрибут обязателен.
scm: Укажите систему управления версиями. На данный момент поддерживаются только git или hg. Смотрите примеры ниже. По умолчанию используется git.
version:: Версия роли для скачивания. Укажите значение тега выпуска, хеш коммита или имя ветки. По умолчанию используется ветка, заданная по умолчанию в репозитории, в противном случае используется master.
name:: Скачайте роль с определенным именем. По умолчанию используется имя из Galaxy при скачивании из Galaxy, в противном случае используется имя репозитория.

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

# from galaxy
- src: yatesr.timezone

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

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

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

# 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 + webserver.yml

ansible-galaxy install -r requirements.yml

Содержание файла requirements.yml:

# from galaxy
- src: yatesr.timezone

- include: <path_to_requirements>/webserver.yml

Содержание файла webserver.yml:

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

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

Зависимости

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

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

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

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

Зависимости, найденные в Galaxy, можно указать следующим образом:

dependencies:
  - geerlingguy.apache
  - geerlingguy.ansible

Также можно использовать сложную форму следующим образом:

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

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

Примечание

На момент написания этой статьи веб-сайт Galaxy ожидает, что все зависимости ролей будут существовать в Galaxy, и, следовательно, зависимости должны быть указаны в формате username.role_name. Если вы импортируете роль с зависимостью, где значение src является URL, процесс импорта завершится ошибкой.

Создание ролей

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

$ ansible-galaxy init role_name

Вышеуказанное создаст следующую структуру каталогов в текущей рабочей директории:

role_name/
    README.md
    .travis.yml
    defaults/
        main.yml
    files/
    handlers/
        main.yml
    meta/
        main.yml
    templates/
    tests/
        inventory
        test.yml
    vars/
        main.yml

Если вы хотите создать репозиторий для роли, корень репозитория должен быть role_name.

Принудительно

Если каталог, соответствующий имени роли, уже существует в текущей рабочей директории, команда init завершится ошибкой. Чтобы проигнорировать ошибку, используйте опцию –force. Принудительное действие создаст вышеуказанные подкаталоги и файлы, заменив все совпадающие.

Включено контейнеризирование

Если вы создаёте роль с поддержкой контейнеров, передайте --type container в ansible-galaxy init. Это создаст ту же структуру каталогов, что и выше, но заполнит её значениями, соответствующими роли с поддержкой контейнеров. Например, README.md имеет немного другую структуру, файл .travis.yml тестирует роль с помощью Ansible Container, а каталог meta включает файл container.yml.

Использование пользовательского шаблона роли

Директория с пользовательским шаблоном роли может быть передана следующим образом:

$ ansible-galaxy init --role-skeleton=/path/to/skeleton role_name

При предоставлении шаблона init:

скопировать все файлы и каталоги из шаблона в новую роль
любые файлы .j2, найденные вне папки templates, будут обработаны как шаблоны. В настоящий момент единственной полезной переменной является role_name
каталог .git и любые файлы .git_keep не будут скопированы

В качестве альтернативы, шаблон роли и игнорирование файлов могут быть настроены в ansible.cfg

[galaxy]
role_skeleton = /path/to/skeleton
role_skeleton_ignore = ^.git$,^.*/.git_keep$

Поиск ролей

Искать в базе данных 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

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

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

$ ansible-galaxy list

- chouseknecht.role-install_mongod, master
- chouseknecht.test-role-1, v1.0.2
- chrismeyersfsu.role-iptables, master
- chrismeyersfsu.role-required_vars, master

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

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

$ ansible-galaxy remove username.role_name

Авторизация в Galaxy

Использование команд import, delete и setup для управления вашими ролями на сайте Galaxy требует авторизации, и команда login может быть использована для этого. Прежде чем вы сможете использовать команду login, вам необходимо создать учетную запись на сайте Galaxy.

Команда login требует использования ваших учетных данных GitHub. Вы можете использовать имя пользователя и пароль или создать личный токен доступа. Если вы решите создать токен, предоставьте минимальный доступ для него, поскольку он используется только для проверки личности.

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

$ ansible-galaxy login

We need your GitHub login to identify you.
This information will not be sent to Galaxy, only to api.github.com.
The password will not be displayed.

Use --github-token if you do not want to enter your password.

GitHub Username: dsmith
Password for dsmith:
Successfully logged into Galaxy as dsmith

Когда вы выбираете использование имени пользователя и пароля, ваш пароль не отправляется в Galaxy. Он используется для аутентификации с GitHub и создания личного токена доступа. Затем он отправляет токен в Galaxy, который в свою очередь проверяет вашу личность и возвращает токен доступа Galaxy. После завершения авторизации токен GitHub уничтожается.

Если вы не хотите использовать свой пароль GitHub или у вас включена двухфакторная аутентификация с GitHub, используйте параметр –github-token для передачи личного токена доступа, который вы создали.

Импорт роли

Команда import требует, чтобы вы сначала выполнили авторизацию с помощью команды login. После авторизации вы можете импортировать любой репозиторий GitHub, которым вы владеете или к которому у вас есть доступ.

Используйте следующее для импорта роли:

$ ansible-galaxy import github_user github_repo

По умолчанию команда будет ждать завершения процесса импорта Galaxy, отображая результаты по мере его выполнения:

Successfully submitted import request 41
Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
Retrieving GitHub repo githubuser/ansible-role-repo
Accessing branch: master
Parsing and validating meta/main.yml
Parsing galaxy_tags
Parsing platforms
Adding dependencies
Parsing and validating README.md
Adding repo tags as role versions
Import completed
Status SUCCESS : warnings=0 errors=0

Ветка

Используйте параметр –branch для импорта определенной ветки. Если не указано, будет использоваться ветка по умолчанию для репозитория.

Имя роли

По умолчанию имя роли будет получено из имени репозитория GitHub. Однако вы можете использовать параметр –role-name для переопределения этого и установки имени.

Без ожидания

Если присутствует параметр –no-wait, команда не будет ждать результатов. Результаты последнего импорта любой из ваших ролей доступны на веб-сайте Galaxy, посетив раздел «Мои импорты».

Удаление роли

Команда delete требует, чтобы вы сначала выполнили авторизацию с помощью команды login. После авторизации вы можете удалить роль со страницы Galaxy. Вам разрешается удалять только роли, к которым у вас есть доступ к репозиторию в GitHub.

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

$ ansible-galaxy delete github_user github_repo

Это только удаляет роль из Galaxy. Оно не удаляет и не изменяет фактический репозиторий GitHub.

Интеграции Travis

Вы можете создать интеграцию или подключение между ролью в Galaxy и Travis. После создания подключения сборка в Travis автоматически запустит импорт в Galaxy, обновив индекс поиска с последней информацией о роли.

Вы создаете интеграцию с помощью команды setup, но прежде чем интеграция может быть создана, вам необходимо сначала выполнить авторизацию с помощью команды login; вам также понадобится учетная запись в Travis и ваш токен Travis. После готовности используйте следующую команду для создания интеграции:

$ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx

Команда настройки требует вашего токена Travis, однако токен не хранится в Galaxy. Он используется вместе с именем пользователя GitHub и репозиторием для создания хэша, как описано в документации Travis. Хэш хранится в Galaxy и используется для проверки уведомлений, полученных от Travis.

Команда настройки позволяет Galaxy отвечать на уведомления. Чтобы настроить Travis на выполнение сборки в вашем репозитории и отправку уведомления, следуйте руководству Travis по началу работы.

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

notifications:
    webhooks: https://galaxy.ansible.com/api/v1/notifications/

Список интеграций Travis

Используйте параметр –list для отображения ваших интеграций Travis:

$ ansible-galaxy setup --list


ID         Source     Repo
---------- ---------- ----------
2          travis     github_user/github_repo
1          travis     github_user/github_repo

Удаление интеграций Travis

Используйте параметр –remove для отключения и удаления интеграции Travis:

$ ansible-galaxy setup --remove ID

Укажите ID интеграции, которую нужно отключить. Вы можете найти ID, используя параметр –list.

См. также

Роли: Все об Ansible-ролях
Список рассылки: Вопросы? Помощь? Идеи? Загляните на список на Google Groups
irc.freenode.net: IRC-чат-канал #ansible

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/reference_appendices/galaxy.html