---
title: "Ansible Galaxyの使い方：ansible-galaxyコマンドとrequirements.ymlでロール・コレクションを管理する手順【2.21系】"
url: "https://www.issoh.co.jp/tech/details/18469/"
published: 2026-10-17
updated: 2026-10-17
categories: ["自動化"]
publisher: "株式会社一創"
---

# Ansible Galaxyの使い方：ansible-galaxyコマンドとrequirements.ymlでロール・コレクションを管理する手順【2.21系】

Ansible Galaxyは、Ansibleのロールとコレクションを公開・配布する公式のリポジトリです。この記事では、2026年10月時点のansible-core 2.21系を前提に、`ansible-galaxy`コマンドでの検索とインストール、版の範囲指定、requirements.ymlによる依存の固定、自作ロールの雛形づくり、コレクションのビルドと公開までを、コピーして試せるコードで解説します。Galaxyから直接入れてよい環境と、社内のリポジトリに寄せるべき環境の線引きも示します。

## まとめ｜依存はrequirements.ymlに版を固定しプロジェクト内に入れる運用

Galaxyの資産は、ロール（`namespace.role_name`）とコレクション（`namespace.collection`）の2種類です。版の範囲指定や署名検証はコレクションにしか無いため、新しく作るならコレクションを選びます。インストールは`ansible-galaxy install -r requirements.yml`の1行にまとめ、requirements.ymlには必ず版を書きます。

インストール先は`ansible.cfg`でプロジェクト内のディレクトリに向け、開発者の手元とCIで同じ版が入る状態を作ってください。閉域網の本番や監査が厳しい環境では、Galaxyから直接取らず、`ansible-galaxy collection download`で固めたtarballか、社内のAutomation Hubを取得元にします。

## Ansible Galaxyの役割とロール・コレクションの違いを2026年10月時点で整理

