Galaxy ユーザーガイド

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

デフォルトでは、ansible-galaxy collection install は https://galaxy.ansible.com を Galaxy サーバーとして使用します (GALAXY_SERVER の ansible.cfg ファイルに記載)。追加設定は必要ありません。

Red Hat Automation Hub などの他の Galaxy サーバーを使用している場合は、「ansible-galaxy クライアントの設定」を参照してください。

Galaxy でホストされるコレクションをインストールするには、以下を実行します。

ansible-galaxy collection install my_namespace.my_collection

コレクションを Galaxy サーバーから利用可能な最新バージョンにアップグレードするには、--upgrade オプションを使用します。

ansible-galaxy collection install my_namespace.my_collection --upgrade

ビルドから tarball を直接使用することもできます。

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

ローカルソースディレクトリーからコレクションを構築してインストールできます。ansible-galaxy ユーティリティーは、ディレクトリー内の MANIFEST.json または galaxy.yml メタデータを使用してコレクションを構築します。

ansible-galaxy collection install /path/to/collection -p ./collections

名前空間ディレクトリーに複数のコレクションをインストールすることもできます。

ns/
├── collection1/
│   ├── MANIFEST.json
│   └── plugins/
└── collection2/
    ├── galaxy.yml
    └── plugins/

ansible-galaxy collection install /path/to/ns -p ./collections

-p オプションを使用してインストールパスを指定する場合は、Ansible 自体がコレクションを見つけることが予想される場所であるため、COLLECTIONS_PATHS に設定された値のいずれかを使用します。パスを指定しないと、ansible-galaxy collection install は、COLLECTIONS_PATHS で定義されている最初のパスにコレクションをインストールします。これは、デフォルトでは ~/.ansible/collections です。

また、collections/ansible_collections/ ディレクトリー構造の下で、コレクションを現在の Playbook の横に維持することもできます。

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

コレクションディレクトリー構造の詳細は、「コレクション構造」を参照してください。

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

コマンドラインで Automation Hub からコレクションをダウンロードできます。Automation Hub コンテンツは、サブスクライバーのみで利用できるため、コレクションをダウンロードする前に API トークンをダウンロードし、ローカル環境を設定して提供する必要があります。ansible-galaxy コマンドを使用して Automation Hub からコレクションをダウンロードするには、以下を実行します。

1. Automation Hub API トークンを取得します。https://cloud.redhat.com/ansible/automation-hub/token/ に移動し、バージョンドロップダウンの Load token をクリックして API トークンをコピーします。

2. ansible.cfg ファイルの [galaxy] セクションで、server_list オプションで Red Hat Automation Hub サーバーを設定します。

[galaxy]
server_list = automation_hub

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

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

ansible-galaxy collection install my_namespace.my_collection

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

一度にインストールするコレクションのバージョンは 1 つだけです。デフォルトでは、ansible-galaxy により利用可能な最新バージョンがインストールされます。特定のバージョンをインストールする場合は、バージョン範囲識別子を追加できます。たとえば、コレクションの 1.0.0-beta.1 バージョンをインストールするには、以下を実行します。

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

, で区切って複数の範囲識別子を指定できます。シェルが、>、!、およびその他の演算子を含むコマンド全体を渡すように、一重引用符を使用します。たとえば、1.0.0 以上 2.0.0 未満の最新バージョンをインストールするには、次を実行します。

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

Ansible は、指定する範囲識別子を満たす最新バージョンを常にインストールします。以下の範囲識別子を使用できます。

• *: 最新バージョンです。これがデフォルトです。

• !=: 指定されたバージョンと同等ではありません。

• ==: 指定されたバージョンそのものになります。

• >=: 指定されたバージョン以上になります。

• >: 指定されたバージョンよりも大きくなります。

• <=: 指定されたバージョン以下になります。

• <: 指定されたバージョンよりも小さくなります。

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

requirements.yml ファイルを設定して、1 つのコマンドで複数のコレクションをインストールできます。このファイルは、以下の形式の YAML ファイルです。

---
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)'

各コレクションエントリーに以下のキーを指定できます。

• name

• version

• signatures

• source

• type

version キーは、古いバージョンのコレクションのインストール に記載されているものと同じ範囲識別子形式を使用します。

signatures キーは、コレクションのインストール時および``ansible-galaxy collection verify``時に Galaxy サーバーで見つけられたものを補足するために使用される署名ソースの一覧を受け入れます。署名ソースは、デタッチされた署名が含まれる URI である必要があります。署名が指定されている場合は、--keyring CLI オプションを指定する必要があります。

