ansible-lintとMoleculeによるコード検証入門｜静的解析とroleテストで変更事故を防ぐ

この記事のポイント

・ansible-lintはPlaybookとroleのコード品質違反を静的解析で即座に検出するツール
・Moleculeはroleをコンテナで実行して冪等性テストを自動化するフレームワーク
・molecule testで全フェーズ（create/converge/idempotence/verify/destroy）を一括実行できる
・GitHub Actionsに組み込めばPushごとにlintとroleテストが自動実行される

# 仮想環境を作成してansible-lintをインストール（推奨）
python3 -m venv ~/.venv/ansible
source ~/.venv/ansible/bin/activate

# ansible-coreとansible-lintをインストール
pip install ansible-core ansible-lint

# バージョン確認
ansible-lint --version

ansible-lint 25.1.0 using ansible-core:2.17.8 ansible:10.7.0 python:3.11.9
  config-file: None
  rulesdir: /home/user/.venv/ansible/lib/python3.11/site-packages/ansiblelint/rules

# Playbookを直接対象にする
ansible-lint site.yml

# roleディレクトリ全体をチェックする
ansible-lint roles/webserver/

# カレントディレクトリ配下を全部スキャンする
ansible-lint

WARNING  Listing 3 violation(s) that are fatal
yaml[truthy]: Use 'true' instead of 'yes'. (Line: 12, Column: 9)
yaml[truthy]: Use 'false' instead of 'no'. (Line: 24, Column: 9)
fqcn[action-core]: Use FQCN for builtin actions: yum -> ansible.builtin.yum
                   Action: yum [roles/webserver/tasks/main.yml:8]
Finished with 3 failure(s), 0 warning(s) on 2 files.

# yaml[truthy] の修正例
# 修正前
- name: Ensure httpd is enabled
  ansible.builtin.service:
    name: httpd
    enabled: yes   # ← NG

# 修正後
- name: Ensure httpd is enabled
  ansible.builtin.service:
    name: httpd
    enabled: true  # ← OK

# fqcn[action-core] の修正例
# 修正前
- name: Install httpd
  yum:              # ← NG（短縮形）
    name: httpd
    state: present

# 修正後
- name: Install httpd
  ansible.builtin.dnf:  # ← OK（RHEL 10はdnf推奨）
    name: httpd
    state: present

# .ansible-lint の設定例
---
# チェック対象のPlaybook/roleを明示（省略時はカレントディレクトリ全体）
# lint_paths:
#   - site.yml
#   - roles/

# 特定のルールIDをスキップする（チームで合意した例外を記載）
skip_list:
  - yaml[line-length]   # 長い行を許容する場合

# 警告扱いにするルール（NG→警告に緩和）
warn_list:
  - experimental

# Moleculeのテスト用シナリオを除外（lint対象外にする）
exclude_paths:
  - molecule/
  - .git/
  - .github/

# 実行環境プロファイル（min/basic/moderate/safety/shared/production）
profile: production

# molecule本体とdockerドライバーをインストール
pip install molecule molecule-plugins[docker]

# バージョン確認
molecule --version

# dockerドライバーでwebserverというroleを初期化
molecule init role --driver-name docker webserver

# 生成されたディレクトリ構造を確認
find webserver -type f | sort

webserver/
  defaults/
    main.yml
  handlers/
    main.yml
  meta/
    main.yml
  molecule/
    default/
      converge.yml      ← roleを適用するシナリオPlaybook
      molecule.yml      ← テスト環境の定義ファイル
      verify.yml        ← 検証タスクの定義ファイル
  tasks/
    main.yml
  vars/
    main.yml

# 既存roleのディレクトリに移動してMoleculeシナリオを追加
cd roles/webserver
molecule init scenario --driver-name docker default

# molecule/default/molecule.yml
---
dependency:
  name: galaxy

driver:
  name: docker

platforms:
  - name: instance
    # RHEL 10互換のRocky Linux 9イメージ（systemdが使えるAnsiblize済みイメージ）
    image: geerlingguy/docker-rockylinux9-ansible
    pre_build_image: true
    # systemdを使うサービス管理が必要な場合
    command: /usr/sbin/init
    privileged: false
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup:ro
    tmpfs:
      - /run
      - /tmp

provisioner:
  name: ansible
  config_options:
    defaults:
      interpreter_python: auto_silent
  env:
    ANSIBLE_FORCE_COLOR: "1"

