mcpField
D
darkmatter-gitops-conventions

darkmatter-gitops-conventions

github.com/darkmatterクラウド・DevOps0297 回インストール5 日前に更新
リポジトリ

darkmatter-gitops-conventions について

`darkmatter/gitops`リポジトリでDarkmatterのk3sクラスターを管理するためのGitOps規約を定めるスキルです。コミット済みの再現可能な変更、ArgoCDによる同期、リポジトリ内の暗号化されたシークレットを重視します。

主な機能

  1. 01Gitをクラスターの唯一の正とする
  2. 02ArgoCDマニフェストで変更を管理
  3. 03コミット前にマニフェストを検証
  4. 04コミットまたはダイジェストでコンテナイメージを固定
  5. 05SOPSでインフラシークレットを暗号化保存
  6. 06beadsでフォローアップを管理

活用シーン

  1. 01コミット済みマニフェストでk3sクラスターを更新
  2. 02git revertによるクラスター変更のロールバック
  3. 03コミット前のマニフェスト構文とスキーマの確認
  4. 04暗号化されたインフラシークレットの安全な編集

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/darkmatter/skills --skill darkmatter-gitops-conventions

インストール後、Claude Code で/darkmatter-gitops-conventionsを入力して読み込まれたか確認します。

詳細

Darkmatter GitOps の規約

darkmatter/gitops は、k3s クラスターの唯一の信頼できる情報源です。ArgoCD app-of-apps、Helm values、KSOPS シークレット、ネットワークポリシー、cloudflared のルートを管理します。 ここにコミットされて初めて変更が有効になります。それ以外はすべてドリフトです。

最優先のルール

クラスターを命令的に変更してはいけません。kubectl apply/edit/patch も helm upgrade も、命令的な再起動も禁止です。稼働中のオブジェクトが リポジトリと異なる場合は、リポジトリが正であり、オブジェクトに問題があります。

  • デプロイメントを再読み込みする：マニフェスト内の pod-template config-rev アノテーションを更新してコミットします。kubectl rollout restart は使いません。
  • ArgoCD に今すぐ再調整させる：マニフェストに arc.darkmatter.io/reconcile-at: "<current UTC timestamp>" アノテーションを設定します。
  • ロールバックする：問題のコミットを git revert してプッシュします。ArgoCD が収束します。 稼働中の状態を「前向きに修正」してはいけません。

すべてのコミット前に検証する

次の3つをすべて実行してください。CI でも実行されます。遅いコミットより、main が赤くなるほうが問題です。

kubeconform -strict -ignore-missing-schemas -summary <changed manifests>
yq eval '.' <changed file> > /dev/null        # syntax parse
git diff --check                              # whitespace damage

Helm values がブロックスカラー内にある ArgoCD の apps/*.yaml については、埋め込まれた YAML も検証してください。

yq eval '.spec.sources[0].helm.values | from_yaml' apps/<app>.yaml > /dev/null

アサーションスクリプトで失敗を隠してはいけません。|| true は使わず、パイプラインの終了コードが重要な場合は set +e と明示的な PIPESTATUS[0] の取得を使ってください。

イメージ

完全なコミットタグ（sha-<40-hex>）またはダイジェストで固定してください。latest もブランチタグも使ってはいけません。イメージの更新は、出荷するコミットをメッセージに記載する1行の差分にします。ArgoCD は同期時（約3分後）に変更を取り込みます。サンドボックス／Pod 仕様のハッシュが変わると、依存するウォームプールは自動的に入れ替わります。

シークレット（KSOPS/SOPS）

  • シークレットは JSON（*.sops.json）として暗号化した状態でリポジトリに保存し、KSOPS でレンダリングします。 ADR-0011 を参照してください。新しい *.sops.yaml や .env.sops を追加してはいけません。既存の YAML SOPS ファイルを編集する場合は変換してください。 Kubernetes Secret の JSON は API で有効です。
  • 編集する場合：0600 の一時ファイルに復号し、編集してから再暗号化します。その後、構造を検証し（復号した形式に対して jq empty を実行）、キー名のみを比較して差分を確認します。値は決して出力してはいけません。一時ファイルは削除してください。シークレットではない通常のマニフェストは YAML のままにし、引き続き yq を使ってください。
  • それ以外の場所では、名前でシークレットを参照してください。マニフェストやログにシークレット値を直接記載した場合は、インシデントとなります。
  • エージェント／ランタイムのシークレットには、Git ではなく強化されたフロー（Centaur vault + console PUTs）を使用します。このリポジトリに含めるのはインフラストラクチャのシークレットのみです。

ArgoCD の想定事項

  • 同期周期は約3分です。再プッシュするのではなく、ArgoCD でアプリを確認してください。
  • 古い同期の再試行：Application から /operation フィールドを削除し、ハードリフレッシュしてください。
  • プルーニング後も保持する必要がある重要なリソースには、IgnoreExtraneous / Prune=false アノテーションが付与されています。近くを編集する際は、既存のアノテーションを尊重してください。

タスク

フォローアップは TODO コメントではなく、beads（bd create）で管理してください。基準となるのは再現可能性です。クラスターはこのリポジトリだけから再構築できなければなりません。

コメント

Markdown 対応