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 предположит, что файл имеет устаревший формат «basic».

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

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+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

- include: <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

Укажите идентификатор интеграции, которую необходимо отключить. Вы можете найти идентификатор, используя опцию –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.6/reference_appendices/galaxy.html