Ansibleが対象サーバーへ手順を流す仕組みは[Ansibleとは？エージェントレスの仕組みとメリット・デメリット](https://www.issoh.co.jp/tech/details/6533/)で解説しています。Galaxyは、その手順の部品を他人と共有するための置き場です。

### ロールとコレクションの中身・名前の付け方・版指定の違いを比較表で確認

ロールはタスク・変数・テンプレートをひとまとめにした部品で、コレクションはロールに加えてモジュールやプラグインまで含められる配布単位です。[コレクションのインストールガイド](https://docs.ansible.com/projects/ansible/latest/collections%5Fguide/collections%5Finstalling.html)と[Galaxyのユーザーガイド](https://docs.ansible.com/projects/ansible/latest/galaxy/user%5Fguide.html)の記述を並べると、差は次のとおりです。

| 項目     | ロール                  | コレクション                  |
| ------ | -------------------- | ----------------------- |
| 名前     | namespace.role\_name | namespace.collection    |
| 含められる物 | タスク・変数・テンプレート        | ロール＋モジュール・プラグイン         |
| 版の範囲指定 | 不可                   | 可（>=・<など）               |
| 既定の入れ先 | \~/.ansible/roles    | \~/.ansible/collections |
| 署名検証   | なし                   | GnuPGで可                 |

実務で効いてくるのは版の範囲指定の差です。ロールはタグ・コミット・ブランチのいずれか1つを指すしかなく、「8系の最新」のような書き方ができません。コレクションの中に入ったロールは、`namespace.collection.role`の形の完全修飾名（FQCN）で呼び出します。

### ansible-coreとansibleパッケージで同梱コレクションが変わる点

PyPIの[ansible-core](https://pypi.org/project/ansible-core/)は2.21.5が最新で、Python 3.12以上を要求します。ansible-coreには`ansible.builtin`しか入っていません。`pip install ansible`で入る「ansible」パッケージは、ansible-coreに主要なコレクション群を同梱したものです。

同梱版に頼ると、ansibleパッケージを上げた瞬間にコレクションの版も一斉に変わります。公式ガイドの説明でも、手動で入れたコレクションはansibleやansible-coreを更新しても版が上がらない仕様です。本番の構成管理では、ansible-coreだけを入れ、使うコレクションをrequirements.ymlで個別に指定する構成をすすめます。

## ansible-galaxyコマンドでコレクションとロールを検索・インストールする手順

サブコマンドは`collection`と`role`に分かれています。[ansible-galaxyのコマンドリファレンス](https://docs.ansible.com/projects/ansible/latest/cli/ansible-galaxy.html)によると、collectionにはdownload・init・build・publish・install・list・verifyがあり、roleにはsearch・info・init・install・list・removeなどがあります。

### collection installとrole installの基本構文と導入先

Galaxyにある[community.general](https://galaxy.ansible.com/ui/repo/published/community/general/)の最新は13.5.0（2026年10月5日公開）で、ansible-core 2.18.0以上を要求します。ロールの例には、Galaxyで3,000万回以上ダウンロードされている[geerlingguy.docker](https://github.com/geerlingguy/ansible-role-docker)（最新タグ8.0.0）を使います。

```
# コレクションを入れて確認
ansible-galaxy collection install community.general
ansible-galaxy collection list community.general

# ロールを版指定で入れて確認
ansible-galaxy role install geerlingguy.docker,8.0.0
ansible-galaxy role list

# Galaxy上のロールを検索・詳細表示
ansible-galaxy role search docker --author geerlingguy
ansible-galaxy role info geerlingguy.docker
```

何も指定しなければ、コレクションは`~/.ansible/collections/ansible_collections`、ロールは`~/.ansible/roles`に入ります。ユーザーのホームへのインストールは、別のプロジェクトとの間で版が衝突する原因です。この問題の対処は後半の`ansible.cfg`の設定で扱います。

### 版の範囲指定・–upgrade・–no-depsで依存の入り方を制御する方法

コレクションは、名前の後ろに`:`を付けて版の条件を書けます。使える演算子は`*`・`==`・`!=`・`>=`・`>`・`<=`・`<`の7つで、条件に合う中で最も新しい版が入ります。

```
# 13系の範囲で最新を入れる（演算子を含むので全体を引用符で囲む）
ansible-galaxy collection install 'community.general:>=13.0.0,<14.0.0'

# 入っている版を条件内の最新へ上げる（依存も上がる）
ansible-galaxy collection install --upgrade 'community.general:>=13.0.0,<14.0.0'

# 依存コレクションを取らずに本体だけ入れる
ansible-galaxy collection install --no-deps community.docker:5.4.0
```

依存の自動取得は便利な反面、意図しない版を連れてきます。たとえば[community.docker](https://galaxy.ansible.com/ui/repo/published/community/docker/)の5.4.0は、`community.library_inventory_filtering_v1`の1.0.0以上が依存先として指定されています。このコレクションも自動取得の対象です。`--no-deps`で外すなら、その依存は自分で入れる必要があります。ベータなどのプレリリース版は既定で無視されるので、試すときは`--pre`か`==`での明示が要ります。

## requirements.ymlでロールとコレクションの依存を固定して共有する手順

コマンドを1つずつ打つ運用は、人によって入る版がずれます。Playbookと同じリポジトリにrequirements.ymlを置き、依存の一覧をコードとしてレビューする形にします。Playbookそのものの書き方は[Ansible Playbookの書き方と実行手順](https://www.issoh.co.jp/tech/details/18457/)を参照してください。

### roles・collectionsで依存を指定するrequirements.ymlの実例

1つのファイルに`roles:`と`collections:`の両方を書けます。`ansible-galaxy install -r`なら両方、`collection install -r`ならコレクションだけ、`role install -r`ならロールだけが入ります。

```
# requirements.yml
---
roles:
  - name: geerlingguy.docker
    version: "8.0.0"

collections:
  - name: community.general
    version: ">=13.0.0,<14.0.0"
  - name: community.docker
    version: "==5.4.0"
  - name: ansible.posix
```

```
ansible-galaxy install -r requirements.yml
# 既に入っている版を上書きして入れ直す
ansible-galaxy install -r requirements.yml --force
```

ファイル名の拡張子は`.yml`にしてください。拡張子が無いと、廃止予定の古い書式として読まれるとガイドに明記されています。`version`を書かない`ansible.posix`の行は、実行するたびに最新が入る指定です。ansible-galaxyにはnpmやpipのようなロックファイルの仕組みがないため、本番で再現性が要るコレクションは`==`で固定し、更新はファイルの変更としてレビューを通す運用が手堅いでしょう。

### Gitリポジトリ・社内サーバー・tarballを取得元に指定する書き方

社内で作ったロールやコレクションは、Galaxyに公開せずGitから直接入れられます。コレクションでは`type`にfile・galaxy・git・url・dir・subdirsのいずれかを指定し、ロールでは`src`と`scm`で指定します。

```
collections:
  # 社内Gitのタグを指定（version はブランチかコミット・タグ）
  - name: git+https://git.example.com/infra/acme_baseline.git
    type: git
    version: v1.4.0
  # ビルド済みtarballを社内のWebサーバーから取得
  - name: https://files.example.com/acme-baseline-1.4.0.tar.gz
    type: url

roles:
  - src: git@git.example.com:infra/ansible-role-nginx.git
    scm: git
    version: v2.3.1
    name: nginx
```

ブランチ名を指定すると中身が日々変わるため、本番ではタグかコミットのハッシュを書きます。ガイドは、GitのURLに資格情報を埋め込むことは安全でないとして、SSH鍵・netrc・Gitの`http.extraHeader`を使うよう求めています。CIでトークンを使う場合も、requirements.ymlではなくCIの秘密変数側に置いてください。

### ansible.cfgのcollections\_path指定によるプロジェクト内への配置

インストール先はコマンドの`-p`でも変えられますが、ガイドには落とし穴が書かれています。`ansible-galaxy install -r`でロールとコレクションを同時に入れるとき、独自のパスを指定するとコレクションがスキップされるという制限です。パスは`ansible.cfg`で固定するほうが確実です。

```
# ansible.cfg（Playbookと同じディレクトリに置く）
[defaults]
collections_path = ./collections
roles_path = ./roles

# .gitignore に追記してGitに含めない
collections/ansible_collections/
roles/geerlingguy.docker/
```

この設定で、`ansible-galaxy install -r requirements.yml`はプロジェクト内に依存を入れ、Playbookの実行時もそこから読み込みます。コレクションのディレクトリに自動で付く名前は`ansible_collections`です。CIでは最初のジョブでこのコマンドを流し、手元と同じ版で検証する流れにします。入れたコレクションが改ざんされていないかは`ansible-galaxy collection verify community.general`で、サーバー上のチェックサムと突き合わせられます。

## ansible-galaxy role initで自作ロールを作り変数と依存を定義する手順

社内の手順をロールにまとめると、複数のPlaybookから同じ処理を呼べます。雛形は`ansible-galaxy role init`で作ります。

### role initが作るディレクトリとdefaults・varsの優先順位の違い

```
ansible-galaxy role init --init-path roles acme_nginx
# 主な生成物
# roles/acme_nginx/tasks/main.yml      … 処理の本体
# roles/acme_nginx/handlers/main.yml   … 再起動などの通知先
# roles/acme_nginx/defaults/main.yml   … 利用者が上書きする前提の既定値
# roles/acme_nginx/vars/main.yml       … ロール内部で固定する値
# roles/acme_nginx/templates/  files/  meta/main.yml
```

[ロールの公式ガイド](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Freuse%5Froles.html)によると、標準のディレクトリは7つで、使わないものは消して構いません。迷いやすいのがdefaultsとvarsの違いです。defaultsは優先順位が非常に低く、インベントリやPlaybookの変数でほぼ必ず上書きされます。varsは優先順位が高く、利用者が変えようとしても効きにくい値です。ポート番号のように利用者が変える値はdefaults、パッケージ名のようにOSで決まる値はvarsに置きます。

ロールの探索順は、コレクション内、Playbookから見た`roles/`、`roles_path`、Playbookのディレクトリの順です。依存するロールは`meta/main.yml`の`dependencies`に書くと、呼び出し元より先に実行されます。

### meta/argument\_specs.ymlで引数を検証し誤った変数を実行前に止める

Ansible 2.11からは、ロールが受け取る変数の型や必須かどうかを`meta/argument_specs.yml`で宣言できます。条件に合わない変数が渡されると、タスクを実行する前にロールが失敗します。

```
# roles/acme_nginx/meta/argument_specs.yml
---
argument_specs:
  main:
    short_description: 社内標準のnginxを導入する
    options:
      acme_nginx_port:
        type: int
        default: 80
        description: 待ち受けポート
      acme_nginx_server_name:
        type: str
        required: true
        description: server_name に入れるホスト名
```

ロールをGalaxyや社内で配る場合、利用者は中身を読まずに変数だけを渡します。必須の変数を渡し忘れても途中まで処理が進んでしまう事故を防ぐ仕組みが、この実行前の検証です。ロールの動作を複数のOSで自動テストする方法は[Ansible Moleculeとは？molecule testの実行手順](https://www.issoh.co.jp/tech/details/17630/)で扱っています。

## 自作コレクションをbuildしてGalaxyやAutomation Hubへ公開する手順

モジュールやプラグインを含めて配るなら、ロール単体ではなくコレクションにします。雛形は`ansible-galaxy collection init acme.baseline`で作れます。

### galaxy.yml・meta/runtime.yml：必須値・build\_ignore

[コレクション構成の公式ガイド](https://docs.ansible.com/projects/ansible/latest/dev%5Fguide/developing%5Fcollections%5Fstructure.html)によると、ビルドに必須なのはルートの`galaxy.yml`だけです。対応するansible-coreの版は`meta/runtime.yml`の`requires_ansible`に書きます。

```
# galaxy.yml（抜粋）
namespace: acme
name: baseline
version: 1.4.0
authors:
  - Infra Team
dependencies:
  community.general: ">=13.0.0,<14.0.0"
build_ignore:
  - "*.tar.gz"
  - tests/output

# meta/runtime.yml
requires_ansible: ">=2.18.0"
```

```
ansible-galaxy collection build
# → acme-baseline-1.4.0.tar.gz が生成される
ansible-galaxy collection install acme-baseline-1.4.0.tar.gz
```

`dependencies`に書いたコレクションは、利用者がインストールするときに自動で取得されます。`build_ignore`でテストの出力や過去のtarballを除外しないと、配布物が膨らみます。Galaxyに置けるtarballは20MBまでです。

### APIトークンの設定先とGalaxy公開後に版を差し替えられない制約

[配布の公式ガイド](https://docs.ansible.com/projects/ansible/latest/dev%5Fguide/developing%5Fcollections%5Fdistributing.html)は、GalaxyのAPIトークンを`ansible.cfg`のサーバー設定に置くよう推奨しています。コマンドラインの`--token`は、他のユーザーから見える可能性があるので避けます。

```
# ansible.cfg（ホーム側に置き、Gitには含めない）
[galaxy]
server_list = release_galaxy

[galaxy_server.release_galaxy]
url = https://galaxy.ansible.com/
token = <Galaxyで発行したAPIトークン>
```

```
ansible-galaxy collection publish acme-baseline-1.4.0.tar.gz
```

公開した版は削除も変更もできません。同じ版番号で上げ直すと`conflict.collection_exists`で拒否されるため、誤りを直すときは1.4.1として出し直します。Galaxyの名前空間にはハイフンを使えない点にも注意してください。社内向けのAutomation Hubでは、アップロードの前に名前空間を作っておく必要があります。`server_list`に社内のハブとGalaxyを並べると、先頭から順に探して見つかった時点で取得を終えます。

## Galaxyの公開物をそのまま使う条件と社内リポジトリに寄せる判断基準

判断の軸は、実行環境からインターネットに出られるか、入れた部品の出所を説明する必要があるかの2つです。

### Galaxyから直接入れてよい条件：版を固定でき外部に出られる環境

開発・検証環境と、インターネットに出られるCIで、requirements.ymlに版を固定しているなら、Galaxyから直接入れて問題ありません。community.generalのように頻繁に更新されるコレクションは、範囲指定で受けて月に1回程度の更新レビューを回すほうが、古い版に取り残されるより安全です。

個人が公開しているロールは、更新が止まっていないか、GitHubのリポジトリで最終更新日とIssueの状況を見てから採用します。ダウンロード数は人気の目安であって、保守されている保証にはなりません。

### 社内ミラーに寄せる場面：閉域網・監査要件・承認済み部品だけの本番

本番サーバーへの実行環境がインターネットに出られない、または「承認した版以外は使わない」と監査で説明する必要があるなら、Galaxyから直接取る構成は見送ります。小規模なら、外に出られる端末で`ansible-galaxy collection download -r requirements.yml -p ./dist`を実行し、依存ごと固めたtarballを本番側で`--offline`付きで入れる方法で足ります。

チームが複数あり、承認済みのコレクションを配る仕組みまで要るなら、Red HatのAutomation Platformに含まれるPrivate Automation Hubが選択肢になります。契約の要否は[Ansible Automation Platformの費用と導入判断](https://www.issoh.co.jp/column/details/18090/)、実行基盤は[Ansible Towerの機能と設定手順](https://www.issoh.co.jp/tech/details/18459/)で整理しています。

requirements.ymlの更新をプルリクエストでレビューし、CIで検証してから本番へ流す仕組みを整えたい場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)でご相談を承っています。

## よくある質問

Ansible Galaxyとansible-galaxyコマンドについて、検索されることの多い質問に答えます。

### Ansible Galaxyのロールやコレクションは無料で使えますか？

galaxy.ansible.comで公開されているロールとコレクションは、アカウント無しで検索・ダウンロードできます。ライセンスは公開物ごとに異なるため、商用の構成管理に組み込む前に、各リポジトリのLICENSEファイルを確認してください。公開する側に回る場合だけ、Galaxyへのログインと名前空間、APIトークンが必要になります。

### ロールとコレクションはどちらで作るべきですか？

新しく作るならコレクションをすすめます。版の範囲指定と署名検証が使え、モジュールやプラグインも同じ単位で配れるためです。社内で使うロールが数本だけで、Playbookと同じリポジトリに置くなら、ロールのままでも困りません。配布や再利用の範囲が広がった時点で、ロールをコレクションの`roles/`配下へ移せば済みます。

### 入れたはずのコレクションがPlaybookから見つからないのはなぜですか？

多くは、インストール先と、Playbookの実行時に探すパスがずれている状態です。`-p`で`collections_path`に無いディレクトリへ入れると、Ansibleはそこを探しません。`ansible-config dump --only-changed`で効いている設定を確認し、プロジェクトの`ansible.cfg`が読まれているかを見てください。社内のプロキシ経由でGalaxyに届かずインストール自体が止まる場合は、`--timeout`（既定60秒）を延ばすか、`HTTPS_PROXY`を設定します。

### インストール済みのコレクションを最新に更新するには？

`ansible-galaxy collection install --upgrade community.general`で最新に上がり、依存も一緒に更新されます。requirements.ymlを使っているなら、版の条件を書き換えてから`ansible-galaxy install -r requirements.yml --force`を実行します。コレクションの更新では引数名や既定値が変わることがあるため、各コレクションのCHANGELOGで破壊的変更の有無を確認してから上げてください。

### ロールやコレクションを削除するコマンドはありますか？

ロールは`ansible-galaxy role remove geerlingguy.docker`で削除できます。コレクションには削除用のサブコマンドが無いため、`ansible-galaxy collection list`で表示されるパスのディレクトリを直接消します。プロジェクト内に入れる構成にしていれば、`collections/ansible_collections`ごと消してrequirements.ymlから入れ直すのが確実です。

## 関連記事

- [Ansibleとは？エージェントレスの仕組みとメリット・デメリット、Red Hat AAPの制約](https://www.issoh.co.jp/tech/details/6533/)：Ansible本体の仕組み。
- [Ansible Playbookの書き方と実行手順：–checkでのdry-runとhandlers【2.21系】](https://www.issoh.co.jp/tech/details/18457/)：ロールを呼び出すPlaybookの文法。
- [Ansible Moleculeとは？v26系のansible-native設定とmolecule testの実行手順](https://www.issoh.co.jp/tech/details/17630/)：自作ロールを自動テストする方法。
- [AnsibleでWindowsを管理する手順：WinRM・SSHの接続設定とansible.windowsのPlaybook例【2.21系】](https://www.issoh.co.jp/tech/details/18467/)：ansible.windowsコレクションの使用例。
- [Ansible AWXとは：AWX OperatorでKubernetesへ導入する手順とAAPとの違い【2.19.1】](https://www.issoh.co.jp/tech/details/18461/)：requirements.ymlを読んで実行する基盤。

---

出典: [Ansible Galaxyの使い方：ansible-galaxyコマンドとrequirements.ymlでロール・コレクションを管理する手順【2.21系】](<https://www.issoh.co.jp/tech/details/18469/>)（株式会社一創）