# keenauth config promote による設定の移行

`keenauth config promote` は、ある環境の設定を別の環境にコピーします（例: `staging` から `production` へ）。ファイルに書き出すことなく、`config export`、`config plan`、`config apply` を手動で実行した場合と同じ手順を実行します:

1. コピー元の `--from` 環境の設定ドキュメントをエクスポートします。
2. そのドキュメントに基づくプランを `--to` 環境で作成します。
3. 差分を表示します: `+` 件の作成、`~` 件の更新、`-` 件の削除。変更のないリソースは件数のみ数えられます。
4. 確認後、プランを適用します。

2つの環境は異なるリージョンにあっても構いません。リージョン同士が直接通信することはありません。ドキュメントはお使いのマシンを経由し、メモリ上にのみ存在します。

## 開始する前に

このコマンドは両方の環境にアクセスする必要があるため、ダッシュボードのサインインを使用します。`keenauth login` でサインインしてください（[keenauth login によるサインイン](/docs/cli/login)を参照）。両方の環境で、コピー元の設定の読み取りとコピー先の設定の書き込みを許可するダッシュボードのロールが必要です。APIキーは 1 つの環境に属するため、`KEENAUTH_API_KEY` が設定されている間はコマンドの実行を拒否し、終了コード 2 で終了します。

## 使用方法

```sh
keenauth config promote --from env_01j9z3k4m5n6p7q8r9s0t1stg0 --to env_01j9z3k4m5n6p7q8r9s0t1prd0
```

| フラグ | 説明 |
|---|---|
| `--from` | コピー元の環境 ID（`env_…`）です。この環境の設定がエクスポートされます（必須）。 |
| `--to` | コピー先の環境 ID（`env_…`）です。プランの作成と適用はこの環境に対して行われます（必須）。 |
| `--kinds` | 移行する種類です。カンマ区切りまたは繰り返し指定できます（`config export` と同様）。既定値: すべての種類。 |
| `--prune` | 移行対象の種類のうち、コピー先にのみ存在するリソースも削除します。このフラグを指定しない場合、それらは保持されます。 |
| `--secrets-from-env` | プランに必要なクライアントシークレットを、ローカルの環境変数から読み取ります（下記を参照）。 |
| `--confirm-deletion` | 保護された削除を `<kind>/<key>` として確認します（`config apply` と同様）。 |
| `--sp-host` | コピー先環境のサービスプロバイダーのホスト（例: `login.example.com`）。プランがコピー先でエンタープライズ接続の OIDC 情報を作成する場合にのみ必要です（下記を参照）。それ以外の場合は省略してください。 |
| `--yes`、`-y` | 確認せずに適用します。標準入力がターミナルでない場合に必須です。 |
| `--output`、`-o` | `table`、`json` または `yaml`。フラグを指定しない場合、ターミナルでは表形式、それ以外では JSON で出力されます。 |

ターミナル（`table`）では、差分は標準出力に、確認の質問は標準エラー出力に表示されます。適用後には、プラン ID、ステータス、変更数を 1 行で表示します。`json` または `yaml` を指定すると、差分は標準エラー出力に出力され、標準出力には適用されたプランのみが出力されるため、スクリプトで読み取れます。コピー先がすでにコピー元と一致している場合、コマンドは `nothing to promote` と表示し、何も適用しません。

標準入力がターミナルではなく `--yes` が指定されていない場合、コマンドはリクエストを送信する前に終了コード 2 で終了します。

## シークレットは移行されません

エクスポートされたドキュメントにシークレットの値が含まれることはありません。接続のクライアントシークレットは `secret_ref` プレースホルダー（例: `KEENAUTH_CONNECTION_GOOGLE_CLIENT_SECRET`）として記載されます。シークレットが必要なコピー先の変更は、`[needs a client secret]` とともに表示されます。

このようなプランは、ご自身でシークレットを指定しない限り適用されません。エラーに示された環境変数を設定し、`--secrets-from-env` を付けてコマンドを再実行してください。値はローカルの環境変数から読み取られ、適用リクエストのボディにのみ送信されます。表示されることもファイルに書き込まれることもなく、コピー元の環境から読み取られることもありません。

```sh
export KEENAUTH_CONNECTION_GOOGLE_CLIENT_SECRET=...   # the production client secret
keenauth config promote --from env_01j9z3k4m5n6p7q8r9s0t1stg0 --to env_01j9z3k4m5n6p7q8r9s0t1prd0 --secrets-from-env
```

## エンタープライズ OIDC とソーシャル接続

エンタープライズ接続の OIDC 設定（`spec.oidc`：発行者、クライアント ID、クライアント認証方式、プロバイダープロファイル）は、接続とともに移行されます。コピー先にこれらの設定がまだない場合、適用時にそれらが作成され、コールバック URL がコピー先のホストから設定されます。そのため、コピー先環境でユーザーがサインインするホストを `--sp-host` に指定してください。ホストは環境ごとに異なるため、ドキュメントには含まれません。

ソーシャル接続のクライアントシークレットは、現時点ではプランから適用できません。プランでこれが必要な場合、`--secrets-from-env` を指定していても適用は `501 not_implemented` で拒否され、何も変更されません。他の種類は `--kinds` を使って移行するか、サポートされるまでコピー元からソーシャル接続を除外してください。

## エラー

プランの有効期間は 1 時間です。プランの作成から適用までの間にコピー先のリソースが変更された場合、適用は `409 config_conflict` で拒否され、何も変更されません。コマンドを再実行してください。その他の適用エラーは `config apply` の場合と同じです。

## 終了コード

| コード | 意味 |
|---|---|
| `0` | プランが適用されたか、移行するものがありませんでした。 |
| `1` | サーバーエラーが発生したか、確認を拒否しました（`aborted`）。 |
| `2` | 使用方法のエラー: 環境 ID が不正または同一、非対話型ターミナルで `--yes` がない、`KEENAUTH_API_KEY` が設定されている、またはプランに必要なシークレットがない。何も適用されません。 |
| `3` | サインインしていないか、サーバーが `401` または `403` を返しました。 |
| `4` | プランにその機能が含まれていません（`403` と `plan_feature_unavailable` の組み合わせ）。 |