Ansible GalaxyでRoleを管理する方法｜requirements.ymlと自社role設計の実践

宮崎智広 この記事の監修：宮崎智広（Linux実務・教育歴20年以上・受講者3,100名超）
ＨＯＭＥ ＞ Linux技術 リナックスマスター.JP（Linuxマスター.JP） ＞ Ansible ＞ Ansible GalaxyでRoleを管理する方法｜requirements.ymlと自社role設計の実践
「AnsibleのPlaybookを書くたびにNginxやMySQLのroleをゼロから書いている。誰かが公開していれば使いたいのに、どこから探せばいいか分からない」
Ansibleを使い始めると、こういった悩みが必ず出てきます。

実は、AnsibleにはAnsible Galaxyという公式のrole共有プラットフォームがあります。世界中のエンジニアが作成したroleが多数登録されており、ansible-galaxy installコマンド1本で自分のプロジェクトに取り込めます。コミュニティroleを上手に活用すれば、構成管理の開発コストを大幅に削減できます。

この記事では、Ansible GalaxyからのroleインストールとPlaybookへの組み込み方、requirements.ymlによる依存バージョン管理、そして自社独自roleの骨格設計まで解説します。単なるコマンドリファレンスではなく、チーム開発で実際に使える設計パターンを重点的に扱います。実行環境はRHEL 10 / Rocky Linux 9です。

この記事のポイント

・Ansible Galaxyはコミュニティroleの公式共有プラットフォームで1コマンドで取り込める
・requirements.ymlでrole依存とバージョンを宣言しチームで環境を統一できる
・ansible-galaxy role initで自社roleの骨格を生成し再利用しやすい設計を実現できる
・本番環境ではバージョン固定とGalaxy/Automation Hubの使い分けが品質の鍵になる


「このままじゃマズい」と感じていませんか？
参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
図解60P／登録10秒／解除も3秒 ／ 詳細はこちら

Ansible Galaxyとは何か｜コミュニティが作ったroleの共有プラットフォーム

Ansible Galaxyは、Red Hatが運営するrole（およびcollection）の公式リポジトリです。URLは https://galaxy.ansible.com/ で、誰でも無料で公開・利用できます。

Galaxyで共有されているコンテンツは主に2種類あります。

・Role: 特定のタスクをまとめた再利用可能なユニット。NginxやPostfixのセットアップroleが多数公開されている
・Collection: モジュール・プラグイン・roleをまとめたパッケージ。ansible.posixやcommunity.generalなど機能別に体系化されている

2026年時点でGalaxy上のrole数は数万件に達しており、一般的なサーバーソフトウェアのroleはほぼ存在すると考えてよいです。「まずGalaxyを検索してから実装を判断する」という習慣が、Ansible経験者の間では標準的なワークフローになっています。

GalaxyとAnsible AWX・Automation Hubとの違い
よく混同されるのがGalaxy・AWX・Automation Hubの3つです。整理すると次のとおりです。

・Galaxy（galaxy.ansible.com）: コミュニティが公開するrole/collectionのパブリックリポジトリ。無料で誰でも利用可能
・AWX（Automation Tower）: PlaybookをGUIから実行・スケジューリングするオーケストレーションツール
・Automation Hub: Red Hat公式のプライベートrole/collectionレジストリ。RHEL/AAP契約者向け

この記事ではGalaxyを中心に解説しますが、後の節でAutomation Hubとの使い分けも触れます。

ansible-galaxyコマンドの基本操作｜検索・インストール・一覧管理

Galaxyの操作は ansible-galaxy コマンドで行います。Ansibleをインストールすると自動的に含まれるため、別途のインストールは不要です。

1. コマンドラインからGalaxyを検索する

Galaxy上のroleはコマンドラインから検索できます。


# キーワードでroleを検索（例: nginxに関するrole）
ansible-galaxy search nginx

# 作者名を指定して検索
ansible-galaxy search nginx --author geerlingguy

# 出力例（抜粋）
Found 176 roles matching your search:

 Name                                       Description
 ----                                       -----------
 geerlingguy.nginx                          Nginx installation for Linux/RHEL
実際には https://galaxy.ansible.com/ をブラウザで開き、Star数・ダウンロード数・最終更新日を目視確認する方が実用的です。特に「最終コミットから1年以上更新がない」roleは採用を避けましょう。

2. roleをインストールする

roleのインストールは ansible-galaxy install コマンドで行います。形式は 作者名.role名 です。


# geerlingguy.nginxをインストール（最新版）
ansible-galaxy install geerlingguy.nginx

# バージョンを指定してインストール
ansible-galaxy install geerlingguy.nginx,4.0.0

# インストール先ディレクトリを指定
ansible-galaxy install -p ./roles geerlingguy.nginx

