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

См. также

Настройка 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. Параметр 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 не будут скопированы

В качестве альтернативы, роль role_skeleton и игнорирование файлов могут быть настроены в 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.5/reference_appendices/galaxy.html