Galaxy ユーザーガイド¶

Ansible Galaxy は、コミュニティーが開発したロールの検索、ダウンロード、共有を行う無料サイトである Galaxy の Web サイトを指します。

Galaxy を使用して、Ansible コミュニティーの優れたコンテンツで自動化プロジェクトを活性化させます。Galaxy はロールなどの事前にパッケージ化された作業単位を提供し、Galaxy 3.2 ではコレクションが新たに提供されました。インフラストラクチャーのプロビジョニング、アプリケーションのデプロイ、および日々の作業を行うすべてのタスクにロールがあります。コレクション形式は、複数の Playbook、ロール、モジュール、およびプラグインが含まれる可能性のある自動化の包括的なパッケージを提供します。

Galaxy でコレクションの検索
コレクションのインストール
Galaxy でのロールの検索
- ロールに関する詳細情報の取得
Galaxy からのロールのインストール

Galaxy でコレクションの検索 ¶

Galaxy でコレクションを検索するには、以下を行います。

左側のナビゲーションにある検索アイコンをクリックします。
コレクション にフィルターを設定します。
その他のフィルターを設定し、Enter を押します。

Galaxy は、検索条件に一致するコレクションのリストを表示します。

コレクションのインストール ¶

Galaxy からコレクションのインストール ¶

You can use the ansible-galaxy collection install command to install a collection on your system.

Note

By default, ansible-galaxy uses https://galaxy.ansible.com as the Galaxy server (as listed in the ansible.cfg file under GALAXY_SERVER). You do not need any further configuration. See Configuring the ansible-galaxy client if you are using any other Galaxy server, such as Red Hat Automation Hub).

To install a collection hosted in Galaxy:

ansible-galaxy collection install my_namespace.my_collection

You can also directly use the tarball from your build:

ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections

Note

The install command automatically appends the path ansible_collections to the one specified with the -p option unless the parent directory is already in a folder called ansible_collections.

When using the -p option to specify the install path, use one of the values configured in COLLECTIONS_PATHS, as this is where Ansible itself will expect to find collections. If you don’t specify a path, ansible-galaxy collection install installs the collection to the first path defined in COLLECTIONS_PATHS, which by default is ~/.ansible/collections

You can also keep a collection adjacent to the current playbook, under a collections/ansible_collections/ directory structure.

play.yml
├── collections/
│   └── ansible_collections/
│               └── my_namespace/
│                   └── my_collection/<collection structure lives here>

See コレクション構造 for details on the collection directory structure.

Automation Hub からのコレクションのダウンロード ¶

ansible-galaxy コマンドで Automation Hub からコレクションをダウンロードするには、以下を行います。

Automation Hub API トークンを取得します。https://cloud.redhat.com/ansible/automation-hub/token/ にアクセスし、バージョンのドロップダウンから Get API token をクリックして、API トークンをコピーします。
ansible.cfg ファイルの [galaxy] セクションの下にある server_list オプションで Red Hat Automation Hub サーバーを設定します。

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token

Automation Hub でホストされるコレクションをダウンロードします。

ansible-galaxy collection install my_namespace.my_collection

古いバージョンのコレクションのインストール ¶

By default ansible-galaxy installs the latest collection that is available but you can add a version range identifier to install a specific version.

To install the 1.0.0 version of the collection:

ansible-galaxy collection install my_namespace.my_collection:1.0.0

To install the 1.0.0-beta.1 version of the collection:

ansible-galaxy collection install my_namespace.my_collection:==1.0.0-beta.1

To install the collections that are greater than or equal to 1.0.0 or less than 2.0.0:

ansible-galaxy collection install my_namespace.my_collection:>=1.0.0,<2.0.0

You can specify multiple range identifiers which are split by ,. You can use the following range identifiers:

*: Any version, this is the default used when no range specified is set.
!=: Version is not equal to the one specified.
==: Version must be the one specified.
>=: Version is greater than or equal to the one specified.
>: Version is greater than the one specified.
<=: Version is less than or equal to the one specified.
<: Version is less than the one specified.

Note

The ansible-galaxy command ignores any pre-release versions unless the == range identifier is used to explicitly set to that pre-release version.