verifier:
  name: ansible

lint: |
  set -e
  ansible-lint

# molecule/default/verify.yml
---
- name: Verify
  hosts: all
  gather_facts: false

  tasks:
    - name: httpd サービスが起動していることを確認する
      ansible.builtin.service_facts:

    - name: httpdがactiveであることをassertする
      ansible.builtin.assert:
        that:
          - "'httpd.service' in ansible_facts.services"
          - "ansible_facts.services['httpd.service'].state == 'running'"
        fail_msg: "httpd は起動していません"
        success_msg: "httpd が正常に起動しています"

    - name: ポート80が開いていることを確認する
      ansible.builtin.wait_for:
        port: 80
        timeout: 10

# テストシナリオ全体を実行する
molecule test

# または個別フェーズだけ実行する（開発中に便利）
molecule create     # コンテナを起動する
molecule converge   # roleを適用する
molecule idempotence  # 2回目の適用で変更なしを確認する
molecule verify     # verify.ymlの検証タスクを実行する
molecule destroy    # コンテナを削除する

INFO     Running default > create

PLAY [Create] ******************************************************************

TASK [Create molecule instance(s)] ********************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost     : ok=2    changed=1    unreachable=0    failed=0

INFO     Running default > converge

PLAY [Converge] ****************************************************************

TASK [Gathering Facts] *********************************************************
ok: [instance]

TASK [webserver : Install httpd] ***********************************************
changed: [instance]

TASK [webserver : Start and enable httpd] **************************************
changed: [instance]

PLAY RECAP *********************************************************************
instance      : ok=3    changed=2    unreachable=0    failed=0

INFO     Running default > idempotence

TASK [webserver : Install httpd] ***********************************************
ok: [instance]

TASK [webserver : Start and enable httpd] **************************************
ok: [instance]

PLAY RECAP *********************************************************************
instance      : ok=3    changed=0    unreachable=0    failed=0

INFO     Idempotence completed successfully.
INFO     Running default > verify

TASK [httpd サービスが起動していることを確認する] *****
ok: [instance]

TASK [httpdがactiveであることをassertする] *****
ok: [instance]

INFO     Verifier completed successfully.
INFO     Running default > destroy

PLAY RECAP *********************************************************************
instance      : ok=2    changed=1    unreachable=0    failed=0

# .github/workflows/ansible-ci.yml
---
name: Ansible CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  lint:
    name: ansible-lint
    runs-on: ubuntu-latest
    steps:
      - name: コードをチェックアウトする
        uses: actions/checkout@v4

      - name: Python環境をセットアップする
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: ansible-lintをインストールする
        run: pip install ansible-core ansible-lint

      - name: ansible-lintを実行する
        run: ansible-lint

  molecule:
    name: Molecule Test
    runs-on: ubuntu-latest
    needs: lint   # lintが通過してからtestを実行する
    strategy:
      matrix:
        role:
          - webserver
          - dbserver
    steps:
      - name: コードをチェックアウトする
        uses: actions/checkout@v4

      - name: Python環境をセットアップする
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: MoleculeとDockerドライバーをインストールする
        run: pip install ansible-core molecule molecule-plugins[docker]

      - name: Moleculeテストを実行する
        working-directory: roles/${{ matrix.role }}
        run: molecule test
        env:
          PY_COLORS: "1"
          ANSIBLE_FORCE_COLOR: "1"

# enabled: yes を enabled: true に一括置換（バックアップ付き）
find . -name "*.yml" -not -path "./molecule/*"   -exec sed -i.bak 's/: yes$/: true/g' {} \;

# バックアップファイルを削除する
find . -name "*.yml.bak" -delete

# Dockerデーモンの状態を確認する
systemctl status docker

# 起動していなければ起動する
sudo systemctl start docker
sudo systemctl enable docker

# 現在のユーザーをdockerグループに追加する（再ログイン必要）
sudo usermod -aG docker $USER

# グループ変更を即時反映する（ログアウト不要）
newgrp docker

# 動作確認
docker run --rm hello-world

# NG: 毎回変更ありになる
- name: アーカイブを展開する
  ansible.builtin.command: tar xzf /tmp/app.tar.gz -C /opt/app

# OK: 展開済みならスキップする
- name: アーカイブを展開する
  ansible.builtin.command: tar xzf /tmp/app.tar.gz -C /opt/app
  args:
    creates: /opt/app/bin/app  # このファイルが存在すればスキップ