コマンドのリファレンス

tegata v0.3.1 の文書

tegata のすべてのコマンドと、その引数、出すものです。下の出力は、examples/minimal（local の保存先。クラウドのアカウントなし）で取りました。

コマンド	書き方	保存先を変えるか	プロバイダーを動かすか
`init`	`tegata init [--upgrade]`	いいえ	いいえ（入れる）
`check`	`tegata check [<identity> <templates>]`	いいえ	`describe`
`status`	`tegata status`	いいえ	`describe`
`apply`	`tegata apply [--yes \| --dry-run]`	はい	`create`、`read`
`rotate`	`tegata rotate [--yes \| --dry-run] <resource>...`	はい	`create`
`settle`	`tegata settle [--yes] <resource>...`	はい	いいえ
`prune`	`tegata prune [--yes] [<resource>...]`	はい	`delete`
`set`	`tegata set [--yes] <resource>`	はい	いいえ
`import`	`tegata import [--yes] <templates> <dir>`	はい	いいえ
`migrate`	`tegata migrate`	いいえ	いいえ
`env`	`tegata env <name>`	いいえ	いいえ
`render`	`tegata render [--project <p> \| --store-dir <d>] [--on-change <cmd>] [--exit-code] [--fail-on-missing] <templates> <out>`	いいえ	いいえ

render 以外のコマンドは、tegata.yaml を置いていて、保存先を管理できる場所で動かします。render はサーバーで動かします。値を変えるコマンド（apply、rotate、settle、set、import）は、変わった値を届け先にも書きます。

全体の引数

引数	説明
`-f, --file <FILE>`	設定のファイル。既定は `tegata.yaml`。`TEGATA_FILE` でも。`render` は読まない
`-e, --env <NAME>`	設定に `environments` があるときの環境。`TEGATA_ENV` でも。そのときは `render`、`init`、`check`、`env` 以外のすべてのコマンドに要る
`-h, --help`	tegata か、1 つのコマンドのヘルプ（`tegata apply --help`）
`-V, --version`	版

環境変数：設定のリファレンスを見てください。

終了コード

コード	意味
0	成功
1	エラー。標準エラー出力に `error: ...` と出す。`check` は問題を見つけたときも 1 で終わる
2	使い方の誤り。知らない引数など
3	`render --exit-code`：ファイルが変わった

render は、埋められなかった名前が残っても 0 で終わり、代わりにそれを挙げます（--fail-on-missing を付けるとエラーになります）。

エラーのあとには、助けになるページを示す see: の行が出ます。失敗したコマンドのこのリファレンスの節か、tegata.yaml を読めないときや正しくないときは設定のリファレンスです。tegata --help は主なページを挙げ、tegata <command> --help の最後には、そのコマンドの節へのリンクがあります。

$ tegata settle admin_password
error: admin_password has no previous
see: https://github.com/k-kawa/tegata/blob/main/docs/reference/commands.md#tegata-settle

ファイル

ファイル	書くもの	説明
`tegata.yaml`	あなた	設定。コミットする
`tegata.lock`	`init`	選んだプロバイダーの版、その要件、署名の鍵、すべてのプラットフォームの実行ファイルの SHA-256。コミットする
環境のファイル	あなた	`environments` がファイルを名指しするときの、環境の上書き。コミットする
雛形のディレクトリ	あなた	`render` が埋める `__NAME__` の入ったファイル。ふつうはアイデンティティごとに 1 つのディレクトリ
`$TEGATA_CACHE_DIR/...`	`init`	入れたプロバイダー
`render` の出力のディレクトリ	`render`	モード 0700。各ファイルは 0600 で、一時的なファイルに書いてから名前を変える
`store.local.dir`	すべてのコマンド	シークレットごとに 1 つ、そのままの文字の JSON のファイル。モード 0600。tegata を試すときと試験のためだけ

tegata init

tegata init [--upgrade]

source のあるすべてのプロバイダーを入れ、tegata.lock を書きます。プロバイダーごとに：

version に合う、いちばん新しいリリースを選ぶ。tegata.lock に版があれば、それのまま
SHA256SUMS を取ってきて、その minisign の署名を public_key で確かめる（github.com/k-kawa/tegata には公式の鍵が組み込まれている）
この機械向けの実行ファイルを取ってきて、SHA256SUMS と照らし合わせる
版と、すべてのプラットフォームのファイルの SHA-256 を tegata.lock に書く

引数	説明
`--upgrade`	lock した版ではなく、要件が許すいちばん新しい版を選ぶ

lock したあとでファイルが変わったリリースは、受け付けません。ほかのコマンドは、lock と合う入れ済みのプロバイダーだけを使い、そうでなければ tegata init を流すように言います。source のプロバイダーがなければ、no providers with a source と出します。

tegata init
GITHUB_TOKEN=$(gh auth token) tegata init --upgrade
TEGATA_PROVIDER_MIRROR=/mnt/mirror tegata init   # a machine without internet access

tegata check

tegata check [<identity> <templates>]