要件ファイルを使用した複数のコレクションのインストール ¶

You can also setup a requirements.yml file to install multiple collections in one command. This file is a YAML file in the format:

---
collections:
# With just the collection name
- my_namespace.my_collection

# With the collection name, version, and source options
- name: my_namespace.my_other_collection
  version: 'version range identifiers (default: ``*``)'
  source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'

The version key can take in the same range identifier format documented above.

Roles can also be specified and placed under the roles key. The values follow the same format as a requirements file used in older Ansible releases.

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: 1.9.6

collections:
  # Install a collection from Ansible Galaxy.
  - name: geerlingguy.php_roles
    version: 0.9.3
    source: https://galaxy.ansible.com

Note

While both roles and collections can be specified in one requirements file, they need to be installed separately. The ansible-galaxy role install -r requirements.yml will only install roles and ansible-galaxy collection install -r requirements.yml -p ./ will only install collections.

`ansible-galaxy` クライアントの設定 ¶

By default, ansible-galaxy uses https://galaxy.ansible.com as the Galaxy server (as listed in the ansible.cfg file under GALAXY_SERVER).

You can configure this to use other servers (such as Red Hat Automation Hub or a custom Galaxy server) as follows:

Set the server list in the GALAXY_SERVER_LIST configuration option in The configuration file.
Use the --server command line argument to limit to an individual server.

To configure a Galaxy server list in ansible.cfg:

Add the server_list option under the [galaxy] section to one or more server names.
Create a new section for each server name.
Set the url option for each server name.

For Automation Hub, you additionally need to:

Set the auth_url option for each server name.
Set the API token for each server name. Go to https://cloud.redhat.com/ansible/automation-hub/token/ and click :Get API token from the version dropdown to copy your API token.

The following example shows how to configure multiple servers:

[galaxy]
server_list = automation_hub, my_org_hub, release_galaxy, test_galaxy

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token

token=my_ah_token

[galaxy_server.my_org_hub]
url=https://automation.my_org/
username=my_user
password=my_pass

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token

[galaxy_server.test_galaxy]
url=https://galaxy-dev.ansible.com/
token=my_test_token

Note

You can use the --server command line argument to select an explicit Galaxy server in the server_list and the value of this argument should match the name of the server. To use a server not in the server list, set the value to the URL to access that server (all servers in the server list will be ignored). Also the --api-key argument is not applied to any of the predefined servers. It is only applied if no server list is defined or a URL was specified by --server.

Galaxy server list configuration options

The GALAXY_SERVER_LIST option is a list of server identifiers in a prioritized order. When searching for a collection, the install process will search in that order, e.g. automation_hub first, then my_org_hub, release_galaxy, and finally test_galaxy until the collection is found. The actual Galaxy instance is then defined under the section [galaxy_server.{{ id }}] where {{ id }} is the server identifier defined in the list. This section can then define the following keys:

url: The URL of the galaxy instance to connect to, this is required.
token: A token key to use for authentication against the Galaxy instance, this is mutually exclusive with username
username: The username to use for basic authentication against the Galaxy instance, this is mutually exclusive with token
password: The password to use for basic authentication
auth_url: The URL of a Keycloak server ‘token_endpoint’ if using SSO auth (Automation Hub for ex). This is mutually exclusive with username. auth_url requires token.

As well as being defined in the ansible.cfg file, these server options can be defined as an environment variable. The environment variable is in the form ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }} where {{ id }} is the upper case form of the server identifier and {{ key }} is the key to define. For example I can define token for release_galaxy by setting ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token.

For operations where only one Galaxy server is used, i.e. publish, info, login then the first entry in the server_list is used unless an explicit server was passed in as a command line argument.

Note

Once a collection is found, any of its requirements are only searched within the same Galaxy instance as the parent collection. The install process will not search for a collection requirement in a different Galaxy instance.

Galaxy でのロールの検索 ¶

Galaxy データベースは、タグ、プラットフォーム、作成者、および複数のキーワードで検索します。たとえば、以下のようになります。

$ ansible-galaxy search elasticsearch --author geerlingguy

search コマンドは、検索に一致する最初の 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

Galaxy からのロールのインストール ¶

