CI パイプライン

このページは、tazuna.yaml を持つリポジトリで CI / CD パイプラインに Tazuna を組み込む ときの典型構成をまとめます。Tazuna は手元で apply するためにも、CI から apply するためにも使えます。ここでは後者の組み立て方を中心に扱います。

典型構成

役割を分けると次の 3 ステージになります。

ステージ	目的	走らせるコマンド	クラスタアクセス
検証	`tazuna.yaml` が壊れていないことの保証	`tazuna check`、`tazuna build`	なし
反映	`main` の内容をクラスタに反映する	`tazuna apply`（または `tazuna state sync`）	あり
取り外し	Tazuna 管理リソースを削除する	`tazuna destroy`	あり

「検証」は全 PR で走らせて構いません。「反映」は通常 main への push をトリガにします。「取り外し」は CI に常設しない ことを推奨します（tazuna destroy の運用参照）。

検証ステージ

tazuna.yaml を CI に乗せる場合、最低限の通過条件として tazuna check を入れます。クラスタに触れずに走るので、PR でのコストはほぼゼロです。

# GitHub Actions の例（要点だけ）
- name: tazuna check
  run: tazuna check -f tazuna.yaml

- name: tazuna build (preview)
  run: tazuna build -f tazuna.yaml > rendered.yaml

PR で build 結果をアーティファクトに残しておくと、レビュー時に「最終的に何が apply されるか」をレンダリング結果ベースで確認できます。type: oras を使っているなら --offline を付けて先取り cache を使う構成も検討できます（tazuna build）。

反映ステージ

main への push をトリガに tazuna apply を走らせる構成が基本です。

on:
  push:
    branches: ["main"]

jobs:
  apply:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # OIDC でクラスタに繋ぐ場合
    steps:
      - uses: actions/checkout@v6
      - name: install tazuna
        run: |
          curl -L https://github.com/pepabo/tazuna/releases/download/v0.1.0/tazuna_Linux_x86_64.tar.gz \
            | tar xz -C /usr/local/bin tazuna
      - name: configure kubeconfig
        run: |
          # クラスタ側の都合に応じて、aws-iam-authenticator / gke-gcloud-auth-plugin
          # / kubeconfig secret 等で current-context を設定する
          aws eks update-kubeconfig --name prod-tokyo --region ap-northeast-1
      - name: tazuna apply
        run: tazuna apply -f tazuna.yaml

ポイント:

tazuna apply の current-context は kubeconfig の current-context そのものです。 CI で current-context を切り替えるステップを必ず明示します。
tazuna.yaml に spec.context_matches を入れておけば、誤って違うクラスタを向いた kubeconfig で apply しようとしても即終了します。CI でも有効な保険になります。
Tazuna は失敗時に非ゼロ終了するので、CI 側で特別なエラーハンドリングは不要です（CLI - 終了コード）。

`apply` か `state sync` か

CI で回すコマンドには 2 通りあります。

コマンド	いつ何が走るか	drift 検知
`tazuna apply`	`tazuna.yaml` で宣言された Manifest を全部 Manager に通す	しない（毎回上書き）
`tazuna state sync`	Build 結果と State を比較し、差分（`added` / `modified` / `always-sync`）だけ反映	する

おおまかな指針:

ブートストラップ初期 / Manifest 数が少ない: tazuna apply が単純で予測しやすい。
Manifest 数が増えて 1 回の apply が重くなった: tazuna state sync で差分のみに絞る。
removed の自動削除が欲しい: state sync + TAZUNA_STATE_SYNC_DELETE=true。誤削除のリスクと相談。

`--atomic` を使うか

tazuna state sync --atomic を付けると、いずれかのリソースでエラーが出たときに State を更新せず終了します。反映自体は途中まで進む ため、CI で「全部入ったか何も入らなかったか」の二値にはなりませんが、State 上の整合性は守れます。詳細は tazuna state sync を参照。

取り外しステージ

CI から tazuna destroy を回す運用は推奨しません。

環境変数 TAZUNA_DESTROY_EXECUTABLE=true を CI に常設すると、誤発火時のガードがプロンプトしか残らなくなる（しかも CI ではプロンプトに答えられないので、--force と組み合わさると無条件で消えます）。
どうしても CI から消す必要がある場合は、手動トリガの専用 workflow を作り、その job に限って環境変数を渡す構成にします。

詳細は tazuna destroy の運用を参照してください。

Tag を使った段階的反映

tazuna apply --tags で、CI で反映する Manifest を絞り込めます。たとえば「インフラレイヤと application レイヤを分けて回す」「実験 add-on を独立した job で回す」といった段階的反映に向きます。

tazuna apply --tags infra        # 先に基盤を入れる
tazuna apply --tags application  # 次にアプリ側

タグの設計は tazuna.yaml 側の manifests[].tags で行います。

監視・通知との接続

CI とは別系で、tazuna state diff の定期実行を回しておくのが推奨構成です。詳細は Drift モニタリングを参照してください。 CI で apply の成否を見るだけだと、「tazuna.yaml の更新が無いのに drift が起きている」ケースを取り逃がします。

Keyboard shortcuts

Tazuna