specsfy-specialist-deploy

デプロイ

使用するタイミング

• アプリケーションのサーバーへのリリースまたはデプロイを依頼されたときに使用します。
• Ansible 経由で Docker Swarm スタックを受け入れるサーバーを準備するときに使用します。
• 環境内のサーバーの登録、追加、置換、確認を依頼されたときに使用します。
• 対象と明示的な許可がない限り、プッシュ、プロビジョニング、リモートでの変更は実行しません。

フロー

計画を提示し、各段階の進捗を伝え、変更したファイル、検証結果、保留事項を報告して終了します。公開するテキストについては、利用するプロジェクトに適用される共有編集ガイドラインに従ってください。

1. ユーザーのシステムのルートを確認し、$specsfy-specialist-versioning を呼び出して SEMVER を読み込むか準備します。

2. 既存の Dockerfile、Compose、スタック、ansible/ を調査します。PHP、拡張機能、依存関係、アセット、エントリーポイント、内部ユーザー、ポート、ヘルスチェック、Octane のコマンドを現在のアプリケーションと比較します。カスタマイズされた部分は保持し、管理マーカーのないファイルを置き換える前に差分を提示します。

3. すべての宛先が存在しない場合に限り、初回の準備時にジェネレーターを実行します。

   node scripts/scaffold.mjs --project <raiz> --image <registry>/<aplicacao>
   

   デフォルトではスタックに Cloudflare Tunnel が含まれます。別のプロキシを希望する場合は、--proxy external を指定して cloudflared を含めずに生成し、別の手順で希望する代替手段を設定します。

4. $specsfy-specialist-debian-server を呼び出し、1 回の作業につき 1 台ずつマシンをセットアップします。ホスト名、アドレス、SSH ポート、接続ユーザー、manager または worker の役割を ansible/inventory.yml に記録し、登録済みのホストは保持します。新しいマシンが追加された場合は、そのホストのみを追加します。

5. リモートでの変更を行う前に、宣言済みのすべてのホストをテストします。このスキルはユーティリティを実行しますが、Herdr で使う短い形式も示します。

   ./deploy check-hosts
   