設定を確かめ、何も変えません。YAML が読めること、すべてのプロバイダーが describe に答え、リソースの type を持っていることを見ます。ok を出すか、問題を 1 行に 1 つずつ出して 1 で終わります。

アイデンティティと雛形のディレクトリ（そのアイデンティティとして動くサーバーが tegata render に渡すもの）を渡すと、雛形の中のすべての __NAME__ が、どれかのリソースで作られ、そのアイデンティティが読めることも確かめます。アイデンティティは読めるが雛形が使っていないシークレットは、警告として挙げます（確かめは失敗しません）。アイデンティティごとに 1 回流してください。たとえば CI で、デプロイの設定の隣で流します。ディレクトリは、render と同じく今のディレクトリからの相対です。

$ tegata check edge templates/edge
warning: identity edge: can read MAIL, which its templates do not use
identity edge: KEY is in the templates but edge cannot read it (add edge to its readers)
identity edge: NOT_MADE is in the templates but no resource makes it
error: 2 problems
see: https://github.com/k-kawa/tegata/blob/main/docs/reference/commands.md#tegata-check

古い形のファイルでは、check は各 role の templates も比べます。それが、その role が何を読むかを決めるためです。

設定に環境があるとき、-e なしの check はすべての環境を確かめ（各行は環境の名前で始まります）、同じ Google Cloud のプロジェクトを使う環境や、同じ IAM のメンバーに読む権限を与える環境を挙げます。-e を付けると、その環境だけを確かめます。

$ tegata check app templates/app
ok (staging, production)

tegata status

tegata status

リソースごとに：そのプロバイダーと種類、最新の世代、prune を待っている古い世代がいくつあるか。シークレットごとに：有効な最新の版と、それを読むアイデンティティ。そのあと、managed-by=tegata のラベルがあって YAML にもうないシークレット、そのあと各届け先の状態を出します。

$ tegata status
admin_password (manual) generation 1
  ADMIN_PASSWORD                   v1           app
mail (value) -
  MAIL_FROM                        v1           app
session_key (random) generation 2 (+1 to prune)
  SESSION_KEY                      v2           app
  PREVIOUS_SESSION_KEY             v1           app

世代が - なのは、記録がないということです（data のリソースか、まだ値がない）。(no value) は、シークレットはあるが有効な版がないということです。

tegata apply

tegata apply [--yes | --dry-run]

保存先を YAML に合わせます。

ないシークレットを作り、managed-by=tegata と tegata-resource=<resource> のラベルを付ける
各シークレットの読む権限を、その readers のメンバーとちょうど同じにする
名前を変えたリソースのシークレットを、今それを書いているリソースに移す
まだ値のない managed のリソースの、最初の世代を作る（manual のリソースは tegata set を待つ）
data のリソースを読み直し、出力が変わったところに版を足して、古い版を無効にする
まだ届けていない値や変わった値を届け先に書き、この環境で設定が書いているシークレットのうち、設定がもう挙げていない届け先を消す（リソースを消すとき、保存先を共にするとき）

1 つのリソースで失敗しても、ほかは止まりません。コマンドは failed: <names> で終わります。

引数	説明
`--yes`	聞かない：前の値をすぐに使えなくする値を作る前にも、`confirm: true` の環境でも。端末の外ではそのどちらにも要る
`--dry-run`	どのリソースに新しい世代ができるか、届け先に何が届くかを見せる。何も変えない

$ tegata apply
created secret SESSION_KEY
readers of SESSION_KEY: serviceAccount:app@example.iam.gserviceaccount.com
SESSION_KEY: version 1
session_key: generation 1
PREVIOUS_SESSION_KEY: version 1 (the value of SESSION_KEY)
admin_password: no value yet (put it with `tegata set admin_password`)

tegata rotate

tegata rotate [--yes | --dry-run] <resource>...

名指しした managed のリソースそれぞれに、新しい世代を作ります。リソースに previous があれば、先に今の値をそこに写すので、サービスはしばらく両方の値を受け付けられます。data のリソースは入れ替えられません（apply が読み直します）。引数は apply と同じです。

$ tegata rotate --dry-run session_key
would make a new generation of session_key
$ tegata rotate session_key
SESSION_KEY: version 2
session_key: generation 2

tegata settle

tegata settle [--yes] <resource>...

今の値を previous に写し、古い値が受け付けられないようにします。自分のアプリケーションが確かめる値の入れ替えは、これで終わります（シークレットに previous が要るとき）。リソースに previous がなければ、<resource> has no previous で失敗します。

$ tegata settle session_key
PREVIOUS_SESSION_KEY: version 2 (the value of SESSION_KEY)

tegata prune

tegata prune [--yes] [<resource>...]

最新より古い世代それぞれについて（名指しがなければ、すべてのリソースの）、プロバイダーにそれが作ったものを消させ、その世代の版を無効にし、その記録を消します。previous の古い版も無効にします。版は無効にするだけで、決して消しません。

