Ansible collections作成のドキュメントをまた英語で読まなくて良いように日本語でまとめておく。
元サイトは以下。
https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#developing-collections
英語力と技術力低さはお察しなので内容は保証できず。。。
後で気づいたことやgalaxy.ymlの内容等もどこかで調べる。
Developing collections
Collection structure
ディレクトリ構成
collection/
├── docs/
├── galaxy.yml
├── plugins/
│ ├── modules/
│ │ └── module1.py
│ ├── inventory/
│ └── .../
├── README.md
├── roles/
│ ├── role1/
│ ├── role2/
│ └── .../
├── playbooks/
│ ├── files/
│ ├── vars/
│ ├── templates/
│ └── tasks/
└── tests/- 必ず必要なのはgalaxy.ymlだけ
- 他は公開したいものがあれば適宜追加
- draft collectionを参考にして作るべし
各ファイルの詳細
-
galaxy.yml
- 必ず必要なファイル
- Collection Galaxy metadata structure を参考にして作るべし
-
docs directory
- ansible-docコマンドで使用される内容をここにおく
- コレクションが提供するロールとプラグインの使用方法、ロールの要件などを説明する
-
plugins directory
- pluginに応じてサブディレクトリを用意する
- varとinventoryプラグインはサポートされていない
- module、module_utilsもここに置く
- 注意事項
- Pythonのimport文はFQCNを考慮する必要がある
ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}
-
roles directory
- ロール名には以下の制限がある
- 小文字アルファベットから始まること
- 使えるのは小文字アルファベット、数字、アンダーバー
- ロールディレクトリのなめがロールとして使用されるため上記命名規則に従う必要がある
-
playbooks directory
- TBD
-
tests directory
- TBD
- コレクションをテストするものが入っていることが望ましい
Creating collections
- ansible-galaxyコマンドについてはリンク先を参照
コレクションの作成手順
-
ansible-galaxy collection initコマンドで骨組みを作成する
collection_dir#> ansible-galaxy collection init my_namespace.my_collection -
必要なものを適宜追加
-
ansible-galaxy collection buildコマンドでcollection artifactをビルド
collection_dir#> ansible-galaxy collection build上記コマンドを実行するとtar形式で圧縮される
my_collection/ ├── galaxy.yml ├── ... ├── my_namespace-my_collection-1.0.0.tar.gz └── ...- 注意事項(Ansilbe 2.10以降のみ)
- 圧縮ファイルの最大サイズは２MB
- 以下のファイルはデフォルトで圧縮の対象外となる
- galaxy.yml
- *.pyc
- *.retry
- tests/output
- 以前に構築されたartifact
- .git等のバージョン管理ファイル
- 任意のファイルを圧縮の対象が意図したい場合はgalaxy.ymlのbuild_ignoreに記入する
build_ignore: - playbooks/sensitive - '*.tar.gz'
-
Trying collections locally
- 以下コマンドでコレクションのインストールをローカル実行できる。
ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections - コマンド実行時には自分の環境のCOLLECTIONS_PATHSを指定する（ansible-config -list で確認できる
- インストールできたらUsing collectionsを参考に実行する
- 以下コマンドでコレクションのインストールをローカル実行できる。
-
Publishing collections
- 一度公開すると削除や編集ができないので注意が必要
- APIトークンを取得する
- Galaxy profile preferencesで[API key]をクリックしてトークンを取得する
- 取得したトークンは以下どちらかの方法で指定する
- ansible-galaxyコマンドの--tokenオプション指定
ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --token= - ansible.cfgのgalaxy_serverセクションで指定
[galaxy] server_list = release_galaxy[galaxy_server.release_galaxy] url=https://galaxy.ansible.com/ token=my_token - 以下いずれかの方法で公開する
- ansible-galaxyコマンドで公開する
ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz- デフォルトの公開先は https://galaxy.ansible.com になっている
- Automation Hubやその他の場所に公開したい場合はansible.cfgを編集する
- Galaxy webサイトから公開する
- 自分のアカウントページから[Add Content]へ進み[Upload New Collection]をクリック
- namespaceはgalaxy.ymlに定義されたものが使用される
- アップロードしたアカウントがネームスペースのオーナーではない場合、アップロードは失敗する
- バージョニングはSemantic Versioningに従うこと
- ansible-galaxyコマンドで公開する