[Ansible] コレクション内の Playbook のファイル名に - （ハイフン）は使えない

この記事は Ansible Advent Calendar 2024 の 9日目の記事です。

はじめに

コレクションというと、モジュールやプラグイン、ロールを含む単位のイメージが強いかもしれませんが、Playbook も含めることができます。

たとえば、local.sakana コレクションに install.yml という Playbook がある場合、ansible-playbook コマンドなどからは、local.sakana.install という指定で Playbook を呼べます（拡張子はなくてもOK）。

最近、Plyabook のファイル名に - （ハイフン）は使えないという制約があることを知りました。

The dash - character is not valid for playbook names in collections

https://docs.ansible.com/ansible/latest/collections_guide/collections_using_playbooks.html#using-a-playbook-from-a-collection

少し気になったので試してみます。

検証環境

• ansible-core 2.16.6

おためし

コレクション内にハイフンあり、なしの Playbook をそれぞれ仕込んでおきます。playbooks ディレクトリに格納するのは、そういう仕様のためです。

 ~/.ansible/collections/ansible_collections/
└── local
    └── sakana
        └── playbooks
            ├── test-playbook.yml
            └── test_playbook.yml

Playbook は、ただ debug するだけの簡単なものです。

- なし（代わりに _）の Playbookの場合、正常に実行できます。

% ansible-playbook -i localhost, local.sakana.test_playbook

PLAY [localhost] **************************************************************************************************

TASK [ansible.builtin.debug] **************************************************************************************
ok: [localhost] => {
    "msg": "Hello world!"
}

PLAY RECAP ********************************************************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0 

続いて - ありの場合、Playbook が見つからないエラーになりました。.yml をつけても同じでした。

% ansible-playbook -i localhost, local.sakana.test-playbook
ERROR! the playbook: local.sakana.test-playbook could not be found

なお、コレクション内の Playbook としての指定ではなく、普通のファイルパスで指定する分には - ありでも実行できます。この場合は、拡張子まで必須です。

% ansible-playbook -i localhost, ~/.ansible/collections/ansible_collections/local/sakana/playbooks/test-playbook.yml 

PLAY [localhost] *************************************************************************************************************************************************************

TASK [ansible.builtin.debug] *************************************************************************************************************************************************
ok: [localhost] => {
    "msg": "Hello world!"
}

PLAY RECAP *******************************************************************************************************************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

おわりに

Ansible は、グループ名に - を使うと警告が表示されたり、ロール名は -を使わない規則にしているコレクションがあったり、たまに - を使うと都合が悪い時があります。

そんなこともあって、どちらかというと私は _ を使うことが多いです。