署名は、Galaxy サーバーのコレクションを検証するためにのみ使用されます。ユーザーが提供した署名は、git リポジトリー、ソースディレクトリー、または URL/tar.gzファイルへのパスからインストールされたコレクションの検証には使用されません。

collections:
  - name: namespace.name
    version: 1.0.0
    type: galaxy
    signatures:
      - https://examplehost.com/detached_signature.asc
      - file:///path/to/local/detached_signature.asc

type キーは file、galaxy、git、url、dir、または subdirs に設定できます。type を省略すると、name キーを使用してコレクションのソースを暗黙的に決定します。

type: git でコレクションをインストールする場合、version キーはブランチまたは git commit-ish オブジェクト（コミットまたはタグ）を参照できます。以下に例を示します。

collections:
  - name: https://github.com/organization/repo_name.git
    type: git
    version: devel

``roles``キーの下にある``requirements.yml``ファイルにロールを追加することもできます。この値は、古い Ansible リリースで使用される要件ファイルと同じ形式に従います。

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

1 つのコマンドで、ロールとコレクションを同時にインストールするには、以下のコマンドを実行します。

$ ansible-galaxy install -r requirements.yml

ansible-galaxy collection install -r または ansible-galaxy role install -r を実行すると、それぞれコレクションまたはロールがインストールされます。

オフラインで使用するコレクションのダウンロード

オフラインで使用するために、コレクション tarball を Galaxy からダウンロードするには、以下を行います。

1. コレクションページに移動します。

2. Download tarball をクリックします。

また、依存するコレクションを手動でダウンロードする必要がある場合があります。

ソースファイルからのコレクションのインストール

Ansible は、複数の方法でソースディレクトリーからインストールすることもできます。

collections:
  # directory containing the collection
  - source: ./my_namespace/my_collection/
    type: dir

  # directory containing a namespace, with collections as subdirectories
  - source: ./my_namespace/
    type: subdirs

出力ファイルを直接指定して、Ansible は``ansible-galaxy collection build`` で収集したコレクションまたは Galaxy からダウンロードしたコレクションをオフライン用にインストールすることもできます。

collections:
  - name: /tmp/my_namespace-my_collection-1.0.0.tar.gz
    type: file

git リポジトリーからのコレクションのインストール

コレクションは、Galaxy または Automation Hub の代わりに git リポジトリーからインストールできます。開発者は、git リポジトリーからインストールし、tarball を作成してコレクションを公開する前にコレクションを確認できます。ユーザーとして git リポジトリーからインストールすることで、Galaxy または Automation Hub にないコレクションまたはバージョンを使用できます。

リポジトリーには galaxy.yml または MANIFEST.json ファイルが含まれている必要があります。このファイルは、コレクションのバージョン番号、namespace などのメタデータを提供します。

# Install a collection in a repository using the latest commit on the branch 'devel'
ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel

# Install a collection from a private github repository
ansible-galaxy collection install [email protected]:organization/repo_name.git

# Install a collection from a local git repository
ansible-galaxy collection install git+file:///home/user/path/to/repo_name.git

├── galaxy.yml
├── plugins/
│   ├── lookup/
│   ├── modules/
│   └── module_utils/
└─── README.md

├── collection1
│   ├── docs/
│   ├── galaxy.yml
│   └── plugins/
│       ├── inventory/
│       └── modules/
└── collection2
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    |   ├── filter/
    |   └── modules/
    └── roles/

ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/collection2/

namespace/
├── collectionA/
|   ├── docs/
|   ├── galaxy.yml
|   ├── plugins/
|   │   ├── README.md
|   │   └── modules/
|   ├── README.md
|   └── roles/
└── collectionB/
    ├── docs/
    ├── galaxy.yml
    ├── plugins/
    │   ├── connection/
    │   └── modules/
    ├── README.md
    └── roles/

# Install all collections in the namespace
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/

# Install an individual collection using a specific commit
ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/collectionA/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5

インストール済みコレクションの一覧表示

インストール済みのコレクションを一覧表示するには、ansible-galaxy collection list を実行します。詳細は、「コレクション一覧の表示」を参照してください。

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

デフォルトでは、ansible-galaxy は https://galaxy.ansible.com を Galaxy サーバーとして使用します (GALAXY_SERVER の ansible.cfg ファイルに記載)。

以下のオプションを使用して、他のサーバー (カスタムの Galaxy サーバーなど) を使用するように ansible-galaxy collection を設定できます。

• 設定ファイル の GALAXY_SERVER_LIST 設定オプションにサーバーリストを設定します。

