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_PATH. Это может быть набор каталогов (например, /etc/ansible/roles:~/.ansible/roles), в этом случае будет использоваться первый доступный каталог. При первой установке Ansible по умолчанию используется /etc/ansible/roles, для доступа к которому требуется право root.

Вы можете переопределить это, установив переменную среды в вашей сессии, определив roles_path в файле ansible.cfg или используя параметр –roles-path. Следующий пример показывает использование параметра –roles-path для установки роли в текущий рабочий каталог:

$ ansible-galaxy install --roles-path . 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

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

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

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

$ ansible-galaxy install -r requirements.yml

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

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

src: Источник роли. Используйте формат имя_пользователя.имя_роли, если загрузка из 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+http://bitbucket.org/willthames/git-ansible-galaxy
  version: v1.4

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

# from GitLab or other git-based scm
- 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

- import_tasks: <path_to_requirements>/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

Зависимости

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

Вы указываете зависимости ролей в файле 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

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

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

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

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

Включено для контейнеров

Если вы создаёте роль с поддержкой контейнеров, используйте параметр –container-enabled. Это создаст ту же структуру каталогов, что и выше, но заполнит её значениями по умолчанию, подходящими для роли с поддержкой контейнеров. Например, 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: #ansible IRC чат-канал

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