外のプロバイダーのために set や import で入れた世代は、tegata が作ったものではないので、プロバイダーの上では消しません。prune はそう伝えるので、手で片付けてください。
プロバイダーが断ることがあります（たとえば tunnel_token で、入れ替えの前に起動したコネクターがまだつながっているとき）。コマンドはそこで止まります。
prune するものがなければ、何も出しません。

$ tegata prune
SESSION_KEY: disabled version 1
session_key: pruned generation 1
PREVIOUS_SESSION_KEY: disabled version 1

tegata set

tegata set [--yes] <resource>

値を手で、新しい世代として入れます。端末では入力を隠して聞き、ほかでは標準入力から読みます。manual のリソースや、取っておいた値を戻すときに使います。リソースに previous があれば、先に今の値をそこに写します。data のリソースは受け付けません。

tegata set admin_password
op read op://infra/admin/password | tegata set admin_password
op read op://infra/admin/password | tegata -e production set --yes admin_password   # production has confirm: true

tegata import

tegata import [--yes] <templates> <dir>

tegata に移るためのものです。<dir> には、<templates> の雛形と同じ名前の、tegata を使う前に手で埋めたファイル（たとえば、今サーバーが使っている設定のファイル）を置きます。tegata はそれぞれのファイルを雛形と照らし合わせて値を取り出し、まだ値のないシークレットに入れます。すでに値のあるシークレットは飛ばします（already has a value; skipped）。prune は、import した世代をプロバイダーの上で消すことはありません。

tegata import templates/app /etc/app

settle、prune、set、import の --yes は、confirm: true の環境の問いを飛ばします（環境）。ほかの場所では、これらのコマンドは聞きません。

tegata env

tegata env <name>

1 つの環境の設定を出します。共通の部分に、その環境の上書きをまとめたもので、-e <name> を付けたときにコマンドが使うものです。何も変えません。コメントは残らず、confirm はコメントとして出すので、出力はそれだけで設定として読めます（ガイドのように、ほかのファイルと比べるときに）。

$ tegata env production
# confirm: true (commands that change the store ask first)
stores:
  main:
    gcp:
      location: asia-northeast1
      project: myapp-prod
...

tegata migrate

tegata migrate

今の形の設定を標準出力に出し、何も変えません。古い形（store、roles、resources.*.secrets）のファイルでは、各シークレットの readers を雛形から埋めます。それが今 apply が与えているものなので、migrate したあとの apply は保存先を何も変えません。コメントは残りません。ほかのコマンドは古い形のファイルも読みますが、tegata migrate を挙げて警告します。environments のあるファイルはすでに今の形で、migrate はそう伝えます。

$ tegata migrate > tegata.new.yaml
# read access no longer comes from templates; to check that each identity can read its templates:
#   tegata check app ./templates/app
$ diff tegata.yaml tegata.new.yaml
$ mv tegata.new.yaml tegata.yaml
$ tegata check app ./templates/app

tegata render

tegata render [--project <project> | --store-dir <dir>] [--on-change <command>] [--exit-code]
              [--fail-on-missing] <templates> <out>

<templates> の直下のすべてのファイルを、各シークレットの有効な最新の版で埋め、<out> に同じ名前で書きます。読むのは保存先だけです。YAML も、プロバイダーも、サーバーでの tegata init も要りません。

<out> にすでにあるものと中身が同じファイルは書き直さないので、更新の時刻は変わりません。ほかは一時的なファイルに書いてから名前を変えます。そのため、render はタイマーで動かせ、何が変わったかを伝えます。

引数	説明
`--project <project>`	Secret Manager のプロジェクト。Compute Engine の VM ではなくてもよい（メタデータのサーバーから取る）
`--store-dir <dir>`	代わりに `local` の保存先を読む（tegata を試すときと試験のため）
`--on-change <command>`	どれかのファイルが変わったとき、書いたあとに 1 回、そのコマンドを `sh -c` で動かす。変わったファイルの名前が、空白で区切って `TEGATA_CHANGED` に入る。失敗すると `render` も失敗する（ファイルはもう書いてある）
`--exit-code`	ファイルが変わったら 3、何も変わらなければ 0 で終わる
`--fail-on-missing`	保存先にない名前や読めない名前があるとき、`__NAME__` をファイルに残す代わりに、何も書かずに失敗する

印	置き換わるもの
`__NAME__`	シークレット `NAME` の値
`__NAME\|sha256__`	値の SHA-256（小文字の 16 進）

保存先にない名前や、呼んだ人が読めない名前は、書いたまま残し、挙げます。__ と __ の間の、名前として正しくない文字（__init__）はそのままにします。雛形を見てください。

$ tegata render --project my-project templates/app /etc/app
filled 1 files
  not in the store: NEW_KEY

$ tegata render --on-change 'systemctl reload-or-restart app' templates/app /etc/app
filled 3 files
  changed: app.env
ran: systemctl reload-or-restart app (exit status: 0)

入れ替えがサーバーに自分で届くように、タイマーで動かすには：サーバーで動かす。

このページの問題を報告する（GitHub。英語でも日本語でも）