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 опущено, CLI ansible-galaxy предполагает, что файл имеет устаревший, теперь не поддерживаемый, «базовый» формат.

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

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

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

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

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

Если каталог, соответствующий имени роли, уже существует в текущей рабочей директории, команда 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

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