specsfy-specialist-ansible

Ansible

使用する場面

• プロジェクトに playbook、role、inventory、ansible.cfg、 または collection の requirements.yml／galaxy.yml がある場合に使用します。
• 既存の自動化を共有環境に対して実行する前に、本当に 冪等性があるか確認する場合にも使用します。
• すでにコンテナ化されたサービスをクラスターでオーケストレーションする場合は 使用しません。その場合は $specsfy-specialist-docker-swarm を使用します。 ここでの Ansible の役割はホストのプロビジョニングであり、Swarm サービスの オーケストレーションではありません。
• playbook の実行がデプロイパイプラインの一工程である場合は、 $specsfy-specialist-delivery-engineering と組み合わせます。

フロー

計画を提示し、進捗を報告して、変更したファイルと実行した検証を最後に示します。 公開向けの文章では、利用するプロジェクトに適用される共有編集ガイドラインに従います。

1. リリースまたは完全なデプロイでは、 $specsfy-specialist-deploy のもとで作業し、オーケストレーターが すでに準備した SEMVER、イメージ、マニフェストを使用します。
2. 影響のある操作を実行する前に、ホスト、グループ、対象環境、接続方式、 対象となるホストの正確な範囲を確認します。
3. 最初のリモート task の前に ./deploy check-hosts を使用して すべてのホストを表形式で提示し、ping モジュールを確認します。 ./deploy sync-keys を使用して、既存の authorized_keys のエントリーを 削除せず、deploy ユーザーに公開鍵のみを追加します。
4. 適用される変数の優先順位（references/standards.md の表を参照）と、 固定されている collection および ansible-core のバージョンを確認します。
5. 冪等性のあるモジュールと、1 つの責務を持つ一貫した role を使用して、 望ましい状態をモデル化します。
6. secrets は Ansible Vault または外部プロバイダー（管理された保管庫からの lookup） で保護します。リポジトリに平文で保存してはいけません。
7. エージェントが実行する場合は、デプロイオーケストレーターのもとで ./deploy run --non-interactive を使用します。すでに提供されている ファイル、スクリプト、Vault IDs、ネイティブ設定を尊重します。 外部ソースがない場合は、人間が操作するターミナルで ./deploy configure-vault を実行するよう案内します。会話でパスワードを 尋ねたり読み取ったりしてはいけません。./deploy run コマンドは、 入力が非表示になる手動実行として維持します。
8. 出力に secrets を漏らさず、構文、ansible-lint、check mode、diff を 検証します。
9. 破棄可能な環境で role をテストし、同じ実行を繰り返して、2 回目の実行で changed が報告されないことを確認します。
10. 変更の影響範囲に適したシリアル実行（serial）、制限（--limit）、 停止ルール（max_fail_percentage／any_errors_fatal）を設定して本番環境に適用します。

ベストプラクティス

• 書き込みを伴う play の前に、コントローラーのバージョン、ターゲットシステム、Docker へのアクセス、manager の役割、registry へのログイン、collections、変更されないイメージ、Docker Secrets を確認する、独立した preflight を作成します。
• stack が Cloudflare Tunnel を使用する場合は、vault_cloudflare_tunnel_token から cloudflare_tunnel_token を作成し、no_log: true を設定します。stack に渡すのは Docker Secret の名前だけにします。
• バージョン管理されている manifest をホスト上の安定したディレクトリにコピーし、それぞれを docker stack config で検証してから、依存関係の順に stack を公開します。
• 公開のたびにレプリカを確認し、収束するまで待つか、上限回数に達したらエラーで終了します。deploy モジュールの戻り値だけで完了と判断しないでください。
• check mode は正しく扱います。検査タスクでは check_mode: false を使用できますが、状態を変更するタスクはスキップするか、シミュレーションに対応させます。stack をデプロイしなくても preflight が有用である必要があります。
• FQCN（copy ではなく ansible.builtin.copy）と宣言型モジュールを使用し、同等の冪等性を備えたモジュールがある場合は shell／command を避けます。
• タスクと handler には実行内容がわかる名前を付けます（name: にはモジュール名ではなく効果を記述します）。タスクによって状態が実際に変更された場合にのみ handler を通知します。
• defaults/main.yml（role の利用者が設定可能）、vars/main.yml（内部用で、上書き不可）、secrets（Vault または外部 lookup）を別々のファイルに分けます。
• requirements.yml で collections のバージョンを固定し、更新前にインストール済みの ansible-core との互換性マトリックスを検証します。
• changed_when／failed_when はコマンドの実際の意味を表す場合にのみ使用します。実際の失敗を隠したり、常に変更を報告する shell／command に冪等性があるように見せたりしてはいけません。
• 権限を必要最小限に制限し（become は必要なタスクだけに設定）、ログ上では無害に見える値であっても、secret を扱うすべてのタスクで no_log: true を使用します。
• ホスト間で副作用が発生するタスク（例：一度に 1 台のホストしか再起動できないサービス）では、偶然のホスト順序やデフォルトの並列実行に依存しないようにします。そのような場合は serial と throttle を明示的に使用します。