• --server コマンドライン引数を使用して、個々のサーバーに制限します。

ansible.cfg で Galaxy サーバー一覧を設定するには、以下を行います。

1. server_list セクションの [galaxy] オプションを 1 つ以上のサーバー名に追加します。

2. 各サーバー名に新しいセクションを作成します。

3. 各サーバー名に url オプションを設定します。

4. 必要に応じて、各サーバー名の API トークンを設定します。https://galaxy.ansible.com/me/preferences に移動し、guilabel:Show API key をクリックします。

以下の例は、複数のサーバーを設定する方法を示しています。

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

[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

[galaxy_server.my_galaxy_ng]
url=http://my_galaxy_ng:8000/api/automation-hub/
auth_url=http://my_keycloak:8080/auth/realms/myco/protocol/openid-connect/token
client_id=galaxy-ng
token=my_keycloak_access_token

Galaxy サーバー一覧設定オプション

GALAXY_SERVER_LIST オプションは、優先順位が付けられたサーバー識別子の一覧です。コレクションを検索する場合、インストールプロセスは次の順序で検索します。たとえば、automation_hub を検索してから、my_org_hub、release_galaxy、最後に test_galaxy で、コレクションが見つかるまで行います。次に、実際の Galaxy インスタンスが [galaxy_server.{{ id }}] セクションで定義されます。{{ id }} は、一覧で定義されているサーバー識別子です。このセクションでは、次のキーを定義できます。

• url: 接続する Galaxy インスタンスの URL。必須。

• token: Galaxy インスタンスに対する認証に使用する API トークンキー。username と相互に排他的です。

• username: Galaxy インスタンスに対する Basic 認証に使用するユーザー名。token と相互に排他的です。

• password: Basic 認証に使用するパスワード。username と併用します。

• auth_url: SSO 認証 (例: galaxyNG) を使用する場合は Keycloak サーバー「token_endpoint」の URL です。username と相互に排他的です。token が必要です。

• validate_certs: Galaxy サーバーの TLS 証明書を検証するかどうか。これは、--ignore-certs オプションが提供されるか、GALAXY_IGNORE_CERTS が True に設定されている場合を除き、デフォルトで True に設定されます。

• client_id: 認証に使用する Keycloak トークンの client_id。auth_url および token が必要です。デフォルトの client_id は、Red Hat SSO と連携するクラウドサービスです。

これらのサーバーオプションを ansible.cfg ファイルで定義するだけでなく、それらを環境変数として定義することもできます。環境変数は ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }} の形式です。{{ id }} はサーバー識別子の大文字形式であり、{{ key }} は定義するキーです。たとえば、ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token を設定することで、release_galaxy に token を定義することができます。

Galaxy サーバー 1 つだけを使用する操作 (例: publish コマンド、info コマンド、または install コマンド) の場合、ansible-galaxy collection コマンドは、--server 引数を使用して明示的なサーバーに渡しない限り、server_list の最初のエントリーを使用します。

ロールに関する詳細情報の取得

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=main
    version:
    watchers_count: 1

ロールのインストール

ansible-galaxy コマンドを使用して、Galaxy website からロールをダウンロードします。

$ ansible-galaxy install namespace.role_name

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

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

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

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

1. Galaxy 検索ページでロールを見つけます。

2. 利用可能なバージョンなど、名前をクリックして詳細情報を表示します。

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

Galaxy から特定のバージョンのロールをインストールするには、コンマと GitHub リリースタグの値を追加します。以下に例を示します。

$ ansible-galaxy install geerlingguy.apache,1.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 は、ファイルが古いものと見なし、「basic」フォーマットが非推奨であると想定します。

このファイルの各ロールには、以下の属性が 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 locally cloned git repository (git+file:// requires full paths)
- src: git+file:///home/bennojoy/nginx

# 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: main

# from GitHub, specifying a specific commit hash
- src: https://github.com/bennojoy/nginx
  version: "ee8aa41"

# from a webserver, where the role is packaged in a tar.gz
- name: http-role-gz
  src: https://some.webserver.example.com/files/main.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/main.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/main.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-core.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

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

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

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

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

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

両方のファイルからすべてのロールをインストールするには、以下のように root ファイルを渡します。この例では、以下のように、コマンドラインで requirements.yml を指定します。

$ ansible-galaxy install -r requirements.yml

依存関係

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

ロールの依存関係を定義する方法は 2 つあります。

• meta/requirements.yml の使用

• 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

dependencies:
  - geerlingguy.apache
  - geerlingguy.ansible

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

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

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