specsfy-specialist-docker-swarm

Docker Swarm

使用する場面

• プロジェクトが docker swarm init/join、docker stack deploy、または deploy: を含むスタックファイルで複数ノードをオーケストレーションする場合に使用します。
• manager／worker のトポロジー、ロールアウト、ロールバック、クォーラムの復旧を決定する場合にも使用します。
• 1 台のマシンでの docker compose up によるローカル開発や、イメージのビルドには使用しません。その場合は $specsfy-specialist-docker を使用してください。Compose の多くのキー（profiles、depends_on.condition、ランタイムでの build）は docker stack deploy では効果がありません。
• ロールアウトがリリースパイプラインの一部である場合は $specsfy-specialist-delivery-engineering と併用し、ロールアウトを許可または差し戻すシグナルを決める場合は $specsfy-specialist-observability と併用します。

ワークフロー

1. リリースまたは完全なデプロイでは、$specsfy-specialist-deploy のもとで作業します。$specsfy-specialist-versioning が準備した SEMVER を確認し、docker stack deploy の前に verify-docker-tag を実行して、タグが一致しない場合は中止します。
2. トポロジーを変更する前に、manager、worker、ゾーン、ラベル、クォーラム、外部依存関係（registry、storage、DNS）を把握します。
3. 公開済みのイメージがテスト済みのものと同一であること、およびスタックファイルが Compose のスキーマ全体ではなく、docker stack deploy でサポートされるキーのみを使用していることを検証します。
4. services、ネットワーク、ポート、ボリューム、configs、secrets を定義し、共有リソースごとに明確な所有者を設定します。
5. replicas、placement constraints／preferences、resources.limits／reservations、healthcheck、restart_policy を設定します。
6. update_config と rollback_config（並列数、delay、start-first／stop-first の順序、failure_action）を設計し、ロールアウト中に新旧バージョンが共存しても API／データの契約が壊れないようにします。
7. 代表的な swarm（単一ノードではなく、同等のトポロジーを持つ staging）に適用し、docker service ps と docker service logs で収束状況を確認します。
8. デプロイ、ロールバック、secret のローテーション、Raft 状態のバックアップ、manager 喪失時の復旧計画の手順を文書化します。

パターン

• $specsfy-specialist-deploy が調整するデプロイでは、Cloudflare Tunnel をデフォルトの公開入口として使用します。cloudflared とアプリケーションを同じオーバーレイネットワーク上に配置し、Laravel のポートをホスト上に公開しないでください。別のプロキシへの切り替えを明示的に求められた場合は、それを受け入れます。

• トンネルのトークンはファイルとしてマウントする Docker Secret で渡し、cloudflared は --token-file で起動します。値をスタックに保存してはいけません。

• 依存関係、アプリケーション、イングレスはそれぞれ別のスタックに分けます。依存関係の順にデプロイし、各サービスが宣言された状態に収束するのを待ってから、公開経路を開きます。

• マイグレーションは選択した 1 つのレプリカに集約します。ロールアウト中の競合を防ぐため、その他のサービスではマイグレーションを無効にして起動します。

• HTTP、キュー、スケジューラー、WebSocket には同じ不変のイメージを使用し、それぞれに専用のコマンドとヘルスチェックを設定します。別のキュー監視プロセスがアクティブな場合、予備のワーカーはレプリカ数を 0 に保ちます。

• スタックを作成する前に、外部アクセス可能で暗号化されたオーバーレイネットワークを作成します。データサービスは内部ネットワークのみに配置します。この構成がプロジェクトの要件を満たす場合、アウトバウンド専用のトンネルを使えば、ホスト上に公開ポートを設けずに済みます。

• マネージャーは奇数（1、3、5）にし、本番環境でクォーラムが単一のマネージャーに依存する状態を決して作らないでください。

• すべてのノードからアクセスできる、不変のダイジェスト指定イメージ（image@sha256:...）を公開します。ローカルビルドの違いによってノード間に差が生じてはいけません。