アンチパターン

• creates、removes、または明示的な changed_when のない shell／command：最終状態が同じでも、タスクは毎回 changed を報告します。これにより、実行中に「実際に何が変わったか」を読み取れなくなり、冪等性のない自動化を見えにくくします。
• 無条件に通知される handler（changed の場合にのみ notify を実行するタスクの外で通知する場合）：何も変更されていないときも含め、実行のたびにサービスが再起動され、不要な停止が発生します。
• 本番環境／ステージング環境の環境変数を、実際の優先順位を確認せず、汎用的な group_vars だけで解決すること：コマンドラインの -e や、より具体的な host_vars によって、想定した値が気付かないうちに上書きされることがあります。
• Vault を誤って復号してコミットしたり、no_log を設定せずに secret を debug:／ログへ埋め込んだりすること：ソースファイルが正しく暗号化されていても、Git の履歴や実行出力から secret が漏えいします。

検証

• 実際に適用する前に、ansible-playbook --syntax-check、ansible-lint、および --check --diff（チェックモード）で実行し、diff に秘密情報が露出しないことを確認します。
• 同じターゲットに対して連続で2回実行します。2回目では、どのタスクも changed と報告されないことが必要です。これが冪等性の運用上の証明であり、コードを目視で確認するだけでは不十分です。
• ハンドラーのテスト（サービスが必要なときに実際に再起動すること）、テンプレートのテスト（環境ごとに正しくレンダリングされること）、および部分的な失敗のテスト（ホストがバッチの途中で失敗した場合に any_errors_fatal と max_fail_percentage が想定どおり動作すること）を実施します。
• リモート環境を変更する前に、使用するインベントリと --limit を明示的に確認します。「すべてのホストで実行する」ことを、暗黙のデフォルトとして受け入れてはいけません。
• 上記の連続した2回の実行とチェックモードを行わずに、ロールを「冪等」または「安全」と断言してはいけません。プレイブックを読んでも、使い捨て環境で実際に実行することの代わりにはなりません。

関連するスキル

• $specsfy-specialist-server-report は、Ansible による読み取り専用の収集を通じて、ログ、サービス、ディスク使用量をホストごとのレポートにまとめます。

• $specsfy-specialist-deploy は、サーバーの自動化全体を調整します。このスキルでは、ロールと Ansible プレイブックを扱います。

• $specsfy-specialist-versioning は、自動化によって配布されるイメージとマニフェストに SEMVER を合わせます。

• $specsfy-specialist-docker-swarm は、Ansible でプロビジョニングしたホストが Swarm クラスターに参加する場合に使用します。Ansible がノードを準備し、Swarm がその中のサービスをオーケストレーションします。

• $specsfy-specialist-delivery-engineering は、プレイブックの実行が環境間の昇格を伴うパイプラインの段階である場合に使用します。

• $specsfy-specialist-application-security は、秘密情報の管理、認証情報のローテーション、プロビジョニングしたホストのハードニングをレビューする際に使用します。

• $specsfy-specialist-debian-server は、アプリケーションの自動化を始める前に、APT、SSH、sysctl、systemd、ファイアウォール、Docker Engine を準備する際に使用します。

ロールの構成、変数の優先順位、冪等性、運用上のセキュリティ、テストコマンドについては、Ansible ドキュメントの公式情報源を掲載した references/standards.md をお読みください。