1.1 check mode と diff mode#

ansible-playbook site.yml --check --diff を使うと、リモートを変更せずに「何がどう変わるか」を確認できる¹。エージェントが作った playbook の差分を MR に貼り、人間が承認してから適用する、というフローにそのまま組み込める。

注意点もある¹。

• check mode は「シミュレーション」で、check mode 非対応のモジュールは何も報告せず、何もしない
• 前のタスクの register 結果に依存する条件分岐は、check mode 中は意味のある結果にならない
• diff 出力にはシークレットが含まれうる。該当タスクには diff: false を付ける

1.2 冪等性はモジュール単位で成り立つ#

Ansible が冪等なのは、各モジュールが「現在の状態」と「あるべき状態」を比べて、差があるときだけ変更するように作られているからだ。shell / command はこの比較をしないので、そのまま書くと毎回 changed になり、冪等性が崩れる。

つまり、Ansible を使っていても中身が shell: だらけなら、散らかったシェルスクリプトと変わらない。次の章のガードレールが必要になる理由はここにある。

1.3 記法がフレームワークで担保される#

シェルスクリプトは、同じ処理でも書き方がいくらでもある。パッケージを入れる処理ひとつでも、apt-get install -y か apt install か、dpkg -s で事前に確認するか、set -e を付けるか、エラーをどう扱うかで流儀が分かれる。エージェントに大量に書かせると、流儀の違うシェルが溜まり、その一つひとつを人間が読んで確かめることになる。

Ansible では、この「どう書くか」をフレームワークとモジュールが決める。

1
- name: Install packages
2
  ansible.builtin.apt:
3
    name: [curl, gnupg2]
4
    state: present

レビューで確認するのは、主に「どのモジュールに、どの値を渡したか」になる。インストール済みかどうかの確認、エラー処理、冪等性はモジュールの側で担保される。記法から外れたものは ansible-lint（2.1節）が機械的に検出する。when の条件やテンプレートは引き続き読む必要があるが、人間が読む量はかなり減る。エージェントが大量に書く時代には、ここが効いてくる。

1.4 コミュニティが発達していて、知見を共有・検索しやすい#

• モジュール名が共通の語彙になる: 「community.docker.docker_compose_v2 で state: restarted にすると冪等でない」のように、問題をモジュール名とパラメータ名で正確に言い表せる。シェルは書き方が人それぞれなので、検索しても自分のケースに当てはまる情報に行き着きにくい
• 情報源が整っている: 公式ドキュメントには、モジュールごとにパラメータ・check mode 対応・使用例が同じ形式で載っている⁶。ansible パッケージに同梱される collection だけでも、amazon・cisco・community・vmware など多数の名前空間がある⁷。role と collection の共有基盤として Ansible Galaxy があり⁸、4章で触れる NVIDIA のドライバ role も Galaxy から nvidia.nvidia_driver として入れられる⁹。質問や議論の場として Ansible Forum もある¹⁰
• エージェントも同じ情報源を使える: ansible-doc community.docker.docker_compose_v2 のように、制御ノード上でモジュールのドキュメントを引ける。エージェントにこれを実行させてから書かせると、記憶に頼ったパラメータの誤りを減らせる
• 社内でも共有しやすい: 書き方が揃っているので、別チームが書いた role でも読み解ける

1.5 YAML と HCL：記法と抽象化の単位#

1.3節の利点は Terraform にも当てはまる。どちらも記法をツールが担保し、抽象化の単位が決まっている。違うのは、汎用フォーマットに乗るか、専用の設定言語を持つかだ。

YAML の良さは、汎用フォーマットであること。yq や Python でそのまま解析できるので、「全 playbook から shell: を使っている箇所を抜き出す」「group_vars のドライバブランチを一覧にする」といった処理を、専用のパーサなしで書ける。インデントとキー・値だけなので、Ansible を書かないレビュー担当でも何をしているかを追える。CI 設定や Compose などで見慣れた形式なので、エージェントも書き慣れている印象がある（定量的な根拠はない）。