# 実行結果の例
- downloading role 'nginx', owned by geerlingguy
- downloading role from https://github.com/geerlingguy/ansible-role-nginx/...
- extracting geerlingguy.nginx to /home/rocky9-admin/.ansible/roles/geerlingguy.nginx
- geerlingguy.nginx (4.0.0) was installed successfully
デフォルトのインストール先は ~/.ansible/roles/ です。プロジェクト固有のroleは ./roles/ などプロジェクト内に置く方が管理しやすいです。ansible.cfg に roles_path = ./roles:~/.ansible/roles と設定することで複数のパスを指定できます。

3. インストール済みroleの確認と削除


# インストール済みroleの一覧（バージョン付き）
ansible-galaxy list

# 出力例
# - geerlingguy.nginx, 4.0.0
# - geerlingguy.mysql, 5.0.0
# - geerlingguy.docker, 7.1.0

# roleを削除
ansible-galaxy remove geerlingguy.nginx

# 確認（削除されていること）
ansible-galaxy list

Playbookへの組み込み方｜Galaxy roleを実際に使う

Galaxy roleをインストールしたら、PlaybookのRoles節から呼び出すだけです。複雑な設定は不要で、role名を指定するとAnsibleが自動的に tasks/main.yml を実行します。


# site.yml - Galaxy roleを使ったPlaybook例
---
- name: Webサーバーのセットアップ
  hosts: webservers
  become: yes
  roles:
    - role: geerlingguy.nginx
      vars:
        nginx_vhosts:
          - listen: "80"
            server_name: "example.com"
            root: "/var/www/html"
            index: "index.html index.php"
Galaxy roleはほぼ必ずデフォルト変数（defaults/main.yml）を持っています。インストール後に ~/.ansible/roles/geerlingguy.nginx/defaults/main.yml を開き、どの変数で挙動をカスタマイズできるかを確認するのが最初のステップです。

実際のコマンド実行結果（Rocky Linux 9 実機）

[rocky9-admin@control ansible]$ ansible-playbook -i inventory/hosts site.yml

PLAY [Webサーバーのセットアップ] **************************

TASK [Gathering Facts] *****************************
ok: [web01.example.com]

TASK [geerlingguy.nginx : Install Nginx packages] **
changed: [web01.example.com]

TASK [geerlingguy.nginx : Copy nginx configuration] 
changed: [web01.example.com]

TASK [geerlingguy.nginx : Start and enable Nginx]  
changed: [web01.example.com]

PLAY RECAP *****************************************
web01.example.com : ok=8  changed=3  unreachable=0  failed=0
このように、Galaxy roleを使うと自分でNginxのyumインストール・設定・サービス起動のタスクを書かなくても、Playbookが完結します。Nginxの設定変更が必要な場合はrole内の変数を上書きするだけで対応できます。

なお、Postfixの設定roleなどもGalaxy上に豊富に公開されています。Postfixそのものの設定パラメータについてはPostfixの基本設定の解説も参考にしてください。

Galaxy roleのPlaybookへの組み込み設計を実機で体験したい方は、＞＞ Ansibleハンズオン講座の詳細を見る をご覧ください。

信頼できるGalaxy roleの選び方｜品質チェックの3基準

Galaxy roleは誰でも公開できるため、品質にばらつきがあります。本番環境に取り込む前に、次の3基準で確認しましょう。

基準①: Star数・ダウンロード数・作者の実績
Star数が1,000を超えているroleは多くのプロジェクトで実績があります。特にgeerlingguy（Jeff Geerling氏）は「Ansible for DevOps」の著者で、Nginx・MySQL・Docker・Gitなど高品質roleを多数公開しています。実績ある作者のroleを優先的に採用しましょう。

基準②: 最終更新日とAnsibleバージョン対応
最終コミットが2年以上前のroleは避けましょう。サポートするLinuxディストリビューションも確認します。READMEに「RHEL/Rocky Linux対応」の記載があるかどうかが判断のポイントです。AnsibeのバージョンアップでAPIが変わることがあり、古いroleでは非推奨のモジュールが使われている場合があります。

基準③: テストの存在
Moleculeによるテストが含まれているroleは品質が高い傾向にあります。GitHubリポジトリで .github/workflows/ や molecule/ ディレクトリがあるかどうかを確認しましょう。CIで自動テストが通っているroleは信頼性が高いです。

採用を見送る目安としては「直近のIssueが放置されている」「README.mdが内容薄く最終更新が古い」「変数名がわかりにくく上書き方法が不明」などが挙げられます。

requirements.ymlで依存を宣言する｜チーム開発の必須設計パターン

複数のGalaxy roleを使うプロジェクトでは、requirements.ymlで依存roleを宣言するのが標準です。このファイル1つで必要なroleを一括インストールでき、チーム全員が同じ環境を再現できます。

