GenesisSecret スキーマ

GenesisSecret は、外部の Secret ストア（現バージョンでは 1Password）にある秘匿情報を取得し、 Kubernetes Secret として 生成 するための宣言です。

GenesisSecret は Kubernetes の CRD ではなく、Tazuna が読む YAML スキーマ です。 クラスタに GenesisSecret リソースが現れるわけではなく、適用結果として Secret が現れます。

tazuna.yaml からは type: genesissecret の Manifest として参照します。

# tazuna.yaml
spec:
  manifests:
    - name: aws-credentials
      type: genesissecret
      path: ./genesissecrets/aws.yaml

type: genesissecret の path は YAML ファイル 1 つを直接指します （他の Manifest type のようにディレクトリを指すのではありません）。

ルート (GenesisSecret)

apiVersion / kind のフィールドは構造体に対応する宣言がなく、書いても 読まれずに無視されますが、慣習として apiVersion: tazuna.pepabo.com/v1 / kind: GenesisSecret を書いておくと、後から検証が入っても揃えやすくなります。

GenesisSecretSpec

GenesisSecretGenerate

secrets[] の各要素です。1 つの「Provider 上のアイテム」を表します。

uri の形式

1Password Provider では、url.Parse の結果のうち path の 1 つ目を vault 名、2 つ目を item 名 として解釈します。scheme やホストは現バージョンでは使われません。

tazuna secret-to-genesissecret が自動生成するときは次の形式で書き出します。

op://<op-host>/<vault>/<item>

例:

uri: op://example.1password.com/Platform/aws-credentials

scheme やホストはパースには通りますが、参照されません。 将来別 Provider を増やしたときに使い分けるためのスペースとして残されている、と理解しておくと安全です。

GenesisSecretGenerateItem

items マップの 値 にあたる構造です（キーは Provider から返ってきた field の ID または label）。

例:

items:
  accessKeyID:
    mapTo: AWS_ACCESS_KEY_ID
  secretAccessKey:
    mapTo: AWS_SECRET_ACCESS_KEY

items のキー accessKeyID が Provider 上のフィールド名（preferLabel: true ならラベル名）に対応し、 mapTo がそのまま Kubernetes Secret のキー名になります。 items のキーが Provider 側に存在しないとエラーになります。

GenesisSecretOutput

outputs[] の各要素です。1 つの「出力先」を表します。

(※) 現バージョンでは outputs[] の各要素は kubernetesSecret を必須 とします。 構造体上は stdout も存在しますが、kubernetesSecret == nil だと .spec.output currently supports only KubernetesSecret というエラーで失敗します。

GenesisSecretOutputKubernetesSecret

解決の流れ

tazuna apply 時、type: genesissecret の Manifest は次のように処理されます。

1. manifests[].path の指す YAML ファイル（tazuna.yaml 自身のディレクトリ起点）を読む。
2. spec.secrets[] の各要素を Provider に渡し、フィールド集合を取得する。
3. items の mapTo でキー名をリネームしながら、すべての secrets[] の結果を 1 つの map[string]string にマージする（同じキーが衝突した場合は 後勝ち）。
4. spec.outputs[] の各 kubernetesSecret について、namespace / name を持つ Kubernetes Secret を CreateOrUpdate する。
   • StringData にマージ済みの map がそのまま入る。
   • labels / annotations / type は宣言どおりに付与される。

tazuna destroy 時も同じ Provider 取得が走り、outputs[].kubernetesSecret の namespace / name で示される Secret を削除します。

tazuna build 時は、出力対象が outputs[0].kubernetesSecret 1 件分の Secret YAML として 標準出力に書き出されます（複数 outputs を書いていても、build では先頭 1 件のみが対象）。

State と always-sync

GenesisSecret から生成される Secret は、tazuna state diff 上で常に always-sync 分類になります。 ContentHash で差分判定できる対象ではなく、Provider 側を真実の源として 毎回同期する扱いです。詳細は Diff type / always-sync を参照してください。

例

最小例:

apiVersion: tazuna.pepabo.com/v1
kind: GenesisSecret
spec:
  secrets:
    - uri: op://example.1password.com/Platform/aws-credentials
      preferLabel: true
      items:
        accessKeyID:
          mapTo: AWS_ACCESS_KEY_ID
        secretAccessKey:
          mapTo: AWS_SECRET_ACCESS_KEY
  outputs:
    - kubernetesSecret:
        namespace: default
        name: aws-credentials

type: kubernetes.io/tls を出力する例:

apiVersion: tazuna.pepabo.com/v1
kind: GenesisSecret
spec:
  secrets:
    - uri: op://example.1password.com/Platform/tls-wildcard
      preferLabel: true
      items:
        certificate:
          mapTo: tls.crt
        privateKey:
          mapTo: tls.key
  outputs:
    - kubernetesSecret:
        namespace: ingress-nginx
        name: wildcard-tls
        type: kubernetes.io/tls
        labels:
          managed-by: tazuna

関連

• tazuna.yaml 側からの参照: tazuna.yaml Manifest type 別フィールド
• Provider の語彙: Provider (SecretProvider)
• 既存 Secret を 1Password と GenesisSecret に書き出す: tazuna secret-to-genesissecret
• 用語: GenesisSecret