HCL の良さは、書式がツールで1つに決まること¹²。CI で terraform fmt -check を回せば、エージェントが書いたコードの見た目の揺れを機械的にゼロにできる。また、module が抽象化の境界になり、利用側は入力変数だけを渡す¹³。エージェントには「レビュー済みの module を呼び出すコードだけを書かせる」という制約をかけやすい。

1
module "gpu_node" {
2
  source        = "./modules/gpu_node"
3
  instance_type = "g6.xlarge"
4
  count         = 2
5
}

YAML には落とし穴もある。YAML 1.1 では yes / no / on / off が真偽値として解釈されうる。yamllint の truthy ルールは、既定で true / false 以外を検出する¹⁴。ドライバのブランチ番号のように文字列として扱いたい値も、"580" と引用符で囲んでおくほうが安全だ（4章の例でもそうしている）。

2.1 ansible-lint で「shell への逃げ」を止める#

エージェントは適切なモジュールが分からないと shell: で済ませがちだ。ansible-lint の次のルールで検出できる²。

プロファイルは min → basic → moderate → safety → shared → production の順に厳しくなり、上位は下位を包含する³。エージェントが書くコードには production（少なくとも shared）を指定すると、上の4ルールがすべて効く。

1
profile: production

なお、ルールの所属プロファイルはバージョンで変わる可能性がある。導入時に ansible-lint --list-profiles で確認しておく。

2.2 Molecule で冪等性をテストする#

Molecule は role・playbook・collection のテストフレームワークで、コンテナ・VM・ネットワーク機器などをテスト対象にできる⁴。デフォルトのテストシーケンスは次のとおりで、converge（適用）の直後に idempotence ステップがある⁵。

1
dependency → cleanup → destroy → syntax → create → prepare
2
→ converge → idempotence → side_effect → verify → cleanup → destroy

idempotence ステップは、一般に「もう一度流して changed が出ないこと」を確かめるものとして使われている。これを CI で回せば、エージェントの出力を人間が1行ずつ読む負担が減る。

2.3 変数の置き場所をルール化する#

Ansible の変数の優先順位は 22段階ある¹⁵。YAML 自体は読みやすくても、「この値は最終的にどこから来るのか」を追うのは難しくなりやすい。エージェントへの指示（CLAUDE.md や AGENTS.md）に、次のようなルールを入れておくとレビューしやすさを保てる。

• 環境差分は group_vars/ / host_vars/ に寄せる
• role のデフォルト値は defaults/main.yml だけに置く
• -e（extra vars、最優先¹⁵）は緊急時以外使わない
• Jinja2 テンプレートに複雑な条件分岐を書かない

2.4 ドリフト検知#

冪等でも、手作業の変更は Ansible を流さない限り見つからない。対策として、定期的に --check --diff を流し、changed が出たらドリフトとして通知する運用が紹介されている¹⁶。さらに進めると、Event-Driven Ansible（ansible-rulebook）¹⁷でイベントを受けて修復用の playbook を起動する構成も考えられる。ただ、こちらは公式の専用ガイドが見当たらず、デモやコミュニティ事例が中心だ。

2.5 推奨フロー#

ここまでを1本のフローにすると次のようになる。

エージェントの担当は「書く」まで、人間の担当は「差分を承認する」だけ、という分担にできる。

2.6 Claude Code に当てはめると#

普段 Claude Code で作業しているなら、上のガードレールは次の場所に置ける。

スクリプトを書かせる場合との違いは、検査の対象が「エージェントが毎回違う形で書いたコード」ではなく「決まった形のYAMLと、その差分」になることだ。

4.1 Ansible と Docker の責務を分ける#

NVIDIA Container Toolkit はホストにドライバが入っていることを前提にしている²²。なのでドライバはホスト側にだけ入れ、コンテナ側は CUDA のユーザー空間ライブラリだけを持つ構成にする。

もう1つの原則は、Dockerfile の中で Ansible を使わないこと。イメージの中身は Dockerfile と CI で作り、Ansible は「どのイメージを、どの設定で起動するか」だけを担当する。こうすると境界がはっきりする。

4.2 ドライバと CUDA は1本の鎖#

コンテナ化しても、ホストのドライバとコンテナ内の CUDA のバージョンだけは連動する。NVIDIA の minor version compatibility で求められる Linux ドライバの最低バージョンは次のとおり²³。

