tazuna.yaml スキーマ

このページは Tazuna への唯一の入力ファイルである tazuna.yaml の仕様をまとめます。 ここでは Manifest type 別の固有フィールド（kustomize / helmfile / genesissecret / oras）と Test plugin のフィールドには深入りしません。 それらは順次、専用のリファレンスページで扱います。

ルート (Tazuna)

tazuna.yaml のルートオブジェクトです。Kubernetes manifest と同じ apiVersion / kind / spec の 3 つを持ちます。

最小例:

apiVersion: tazuna.pepabo.com/v1
kind: Tazuna
spec:
  manifests:
    - name: nginx
      type: kustomize
      path: ./kustomize/nginx

TazunaSpec

minimumSupportedTazunaVersion

• この tazuna.yaml を安全に処理できる tazuna バイナリの 最小バージョン を semver 形式で宣言します（例: 1.4.0）。先頭の v は許容されます（v1.4.0 も可）。
• tazuna.yaml を読み込む 任意の操作（apply / destroy / plan / build / check / status / tags / state * など）で、実行中の tazuna のバージョンが この値を 下回る とエラーで終了します。新しい記法を要求する tazuna.yaml を 古いバイナリで誤って処理してしまう事故を防ぎます。
• 未設定（空文字）の場合は制約なしです。
• 値が semver として不正な場合は設定エラーになります。
• 実行中の tazuna がローカルビルド（dev など semver でないバージョン）の場合は 比較をスキップします。ローカル開発がこのゲートでブロックされないようにするためです。

spec:
  minimumSupportedTazunaVersion: "1.4.0"
  manifests: []

context_matches

• 各要素は Go の regexp パッケージでコンパイル可能な正規表現でなければなりません。 コンパイルに失敗すると tazuna check の段階で弾かれます。
• 空配列または未設定の場合、context のチェックは行われません。
• 設定されている場合、tazuna apply / tazuna destroy はクラスタに触る前に current-context を検証します。マッチしないと処理を中断します。

context_match_mode

• or（デフォルト）: context_matches のいずれか 1 つにでもマッチすれば OK。
• and: context_matches の すべて にマッチする必要があります。
• それ以外の値を指定するとバリデーションエラーになります。

例:

spec:
  context_matches:
    - ^staging-
    - -tokyo$
  context_match_mode: and
  manifests: []

Manifest

spec.manifests[] の各要素です。1 つの Manifest が、1 つのバックエンド （kustomize / helmfile / 他）による「クラスタへ入れる単位」に対応します。

(※) includes を指定するときは type / path は不要。 それ以外のときは type と path が必須です。

name

• 必須。
• 使える文字種は ^[a-zA-Z0-9_-]+$。
• _metadata は内部利用のため予約されており、Manifest 名としては使えません。
• includes 展開後の全 Manifest 間で 一意 である必要があります。 重複していると tazuna check でエラーになります。

tazuna check では name のバリデーションは エラー として扱いますが、tazuna apply / build / destroy では移行期間として 警告ログのみ が出る挙動になっています。 新規導入時は tazuna check で先に通しておくのが安全です。

path

• includes を使わないときは必須。
• tazuna.yaml 自身の置かれているディレクトリ起点 の相対パスとして解釈されます。 コマンドを実行した cwd 起点ではありません。
• tazuna check の時点で実在チェックが行われます。
• type ごとに path が指すべき先が異なります。

詳細な解釈は各 Manifest type 別ページ を参照してください。

type

• includes を使わないときは必須。
• 値の一覧は Manifest type を参照。
• 未対応の値を指定するとバリデーションエラーになります。

tags

• 文字列の配列。Tazuna 自身は内容を解釈しません。
• --tags フラグでの絞り込み時に、指定されたタグのいずれかが付いている Manifest だけが処理対象になります（OR 評価）。

dependsOn