6. 制御マシン上の ~/.ssh/*.pub にある公開鍵のみを検索し、ユーザー deploy の authorized_keys に追加します。秘密鍵を読み取ったり、コピーしたり、送信したりしてはいけません。登録済みのリモートアクセスは保持します。

7. アプリケーションが使用するパスワード、トークン、キーを確認し、名前を ansible/vault-fields.txt に記録します。会話で値を尋ねてはいけません。ユーティリティは非表示入力で各値を要求し、暗号化された YAML に書き込みます。

   ./deploy secrets
   

   再実行時には既存のフィールドを保持し、不足しているフィールドのみを尋ねます。

   Cloudflare Tunnel のデフォルト設定では、vault_cloudflare_tunnel_token を含めます。このサービスは、ファイル /run/secrets/cloudflare_tunnel_token からトークンを読み取ります。

8. docker-tag でイメージの参照を生成します。SEMVER の値と異なる Docker タグは拒否します。

9. $specsfy-specialist-debian-server と $specsfy-specialist-docker を呼び出し、ホストと Docker Engine の状態を定義します。

10. $specsfy-specialist-ansible を呼び出し、ユーザー deploy の作成、Docker Engine のインストール、デーモン、ファイアウォール、権限、アプリケーションのディレクトリを設定する冪等なロールを作成または確認します。

11. $specsfy-specialist-docker-swarm を呼び出し、マネージャー、ワーカー、ネットワーク、スタックを定義します。プレイブックは、マネージャーがまだ Swarm に参加していない場合にのみ docker swarm init を実行し、参加には保護されたトークンを使用します。

12. Ansible を syntax check、lint、check mode、および使い捨ての対象への 2 回の実行で検証します。スタックは docker stack config で検証します。

13. 指定された対象への許可がある場合、エージェントがデプロイを実行する際は ./deploy run --non-interactive を使用します。パスワードは設定済みの外部ソースから取得します。そのようなソースがない場合は、ユーザー自身のターミナルで ./deploy configure-vault を実行するよう案内します。会話でパスワードを尋ねたり、読み取ったり、表示したりしてはいけません。手動実行の手段として ./deploy run も維持します。プレイブックを適用し、バージョン付きイメージを公開して、マネージャーから docker stack deploy を実行します。

14. レプリカ、ヘルスチェック、ログ、バージョン、ダイジェストを確認します。以前のバージョンにロールバックするコマンドを保存します。

標準

• パスワードを設定する前、既存のスクリプトを移行する前、またはエージェントから実行する前に、references/vault.md を読みます。明示的に指定された情報源は環境変数や ansible.cfg より優先されます。ネイティブな情報源がない場合は、ローカル登録を代替手段として使います。情報源のいずれかで失敗した場合は、実行を終了します。

• パスワードを入力するために、AI から configure-vault を実行しないでください。このコマンドは、入力が非表示になるターミナルで人が準備するためのものです。

• 既存プロジェクトは差分で更新し、カスタマイズを保持します。スキャフォールドは引き続き上書きを拒否し、スキルの更新によって ./deploy や ansible/ が自動的に移行されることはありません。

• ユーザーのシステムルートにある SEMVER が、イメージ、マニフェスト、Git タグ、リリースの基準になります。

• 開発用に compose.yaml を、本番用に stack.yaml を生成します。本番環境ではすべて、Docker Swarm 経由でスタックを使用します。本番環境のランタイムとして Compose を使わないでください。

• Laravel では、laravel/octane と Open Swoole を必須とします。イメージには openswoole をインストールし、Compose とスタックでは Octane を --server=swoole で実行します。

• 公開用の入口には、Cloudflare Tunnel をデフォルトで提案します。cloudflared をスタックのサービスとして実行し、アプリケーションと同じオーバーレイネットワークに接続します。Laravel サービスには公開ポートを設定しません。トンネルのホスト名は http://app:8000 を指すようにします。

• ほかのプロキシを希望すると本人が依頼した場合に限り、デフォルトを変更します。その場合、cloudflared サービスもトークンのシークレットも生成しません。

• Ansible でサーバーと Swarm の状態を設定します。SSH コマンドを手動で並べた手順を主な手順にしないでください。

• サービスユーザー deploy を作成し、そのユーザーのみを docker グループに追加して、アプリケーションのディレクトリを割り当てます。このグループはホストへの広範な管理アクセスを許可するため、この役割を持たないアカウントを追加しないでください。

• ansible/inventory.yml は、把握しているサーバーの一覧として維持します。サーバーを追加する際は現在のホストを保持し、新しい接続をテストしてから、そのノードと Swarm での役割を設定します。

• Herdr の別のパネルに操作をコピーする必要がある場合は、./deploy check-hosts、./deploy secrets、./deploy sync-keys、または ./deploy run を表示します。これらのユーティリティは、コマンドを覚えていなくてもスキルから実行できます。

• 新たに呼び出された場合は、アプリケーションを再度読み込み、変更された部分だけを反映します。ジェネレーターは最初のブートストラップに使うものであり、更新を装うために既存ファイルを上書きしてはいけません。

• 冪等なモジュールと community.docker を使用します。Swarm の開始や参加に必要なコマンドには、現在の状態に基づく条件を設定します。

• マネージャーは奇数台に保ち、Swarm のポートへのアクセスを許可されたノードに制限します。

• イメージは一度だけ公開し、同じダイジェストを環境間で昇格させます。

• パスワード、トークン、鍵は、安全なプロンプトで作成した Ansible Vault に格納します。Ansible は復号した値を no_log: true で Docker Secrets に変換します。スタックには名前と外部マウントのみを記載します。

アンチパターン

• SEMVER を再現しない latest やその他のタグを使用する。
• Playbook の実行ごとに docker swarm init を実行する。
• join トークンをログ、平文の変数、またはコミット済みファイルに露出させる。
• パスワード、トークン、鍵を stack.yaml、平文の変数、またはイメージに保存する。
• Cloudflare Tunnel のトークンを引数、平文の変数、またはバージョン管理対象のファイルで渡す。
• 必要性が確認されていないのに、ユーザー deploy に無制限の sudo 権限を付与する。
• サーバー上でビルドする、または環境ごとにイメージを再ビルドする。
• コマンドが終了コード 0 を返しただけで、デプロイ完了と判断する。

検証

• 使い捨てのターゲットで、手動プロンプト、外部ファイル、ボールトスクリプト、ネイティブ設定を検証します。有効なパスワードがない場合、ホストへの接続前に実行が停止する必要があります。権限 700 と 600、上書き確認、設定ツールの出力に秘密の値が含まれないことを確認します。

• バージョニングスキルで current、docker-tag、verify-docker-tag を実行します。

• deploy が存在し、docker グループに属し、デーモンにアクセスでき、アプリケーションのディレクトリの所有者であることを確認します。

• Docker Engine が稼働中で、manager に到達可能であり、swarm が active 状態であることを確認します。

• プレイブックを2回実行します。2回目は変更なしで終了する必要があります。

• 各サービスのイメージを SEMVER および公開済みダイジェストと比較します。

• 収束を確認し、互換性のある環境でロールバックを試行します。

関連するスキル

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

• $specsfy-specialist-versioning は、ユーザーのシステムバージョンを管理します。

• $specsfy-specialist-debian-server は、ホストのベース状態を定義します。

• $specsfy-specialist-docker は、イメージを準備して公開します。

• $specsfy-specialist-ansible は、サーバーとクラスターを自動化します。

• $specsfy-specialist-docker-swarm は、サービス、ロールアウト、ロールバックを管理します。

• $specsfy-specialist-delivery-engineering は、これらのコンポーネントがデリバリーに含まれる場合、パイプラインと環境間の昇格を管理します。

プロビジョニングおよびデプロイのプレイブックを作成または変更する前に、references/standards.md をお読みください。