はじめに
Pulumi ESC（Environments, Secrets, and Configuration）の公式クイックスタートを、手順どおりに試してみました。
ESC は、API キーやリージョン名のような「設定値・シークレット」を Pulumi Cloud 上の 1 か所にまとめておき、CLI や Pulumi のスタックから取り出せるサービスです。スタックごとに同じ値を pulumi config set していた場合、まとめて管理できるようになります。
-
環境（Environment）: 設定値をまとめた YAML の入れ物です。今回は
my-project/devを作ります -
スタック: Pulumi で作るインフラの単位（
dev/prodなど）です。設定はPulumi.<スタック名>.yamlに書きます
この記事で最終的にできあがる形は次のとおりです。
ユースケース
公式ドキュメントの Secrets & Configuration では、次のような使い方が紹介されています。この記事で試すのは 1 つ目だけです。
| こんなとき | ESC でできること |
|---|---|
| Pulumi のプログラムで API キーやリージョンを使いたい | 環境の値を pulumi.Config でそのまま読む（ドキュメント） |
| Pulumi 以外のコマンドやスクリプトにも同じ値を渡したい |
pulumi env run で環境変数として渡す（ドキュメント） |
| チームで共通の設定を使い回したい | 共通の環境を作り、ほかの環境から imports で読み込む（ドキュメント） |
| AWS などのアクセスキーを手元に置きたくない | OIDC で有効期限の短いクレデンシャルをその都度発行する（ドキュメント） |
| すでに AWS Secrets Manager や Vault にシークレットがある | 外部のシークレットストアから値を取り込む（ドキュメント） |
| アプリケーションの実行時に値を読みたい | Node.js / Python / Go / .NET の SDK で取得する（ドキュメント） |
やってみた
手順は公式の Get started with Pulumi ESC に沿っています。環境の作成と編集は Web UI（Pulumi Cloud）、値の取り出しとスタックの操作は CLI で行います。
手順 0: 準備
Pulumi アカウントと Pulumi CLI を用意します。ESC のコマンド（pulumi env）は Pulumi CLI に同梱されているので、別途インストールは不要です。手順 4 で TypeScript のプロジェクトを作るため、Node.js も使います。
brew install pulumi/tap/pulumi
pulumi login
pulumi whoami
pulumi whoami に自分のユーザー名が出れば準備完了です。
手順 1: Web UI で環境を作る
Pulumi Cloud の画面で、左メニューの Environments → + Create Environment → New Environment を選び、次のように入力します。
| 項目 | 値 |
|---|---|
| Project name | my-project |
| Environment name | dev |
Create Environment を押すとエディタが開くので、次の YAML を貼り付けて Save します。fn::secret を付けた値はシークレット（暗号化して保存される値）になります。
values:
region: ap-northeast-1
apiKey:
fn::secret: demo-secret-123
保存すると、定義の demo-secret-123 は ciphertext: の暗号文に置き換わります。一方、画面のプレビュー欄には復号された値が表示されます。
手順 2: CLI で値を取り出す
作った環境を手元の CLI から読みます。pulumi env get は環境の定義から値を取り出すコマンドで、手元で試すとシークレットは [secret] と伏せられました。pulumi env open は環境を開いて値を解決するコマンドで、シークレットも復号されて表示されます（CLI リファレンス）。
pulumi env get my-project/dev
pulumi env open my-project/dev
get では apiKey が [secret]、open では demo-secret-123 と表示されれば成功です。open は平文でシークレットが出るので、画面共有中などは注意が必要です。
手順 3: スタックから読めるように環境を書き換える
スタックの設定（pulumi config）として値を渡すには、values の下の pulumiConfig ブロックに値を置く必要があります。pulumiConfig の外にそのまま置いた値は pulumi config には出てきません。
手順 1 と同じ画面で定義を次のように書き換えて Save します（CLI なら pulumi env edit my-project/dev でも編集できます）。
values:
pulumiConfig:
region: ap-northeast-1
apiKey:
fn::secret: demo-secret-123
手順 4: スタックを作って環境を紐付ける
空の TypeScript プロジェクトを作ります。ESC は Pulumi Cloud バックエンドのスタックからしか参照できないため、S3 やローカルファイルをバックエンドにしている場合はこの手順は動きません。
mkdir esc-demo && cd esc-demo
pulumi new typescript --name esc-demo --stack dev --yes
スタックの設定ファイル Pulumi.dev.yaml に、参照する環境を書きます。ここでは組織名を付けずに プロジェクト名/環境名 で書きます。
cat > Pulumi.dev.yaml <<'EOF'
environment:
- my-project/dev
EOF
pulumi config
pulumi config に apiKey [secret] と region ap-northeast-1 が並べば紐付け完了です。自分では pulumi config set を 1 回も打っていないのに、環境の値が見えています。
environment には複数の環境を並べられ、後に書いた環境の値が優先されます。my-project/dev@3 のように書けばバージョンを固定することもできます。
手順 5: プログラムから値を読む
index.ts を書き換えます。読み方は普段の pulumi.Config と同じで、シークレットは getSecret で読みます。
cat > index.ts <<'EOF'
import * as pulumi from "@pulumi/pulumi";
const config = new pulumi.Config();
export const region = config.get("region");
export const apiKey = config.getSecret("apiKey");
EOF
pulumi up --yes
pulumi stack output
pulumi stack output apiKey --show-secrets
Outputs に region: "ap-northeast-1" と apiKey: [secret] が出て、--show-secrets を付けたときだけ demo-secret-123 が表示されれば成功です。getSecret で読んだので、ESC から受け取ったシークレットはスタックの出力でもシークレットとして扱われたままでした。
なお、このプログラムはクラウドのリソースを作らないので、作成されるのはスタック自体（pulumi:pulumi:Stack）の 1 つだけです。
後片付け
スタックと環境を削除します。
pulumi destroy --yes
pulumi stack rm dev --yes
pulumi env rm my-project/dev --yes
cd .. && rm -rf esc-demo
まとめ
ESC の環境に値を 1 回書いておけば、CLI からも Pulumi スタックからも同じ値を読めることを確認できました。スタックが増えるほど、pulumi config set を繰り返さずに済む効果が大きくなりそうです。