• この Manifest を apply する前に 必ず完了している必要がある Manifest 名の配列。
• includes 展開後の全 Manifest 集合に含まれる名前でなければなりません。
• 自分自身を含めることはできません（自己依存は循環の特殊例として弾かれます）。
• 全体の依存関係に循環が含まれていてはなりません。
• tazuna.yaml 内で 1 つでも dependsOn が使われていれば Runner は DAG モードに 切り替わり、同じ依存深度の Manifest を 並列に 実行します。1 つも使われていなければ 従来通り宣言順 1 件ずつの実行になります。

詳細と動機は dependsOn による DAG 実行 を参照してください。

例:

spec:
  manifests:
    - name: cni
      type: kustomize
      path: ./cni
    - name: cert-manager
      type: helmfile
      path: ./cert-manager
      dependsOn: [cni]
    - name: ingress
      type: helmfile
      path: ./ingress
      dependsOn: [cni]
    - name: app
      type: kustomize
      path: ./app
      dependsOn: [cert-manager, ingress]

Providers

spec.providers[] は GenesisSecret から参照される Secret provider の宣言リストです。 組み込みの default-op（1Password）以外を使う、または provider を複数並べて使い分けたい ときに書きます。

spec:
  providers:
    - name: primary-op
      type: onepassword
      onepassword: {}
    - name: ops-envfile
      type: envfile
      envfile:
        path: ./secrets/ops.env

詳細は Secret provider を参照してください。

IncludeFile

manifests[].includes[] の各要素です。別の tazuna.yaml を読み込み、その manifests[] を展開します。

includes を使う

spec:
  manifests:
    - name: infra
      includes:
        - path: ./infra/tazuna.yaml
        - path: ./addons/tazuna.yaml

• includes を持つ Manifest は、自身が持つ type / path / tags などの 「Manifest 本体」のフィールドは 無視 されます。
• includes は ネスト不可 です。include 先の tazuna.yaml が さらに includes を持っていても展開されません。
• include 先で定義された Manifest の name も含めて、最終的な全 Manifest 間で name がユニークである必要があります。

Manifest type 別フィールド

type に対応するフィールド（kustomize / helmfile / genesisSecret / oras）は、それぞれ専用のリファレンスページに切り出しています。

ここでは存在と最低限の役割だけを示します。

tests フィールド

spec.tests および manifests[].tests の要素である TestPluginSpec の詳細仕様は Test plugin を参照してください。 ここでは置かれる位置と実行タイミングだけを示します。

• 全体 tests (spec.tests): すべての Manifest 適用が終わったあとに実行されます。
• 個別 tests (manifests[].tests): その Manifest の適用直後に実行されます。

バリデーションのまとめ

tazuna check が tazuna.yaml に対して行う検証を一覧にしておきます。 クラスタには触れず、ここで失敗するものはすべて事前に弾けます。

• apiVersion / kind を設定するなら値が正規値と完全一致すること。
• spec.minimumSupportedTazunaVersion を設定するなら semver として妥当で、実行中の tazuna のバージョンがそれ以上であること（ローカルビルドは比較をスキップ）。なお この検証は check に限らず、tazuna.yaml を読み込むすべての操作で実行されます。
• spec.manifests[] の各要素について:
  • includes が無い場合: path と type が設定されていること。
  • type が既知の値（kustomize / helmfile / genesissecret / oras）であること。
  • path の指す場所が実在すること。
• spec.manifests[].name が必須・使用可能文字・ユニーク・予約語禁止を満たすこと。
• spec.manifests[].dependsOn が既存 Manifest 名のみを参照し、自己参照・循環依存を含まないこと。
• spec.context_matches が正規表現としてコンパイル可能であること。
• spec.context_match_mode が or / and / 未設定のいずれかであること。
• spec.providers[] の各要素について: name がユニークかつ非空、default-op を含まないこと、 type が onepassword / envfile のいずれかであること、type と整合した config を持つこと。
• type: helmfile の場合: helmfile.vars の各値が env / static / op の いずれかを満たすこと（詳細は helmfile のリファレンスページ）。
• type: oras の場合: oras.reference が必須、oras.delegate.type が helmfile / kustomize のいずれかであること。
• includes を指定する場合: 各 include.path が必須で、ファイルが実在すること。