さらに PyTorch の pip wheel は、CUDA ランタイム・cuDNN・NCCL などを nvidia-* の pip パッケージとして依存に持つ²⁴。CUDA のユーザー空間ライブラリはコンテナ内の Python の依存として入り、ホストに必要なのはドライバだけになる。つまり次の4つは1本の鎖でつながっている。

1
ホストのドライバ（branch 580）
2
   └─ 対応できる CUDA の範囲（13.x まで）
3
        └─ コンテナ内の torch の CUDA variant と nvidia-* pip パッケージ
4
             └─ 推論速度・使えるカーネル（cuDNN / NCCL のバージョン）

速度やライブラリのバージョンを決めるのは開発者なので、鎖の根元のドライバも開発側で持つのが筋が通っている。そのうえで、ドライバを入れた後に要件を満たしているかを検査するタスクを残しておく。誰かが手作業でドライバを変えた場合にも、デプロイ前に止められる。

1
gpu_driver_branch: "580"
2
gpu_min_driver_major: 580       # CUDA 13.x イメージを使う場合
3

4
# roles/gpu_host/tasks/check_driver.yml
5
- name: Get driver version
6
  ansible.builtin.command: nvidia-smi --query-gpu=driver_version --format=csv,noheader
7
  register: gpu_driver
8
  changed_when: false
9

10
- name: Assert driver meets CUDA requirement
11
  ansible.builtin.assert:
12
    that:
13
      - (gpu_driver.stdout_lines[0].split('.')[0] | int) >= gpu_min_driver_major
14
    fail_msg: "Driver {{ gpu_driver.stdout_lines[0] }} < {{ gpu_min_driver_major }}"

command を使っているが、changed_when: false で「状態を変えない読み取り」だと宣言しているので、no-changed-when には引っかからない。

4.3 ドライバのブランチを選んで固定する#

NVIDIA のデータセンター向けドライバには3種類のブランチがある²⁵。

本番は PB か LTSB を選び、ブランチ単位で固定する。Ubuntu では、NVIDIA が提供する pinning パッケージ（例: nvidia-driver-pinning-580）をドライバより先に入れるのが推奨されている²⁶。意図しない apt upgrade でブランチが変わるのを防げる。カーネルモジュールは open 版（nvidia-open パッケージ）で入れる²⁷。

1
# roles/gpu_host/tasks/driver.yml（CUDA の apt リポジトリ追加は省略）
2
- name: Pin driver branch
3
  ansible.builtin.apt:
4
    name: "nvidia-driver-pinning-{{ gpu_driver_branch }}"
5
    state: present
6

7
- name: Install NVIDIA driver (open kernel modules)
8
  ansible.builtin.apt:
9
    name: nvidia-open
10
    state: present
11
  register: driver_install
12

13
- name: Reboot if driver changed
14
  ansible.builtin.reboot:
15
  when: driver_install is changed

ただし Ubuntu では、580 以前のブランチはパッケージ名にブランチ番号が入っていて、upgrade / downgrade でのブランチ切り替えがサポートされるのは 590 以降だけ、という制約がある²⁶。別案として NVIDIA 公式の role（nvidia.nvidia_driver）もあり、インストール時にノードを再起動するため、GPU ノードとは別のノードから実行することが推奨されている⁹。再起動には ansible.builtin.reboot を使えば、ホストの復帰待ちまで含めて扱える²⁸。

4.4 更新はローリングで（設計案）#

ドライバ更新では再起動が必要になり、サービスが止まる。複数台あるなら serial で1台ずつ進める²⁹。以下は公式機能を組み合わせた設計案で、実機で検証したものではない。

1
- name: Rolling driver update
2
  hosts: gpu_servers
3
  serial: 1                    # 1台ずつ。[1, "50%"] のように段階的にもできる
4
  tasks:
5
    - name: Stop service
6
      community.docker.docker_compose_v2:
7
        project_src: /opt/inference
8
        state: stopped
9
    - name: Update driver via gpu_host role
10
      ansible.builtin.import_role:
11
        name: gpu_host           # pinning 切替 → ドライバ更新 → reboot → assert
12
    - name: Smoke test (GPU visible from container)