1. requirements.ymlの基本構造


# requirements.yml
---
roles:
  - name: geerlingguy.nginx
    version: 4.0.0
  - name: geerlingguy.mysql
    version: 5.0.0
  - name: geerlingguy.docker
    version: 7.1.0

collections:
  - name: ansible.posix
    version: ">=1.5.0"
  - name: community.general
    version: ">=8.0.0"
roles セクションにはGalaxy roleを、collections セクションにはCollectionを記述します。CollectionはAnsible 2.9以降で導入された新しい配布形式で、モジュール・プラグイン・roleをまとめてパッケージングしたものです。

2. バージョンを固定して意図しないアップデートを防ぐ

バージョンを指定せずにインストールすると、常に最新版が入ります。一見便利に思えますが、roleの新バージョンで変数名が変更されたり、非推奨オプションが削除されたりした場合、突然Playbookが失敗します。

本番環境では必ずバージョンを固定しましょう。

・バージョン固定の書き方: version: 4.0.0（セマンティックバージョニング）
・範囲指定の書き方: version: ">=4.0.0,<5.0.0"（マイナー更新は許容・メジャー更新はブロック）
・最新版を明示的に取得: version: "*"（開発環境でのみ使用）

バージョンを上げる際は、changelogを確認してからstaging環境でテストし、問題がなければrequirements.ymlを更新してGitにコミットします。「requirements.ymlの更新 = 環境変更の履歴」という管理がチームで徹底できます。

3. 一括インストールのワークフロー


# requirements.ymlに定義したrole/collectionをすべてインストール
ansible-galaxy install -r requirements.yml

# プロジェクト内のrolesディレクトリにインストール
ansible-galaxy install -r requirements.yml -p ./roles

# Collectionも含めて一括インストール
ansible-galaxy collection install -r requirements.yml

# インストール結果の確認
ansible-galaxy list
CI/CDパイプラインでPlaybookを実行する際は、このコマンドを事前ステップとして組み込むことで、実行ごとにrequirements.ymlの内容が反映された環境を再現できます。新メンバーがプロジェクトに参加した際も、ansible-galaxy install -r requirements.ymlを1回実行するだけで必要なroleがすべて揃います。

自社独自roleの骨格設計｜ansible-galaxy role initから始める

Galaxy roleを活用しながら、自社特有の設定は独自roleとして作成します。その際に ansible-galaxy role init コマンドで骨格ディレクトリを生成するのが標準的なアプローチです。

1. role initで骨格ディレクトリを生成する


# company_webserverというroleを作成
ansible-galaxy role init company_webserver

# 作成されたディレクトリ構造を確認
tree company_webserver/

company_webserver/
├── README.md
├── defaults/
│   └── main.yml
├── files/
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
├── tasks/
│   └── main.yml
├── templates/
├── tests/
│   ├── inventory
│   └── test.yml
└── vars/
    └── main.yml

2. 各ディレクトリの役割と設計の鉄則

・tasks/main.yml: roleのメインタスク。処理の順序はここで定義する
・defaults/main.yml: デフォルト変数。roleを呼び出す側で上書き可能（最も低い優先度）
・vars/main.yml: roleの内部変数。defaultsより優先度が高く、呼び出し側での上書きは推奨しない
・handlers/main.yml: notifyで呼ばれるhandler。サービス再起動などを記述する
・templates/: Jinja2テンプレートファイル（.j2）。環境別設定ファイルを動的生成する
・files/: 静的ファイル。copyモジュールで配布するファイルを置く
・meta/main.yml: roleのメタ情報とGalaxy依存の宣言

自社roleを作る際のポイントは「1 role = 1つの責務」です。「WebサーバーとデータベースをまとめたMEGAなrole」は再利用性が低く、テストも難しくなります。NginxはNginxのrole、MariaDBはMariaDBのroleに分けて、Playbookから組み合わせる設計が推奨です。

meta/main.yml による依存roleの宣言

# meta/main.yml - 自社roleがGalaxy roleに依存する場合
---
dependencies:
  - role: geerlingguy.nginx
    vars:
      nginx_vhosts:
        - listen: "80"
          server_name: "example.com"
meta/main.yml に依存roleを宣言すると、自社roleを呼び出すだけで依存するGalaxy roleも自動的に実行されます。ただし依存が複雑になりすぎると管理が難しくなるため、「まず独立して使えるシンプルな設計」を基本にしましょう。

GalaxyとAutomation Hubの使い分け

Red Hat Enterprise Linux（RHEL）の環境では、パブリックなGalaxyとは別にAutomation Hubが利用できます。