ansible-galaxy コマンドが Ansible にバンドルされており、これを使用して Galaxy からロールをインストールするか、または git ベースの SCM から直接ロールをインストールすることができます。また、これを使用して、Galaxy の Web サイトで新しいロールの作成、ロールの削除、またはタスクの実行を行います。

デフォルトでは、コマンドラインツールはサーバーアドレス https://galaxy.ansible.com を使用して Galaxy Web サイト API と通信します。`Galaxy プロジェクト<https://github.com/ansible/galaxy>`_ はオープンソースプロジェクトであるため、独自の内部 Galaxy サーバーを実行し、デフォルトのサーバーアドレスを上書きしたい場合があります。この場合は、–server オプションを使用できます。または、ansible.cfg ファイルで Galaxy サーバー値を設定して行います。ansible.cfg の値を設定する方法は、「GALAXY_SERVER」を参照してください。

ロールのインストール ¶

ansible-galaxy コマンドを使用して、`Galaxy の Web サイト<https://galaxy.ansible.com>`_ からロールをダウンロードします。

$ ansible-galaxy install namespace.role_name

ロールをインストールする場所の設定¶

デフォルトでは、Ansible はパスのデフォルトリスト ~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles にあるディレクトリーで、最初に書き込み可能なディレクトリーにロールをダウンロードします。これは、ansible-galaxy を実行しているユーザーのホームディレクトリーにロールをインストールします。

これは、以下のオプションのいずれかで上書きできます。

セッション内に環境変数 ANSIBLE_ROLES_PATH を設定します。
ansible.cfg ファイルに roles_path を定義します。
ansible-galaxy コマンドに --roles-path オプションを使用します。

以下は、--roles-path を使用して現在の作業ディレクトリーにロールをインストールする例を示しています。

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

ロールの特定バージョンのインストール ¶

Galaxy サーバーがロールをインポートする場合は、Sandmantic Version 形式に一致する git タグをバージョンとしてインポートします。その後、インポートされたタグのいずれかを指定して、特定バージョンのロールをダウンロードできます。

ロールで利用可能なバージョンを表示するには、以下を行います。

Galaxy 検索ページでロールを検索します。
名前をクリックして、利用可能なバージョンなどの詳細を表示します。

/<namespace>/<role name> を使用してロールに直接移動することもできます。たとえば、geerlingguy.apache ロールを表示するには、https://galaxy.ansible.com/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

ファイルからの複数ロールのインストール ¶

requirements.yml ファイルにロールを追加して、複数のロールをインストールできます。ファイルのフォーマットは YAML で、ファイル拡張子は .yml または .yaml のいずれかにする必要があります。

以下のコマンドを使用して、requirements.yml: に含まれるロールをインストールします。

$ ansible-galaxy install -r requirements.yml

ここでも、拡張機能は重要です。.yml 拡張を省略すると、ansible-galaxy CLI は、ファイルが古い (現在は非推奨な)、基本的な形式であると見なします。

このファイルの各ロールには、以下の属性が 1 つ以上あります。

src

ロールのソース。Galaxy からダウンロードする場合は namespace.role_name 形式を使用します。それ以外の場合は、git ベースの SCM 内のリポジトリーを指定する URL を指定します。以下の例を参照してください。これは必須の属性です。

scm

SCM を指定します。本ガイドの執筆中は、git または hg のみが許可されています。以下の例を参照してください。デフォルトは git です。

version:

ダウンロードするロールのバージョン。リリースタグの値、コミットハッシュ、またはブランチ名を指定します。デフォルトは、リポジトリーでデフォルトとして設定されたブランチに設定されます。それ以外の場合は master にデフォルト設定されます。

name:

ロールを特定の名前にダウンロードします。Galaxy からダウンロードする場合にデフォルトは Galaxy 名に設定されます。それ以外の場合は、リポジトリーの名前がデフォルトになります。

以下の例を、requirements.yml でロールを指定するためのガイドとして使用してください。

# from galaxy
- name: yatesr.timezone

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

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

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

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

# from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
- name: http-role-xz
  src: https://some.webserver.example.com/files/master.tar.xz