13
      ansible.builtin.command: docker run --rm --gpus all ubuntu nvidia-smi
14
      changed_when: false
15
    - name: Start service
16
      community.docker.docker_compose_v2:
17
        project_src: /opt/inference
18
        state: present

1台目でスモークテストが落ちれば、残りの台には進まない。「検証済みの手順で実行するだけ」を更新作業にも広げる仕組みになる。

また、ドライバのカーネルモジュールは実行中のカーネルと組み合わせて動く。一般的な運用知見として、カーネルの自動更新後にモジュールがロードできず GPU が見えなくなるケースが知られているので、カーネル更新もドライバ更新と同じ playbook で扱い、unattended-upgrades に任せきりにしないほうが安全だ（挙動は DKMS かプリビルドかで変わる）。

4.5 コンテナ実行環境とデプロイ#

NVIDIA Container Toolkit の公式手順は、apt リポジトリを追加 → パッケージをインストール → nvidia-ctk runtime configure --runtime=docker → Docker 再起動、という流れになっている²²。

nvidia-ctk runtime configure は /etc/docker/daemon.json を書き換えるコマンドだ²²。そのまま command で呼ぶと冪等性が崩れ、ansible-lint にも指摘される。代わりに、同じ内容の daemon.json をテンプレートで管理すると diff でレビューでき、冪等にもなる。生成内容はバージョンで変わりうるので、一度実機で nvidia-ctk を実行し、出力をコピーしてテンプレートにするのが確実だ。

1
- name: Install NVIDIA Container Toolkit (version pinned)
2
  ansible.builtin.apt:
3
    name:
4
      - "nvidia-container-toolkit={{ nvidia_ctk_version }}"
5
      - "nvidia-container-toolkit-base={{ nvidia_ctk_version }}"
6
      - "libnvidia-container-tools={{ nvidia_ctk_version }}"
7
      - "libnvidia-container1={{ nvidia_ctk_version }}"
8
    state: present
9
  notify: Restart docker
10

11
- name: Configure Docker daemon (nvidia runtime)
12
  ansible.builtin.template:
13
    src: daemon.json.j2
14
    dest: /etc/docker/daemon.json
15
    mode: "0644"
16
  notify: Restart docker

compose.yaml での GPU 指定は deploy.resources.reservations.devices を使う。capabilities は必須で、count と device_ids は同時に指定できない³⁰。

1
services:
2
  inference:
3
    image: registry.example.com/team/inference@sha256:...   # digest で固定
4
    deploy:
5
      resources:
6
        reservations:
7
          devices:
8
            - driver: nvidia
9
              device_ids: ["0"]
10
              capabilities: [gpu]

Ansible からは community.docker.docker_compose_v2 で起動する。このモジュールは check mode に対応している。ただし state: restarted と recreate: always は冪等ではないので、通常のデプロイでは使わない⁶。最後に、公式のサンプルワークロード³¹相当のスモークテストを changed_when: false で入れておくと、本番で流すたびに「GPU がコンテナから見える」ことを確認できる。

4.6 引き渡し物の構成#

1
gpu-service-deploy/
2
├── roles/
3
│   ├── gpu_host/          # ドライバ導入・固定・検査, Docker, Container Toolkit
4
│   └── app_deploy/        # compose.yaml・.env 配置と起動
5
├── inventories/
6
│   ├── dev/               # 開発者が管理・検証済み
7
│   └── prod/              # インフラが記入（ホスト名、Vault）
8
├── group_vars/
9
│   └── gpu_servers.yml    # ドライバブランチ・イメージ digest をまとめて管理
10
├── site.yml               # 素の OS からの初期構築
11
├── driver_update.yml      # ローリングでのドライバ更新
12
├── molecule/              # OS 層のテスト
13
└── README.md              # 前提条件・変数一覧・実行コマンド

引き渡しで効くのはバージョンの固定だ。ドライバのブランチ、Container Toolkit のバージョン、イメージの digest を group_vars に並べ、同じ MR でまとめて変えるルールにしておけば、「開発で通ったものと同じもの」が本番で動くことを保証しやすくなる。