・Galaxy（galaxy.ansible.com）: コミュニティベース。誰でも公開・利用可能。品質はまちまち
・Automation Hub（console.redhat.com）: Red Hat認定のcollection。RHEL/AAP（Ansible Automation Platform）契約者向け

本番環境でRHELを使う場合は、Automation Hub上のRed Hat認定collectionを優先的に使いましょう。ansible.cfg の [galaxy] セクションでリポジトリの優先順位を設定できます。


# ansible.cfg - Automation Hubを優先リポジトリに設定
[galaxy]
server_list = automation_hub, release_galaxy

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

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
RHELを使わない環境（Rocky Linux・Ubuntu等）では、パブリックGalaxyで実績あるroleを requirements.yml で管理するアプローチで十分です。

トラブルシュート｜よくあるエラーと対処法

1. 「ERROR! the role 'xxx' was not found」

症状: Playbookを実行すると指定したroleが見つからないエラーが出る。

原因と対処: roleのインストール先がAnsibleの roles_path に含まれていない。ansible.cfg で roles_path を確認・修正する。


# ansible.cfg でroles_pathを確認・設定
[defaults]
roles_path = ./roles:~/.ansible/roles

# 現在の設定を確認
ansible-config dump | grep ROLES_PATH

# 出力例
DEFAULT_ROLES_PATH(/etc/ansible/ansible.cfg) = ['/home/user/.ansible/roles', '/usr/share/ansible/roles']

2. 「WARNING: The 'xxx' role has been deprecated」

症状: インストール時に非推奨（deprecated）の警告が出る。

対処: そのroleはGalaxyでメンテナンスが終了している可能性があります。代替のcollectionやroleをGalaxyで検索してください。多くの古いGalaxy roleは対応するCollectionに移行されています。ansible-galaxy search で新しい代替を探しましょう。

3. NTPの時刻同期roleを使う際の注意点

NTPサーバーのセットアップroleもGalaxy上に存在しますが、RHEL 9/10ではchronyが標準になっているため、ntpd系のroleは要注意です。ntpd 時刻同期設定の解説も参考に、対応バージョンを確認してから採用しましょう。

4. プロキシ環境で「SSL Certificate Verification Failed」が出る

症状: プロキシ環境下で ansible-galaxy install が失敗する。


# プロキシを設定してからインストール
export HTTPS_PROXY=http://proxy.example.com:8080
ansible-galaxy install geerlingguy.nginx

# または ansible.cfg でプロキシを設定
# ansible.cfg
[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
# proxy=http://proxy.example.com:8080

本記事のまとめ

やりたいこと コマンド/設定
Galaxy roleをインストールする ansible-galaxy install 作者名.role名
バージョン指定でインストールする ansible-galaxy install 作者名.role名,バージョン番号
requirements.ymlから一括インストールする ansible-galaxy install -r requirements.yml
インストール済みroleの一覧を確認する ansible-galaxy list
新規roleの骨格ディレクトリを生成する ansible-galaxy role init role名
roleのインストール先ディレクトリを指定する ansible-galaxy install -p ./roles 作者名.role名
Ansible Galaxyを活用することで、NginxやMySQLなど一般的なサーバーソフトウェアのroleを自前で書く必要がなくなります。requirements.ymlでバージョンを固定して宣言的に管理し、自社固有の設定は ansible-galaxy role init で生成した骨格に実装するアプローチが、実務での標準パターンです。

Galaxy roleは「自分でゼロから書く手間を省く」という使い方だけでなく、「高品質な実装を参考にして自社roleの設計を学ぶ」という使い方もできます。geerlingguy 等の著名作者のroleはベストプラクティスの宝庫です。実際に tasks/main.yml や defaults/main.yml を読んで、設計パターンを身につけることをおすすめします。
現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、20年以上の運用経験を持つ現役エンジニアが基礎から教えます。
Ansible実践ハンズオンの詳細を見る ＞＞

関連記事

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は1分、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。

登録10秒／合わなければ解除3秒 ／ 詳細はこちら

Linux無料マニュアル（図解60P） 名前とメールで30秒登録
宮崎 智広

この記事を書いた人

宮崎 智広（みやざき ともひろ）

株式会社イーネットマーキュリー代表。現役のLinuxサーバー管理者として20年以上の実務経験を持ち、これまでに累計3,100名以上のエンジニアを指導してきたLinux教育のプロフェッショナル。「現場で本当に使える技術」を体系的に伝えることをモットーに、実践型のLinuxセミナーの開催や無料マニュアルの配布を通じてLinux人材の育成に取り組んでいる。

趣味は、キャンプにカメラ、トラウト釣り。好きな食べ物は、ラーメンにお酒。休肝日が作れない、酒量を減らせないのが悩み。最近、ドラマ「フライトエンジェル」を観て涙腺が崩壊しました。