• 名前にバージョンを含めたシークレット／設定（app_secret_v2）を使用し、スタックファイルの環境変数にシークレットを埋め込まないでください。

• イングレスネットワーク、内部サービスネットワーク、データネットワークを分けます。内部サービスのポートを ports: で公開してはいけません。

• resources.limits と reservations を明示的に設定し、最も余裕のあるノードの暗黙の容量に依存しないでください。

• placement.constraints は、管理対象のラベル（node.labels.*）のみを使って設定し、ホスト名をハードコードしてはいけません。

• Compose のオプション（profiles、build、develop、condition を使った depends_on）が stack deploy でサポートされると決めつけないでください。依存する前に、サポート対象のフィールド一覧を確認します。

アンチパターン

• レプリカ数の少ないサービスで update_config.order: start-first を指定せずにローリングアップデートすること。新しいレプリカが正常になる前に古いレプリカが停止し、サービスの処理能力が一時的に失われます。
• 複数レプリカや再スケジュールを伴うサービスでローカルボリューム（bind または分散ドライバーのない名前付きボリューム）を使うこと。スケジューラーがコンテナを別のノードに再配置すると、データが「消失」します。
• 参照されるファイルの内容を置き換えて、シークレットをその場で変更すること。Swarm はシークレットを名前ごとに不変として扱います。正しくは、新しいバージョン（app_secret_v2）を作成してサービスに追加してから、古いものを削除します。
• 開発用の docker-compose.yml と本番用のスタックファイルを混同すること。ヘルスチェック、deploy:、シークレット、オーバーレイネットワークは、両者で欠けていたり、異なっていたりすることがよくあります。

検証

• デプロイ前に docker stack config --compose-file <arquivo>（またはプロバイダーの同等の検証）を実行し、補間エラーとスキーマエラーを検出します。
• ロールアウトの終了時だけでなく、実行中も docker service ps <serviço>、docker service logs、希望するレプリカ数と現在のレプリカ数、ノードのイベントを確認します。
• ワーカーの障害をシミュレートします。また、権限がありバックアップが検証済みの環境で、マネージャー 1 台の喪失をシミュレートし、残りのマネージャーでクォーラムが維持されることを確認します。
• アプリケーションのロールバック（docker service update --rollback または rollback_config）を実証し、2 つのバージョンが共存する期間におけるデータマイグレーションの互換性を確認します。
• この 4 項目を確認せずに、スタックを「本番環境で使用可能」と宣言してはいけません。「自分のノードでは動いた」ことは、クラスターの収束を示す証拠にはなりません。

関連するスキル

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

• $specsfy-specialist-deploy は、サーバー、イメージ、Ansible、スタックの公開を調整します。このスキルが担当するのは Swarm のみです。

• $specsfy-specialist-versioning は SEMVER を準備し、イメージとスタックマニフェストで使用されるバージョンを確認します。

• $specsfy-specialist-ansible はノードを準備、維持します。このスキルが担当するのは Swarm のクォーラム、スケジューラー、サービス、ネットワークです。

• $specsfy-specialist-laravel はアプリケーションの契約を定義し、$specsfy-specialist-redis はサービスで使用する永続化／キャッシュを担当します。

• $specsfy-specialist-docker はイメージのビルド、Dockerfile、Compose を使ったローカル開発を担当します。境界は、アプリケーションが複数のノードでクラスタ状態を伴って動作し始めるところから Swarm になります。

• $specsfy-specialist-delivery-engineering は、サービスのロールアウトが環境間のプロモーションを伴うリリースパイプラインの一部である場合に使用します。

• $specsfy-specialist-observability は、ロールアウトの続行、一時停止、ロールバックを判断するシグナル（ヘルス、エラー率、レイテンシー）を計測するために使用します。

• $specsfy-specialist-debian-server は、クラスタポート、カーネル、ファイルシステム、ノードの Docker サービスを担当します。

Raft トポロジー、シークレット／設定のライフサイクル、オーバーレイネットワーク、ロールアウト戦略、ディザスターリカバリーについては、Docker の公式ドキュメントを出典とする references/standards.md を参照してください。