テストには限界もある。Molecule のコンテナには GPU がないので、OS 層は Molecule、GPU 層は開発用 GPU サーバーを実機テスト環境として使う。エージェントに任せやすいのは、role の作成と開発用サーバーでの「流す → 直す」の反復で、本番への実行は人間が差分を見てから行う。

5.1 playbook の構造：ansible-playbook-grapher#

playbook を静的に解析して、play・role・task の関係をグラフにするツールだ。インベントリに対しては何も実行しない³²。

1
pip install ansible-playbook-grapher
2

3
# role 内のタスクまで含めて SVG で出力（Graphviz が必要）
4
ansible-playbook-grapher --include-role-tasks --show-handlers site.yml -o docs/site
5

6
# Mermaid で出力（Markdown に埋め込める）
7
ansible-playbook-grapher --include-role-tasks --renderer mermaid-flowchart site.yml -o docs/site

4章のサンプル（site.yml）なら、次のような形のグラフになる。

NOTE

この図は出力のイメージを手で描いたもので、grapher の実際の出力とはノードの形や表記が異なる。

レビューで効く使い方は2つある。

• CI で Mermaid を生成して MR に貼る: エージェントが role を追加したり、タスクの順序を変えたりしたとき、構造の変化が図の差分として見える。「Container Toolkit の導入がドライバの検査より前に来ている」といった順序の誤りに気づきやすい
• handler の通知先を確認する: --show-handlers を付けると、どのタスクがどの handler を呼ぶかが見える。Restart docker が想定外のタスクから呼ばれていないかを確認できる

5.2 インベントリの構造：ansible-inventory —graph#

1
ansible-inventory -i inventories/prod --graph --vars

--graph はグループとホストのツリーを出力し、--vars を付けると各ホスト・グループの変数も表示する（--vars は --graph と組み合わせたときだけ有効）³³。出力はおおよそ次のような形になる（ホスト名は例）。

1
@all:
2
  |--@ungrouped:
3
  |--@gpu_servers:
4
  |  |--gpu01
5
  |  |  |--{gpu_driver_branch = 580}
6
  |  |  |--{gpu_min_driver_major = 580}
7
  |  |--gpu02
8
  |  |  |--{gpu_driver_branch = 580}
9
  |  |  |--{gpu_min_driver_major = 580}

2.3節の「変数の優先順位が22段階あって追いにくい」問題への対策になる。group_vars と host_vars を合成した最終的な値を、ホストごとに確認できる。インフラ担当が inventories/prod を書いた後にこれを流せば、記入漏れや値の食い違いを一覧で確認できる。

5.3 実行計画の一覧：ansible-playbook —list-*#

1
ansible-playbook -i inventories/prod driver_update.yml --list-hosts   # 対象ホスト
2
ansible-playbook -i inventories/prod driver_update.yml --list-tasks   # 実行されるタスク
3
ansible-playbook -i inventories/prod driver_update.yml --list-tags    # 利用可能なタグ

いずれも何も実行しない³⁴。--check --diff が「何が変わるか」を示すのに対し、こちらは「何が、どのホストに対して走るか」を示す。

5.4 実行結果の履歴：ARA Records Ansible#

ARA は Ansible の callback plugin として動き、ansible-playbook の実行結果（play・task・ホストごとの結果）を記録する。既定ではローカルの SQLite に保存し、Web UI・CLI・REST API で参照できる³⁵。

1
pip install "ara[server]"
2
export ANSIBLE_CALLBACK_PLUGINS="$(python3 -m ara.setup.callback_plugins)"
3
ansible-playbook -i inventories/dev site.yml
4
ara-manage runserver   # http://127.0.0.1:8000

callback の設定方法はバージョンで変わりうるので、導入時に公式ドキュメントで確認しておく。「いつ、どのホストで、何が changed になったか」を後から追いたい作業で役に立つ。エージェントが開発環境で繰り返した実行の履歴を、後から人間が確認する用途にも使える。

5.5 レビューフローへの組み込み#

2.5節のフローに、可視化を足すと次のようになる。

構造・値・範囲・変更内容の4つが図とテキストで並ぶので、AIが書いたYAMLを頭の中で実行しなくても判断できる。散らかったスクリプトを読む場合との大きな差はここにある。