# 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: [email protected]:mygroup/ansible-base.git
  scm: git
  version: "0.1"  # quoted, so YAML doesn't parse this as a floating-point value

同じ requirements.yml ファイルからのロールおよびコレクションのインストール ¶

同じ要件ファイルからロールとコレクションをインストールできますが、いくつか注意点があります。

---
roles:
  # Install a role from Ansible Galaxy.
  - name: geerlingguy.java
    version: 1.9.6

collections:
  # Install a collection from Ansible Galaxy.
  - name: geerlingguy.php_roles
    version: 0.9.3
    source: https://galaxy.ansible.com

Note

ロールとコレクションの両方を 1 つの要件ファイルで指定できますが、個別にインストールする必要があります。 ansible-galaxy role install -r requirements.yml はロールのみをインストールし、ansible-galaxy collection install -r requirements.yml -p ./ はコレクションのみをインストールします。

複数のファイルからの複数ロールのインストール ¶

大規模なプロジェクトの場合、requirements.yml ファイルの include ディレクティブにより、大きなファイルを複数の小さなファイルに分割できます。

たとえば、プロジェクトに requirements.yml ファイルと 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

以下は、webserver.yml ファイルが含まれる requirements.yml ファイルの内容を示しています。

# from galaxy
- name: yatesr.timezone
- include: <path_to_requirements>/webserver.yml

両方のファイルから全ロールをインストールするには、root ファイルを渡します (この場合、コマンドラインの requirements.yml は、以下のようになります。

$ ansible-galaxy install -r requirements.yml

依存関係 ¶

また、ロールは他のロールに依存し、依存関係のあるロールをインストールすると、それらの依存関係が自動的にインストールされます。

ロールの一覧を指定して、meta/main.yml ファイルにロール依存関係を指定します。ロールのソースが Galaxy の場合は、 namespace.role_name 形式のロールのみを指定できます。requirements.yml でより複雑な形式を使用し、src、scm、version、および name を指定することもできます。

以下は、依存するロールを持つ meta/main.yml ファイルの例になります。

---
dependencies:
  - geerlingguy.java

galaxy_info:
  author: geerlingguy
  description: Elasticsearch for Linux.
  company: "Midwestern Mac, LLC"
  license: "license (BSD, MIT)"
  min_ansible_version: 2.4
  platforms:
  - name: EL
    versions:
    - all
  - name: Debian
    versions:
    - all
  - name: Ubuntu
    versions:
    - all
  galaxy_tags:
    - web
    - system
    - monitoring
    - logging
    - lucene
    - elk
    - elasticsearch

タグは、依存関係チェーンを介して*継承* されます。タグをロールおよびそのすべての依存関係に適用するには、タグをロール内のすべてのタスクに適用せずに、ロールに適用する必要があります。

依存関係として一覧表示されるロールは、条件およびタグのフィルタリングの対象となり、適用されているタグや条件によっては、完全には実行されない場合があります。

ロールのソースが Galaxy の場合は、ロールを namespace.role_name 形式で指定します。

dependencies:
  - geerlingguy.apache
  - geerlingguy.ansible

または、以下のように requirements.yml で使用される複雑な形式でロールの依存関係を指定することもできます。

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

ansible-galaxy で依存関係が発生すると、各依存関係が roles_path に自動的にインストールされます。プレイの実行中に依存関係がどのように処理されるかを理解するには、「ロール」を参照してください。

Note

Galaxy は、すべてのロールの依存関係が Galaxy に存在することを想定しているため、依存関係は namespace.role_name 形式で指定されます。src の値が URL である依存関係でロールをインポートすると、インポートプロセスに失敗します。

インストール済みロールの一覧表示 ¶

list を使用して、roles_path にインストールされている各ロールの名前およびバージョンを表示します。

$ ansible-galaxy list
  - ansible-network.network-engine, v2.7.2
  - ansible-network.config_manager, v2.6.2
  - ansible-network.cisco_nxos, v2.7.1
  - ansible-network.vyos, v2.7.3
  - ansible-network.cisco_ios, v2.7.0

インストールされたロールの削除 ¶

remove を使用してロールを roles_path から削除します。

$ ansible-galaxy remove namespace.role_name