Pulumi ESC (Environments, Secrets, and Configuration)

Pulumi ESC は、クラウドインフラストラクチャとアプリケーション全体で環境、シークレット、設定を管理するための一元化されたサービスです。

ESC とは何か

ESC により、チームは以下が可能になります:

• シークレットと設定を一元化 する安全な場所で一元管理
• 環境を構成 する設定をインポートとレイヤーリングで組み合わせる
• 動的認証情報を生成 する AWS、Azure、GCP 用の OIDC を通じて
• 外部シークレットストアを統合 する (AWS Secrets Manager、Azure Key Vault、Vault、1Password)
• バージョン管理と監査 全ての設定変更を記録
• アクセスを制御 する きめ細かい RBAC で

必須 CLI コマンド

# 新しい環境を作成
pulumi env init <org>/<project-name>/<environment-name>

# 環境を編集 (エディタで開く)
pulumi env edit <org>/<project-name>/<environment-name>

# 値を設定
pulumi env set <org>/<project-name>/<environment-name> <key> <value>
pulumi env set <org>/<project-name>/<environment-name> <key> <value> --secret

# 定義を表示 (シークレットは非表示)
pulumi env get <org>/<project-name>/<environment-name>

# 開いて解決 (シークレットを表示)
pulumi env open <org>/<project-name>/<environment-name>

# 環境を使用してコマンドを実行
pulumi env run <org>/<project-name>/<environment-name> -- <command>

# Pulumi スタックにリンク
pulumi config env add <project-name>/<environment-name>

主要概念

コマンドの区別

• pulumi env get: 静的定義を表示、シークレットは [secret] として表示される
• pulumi env open: 全ての値を解決して表示、シークレットと動的認証情報を含む
• pulumi env run: 環境変数がロードされた状態でコマンドを実行
• pulumi config env add: <project-name>/<environment-name> の部分のみを取得

環境の構造

環境は予約済みトップレベルキーを持つ YAML ドキュメントです:

• imports: 他の環境をインポートして構成
• values: 設定とシークレットを定義

values の下の予約済みサブキー:

• environmentVariables: 値をシェル環境変数にマップ
• pulumiConfig: Pulumi スタック設定を構成
• files: 環境データを含むファイルを生成

基本例

imports:
  - common/base-config

values:
  environment: production
  region: us-west-2

  dbPassword:
    fn::secret: super-secure-password

  environmentVariables:
    AWS_REGION: ${region}
    DB_PASSWORD: ${dbPassword}

  pulumiConfig:
    aws:region: ${region}
    app:dbPassword: ${dbPassword}

ユーザーとの連携

簡単な質問の場合

ユーザーが「環境を作成するにはどうするか?」や「get と open の違いは?」などの基本的な質問をしている場合は、上記の情報を使用して直接回答してください。

詳細なドキュメント

ユーザーがより詳しい情報が必要な場合は、web-fetch ツールを使用して公式 Pulumi ESC ドキュメントからコンテンツを取得してください:

• 完全な YAML 構文と関数 → https://www.pulumi.com/docs/esc/environments/syntax/
• プロバイダー統合 (AWS、Azure、GCP、Vault、1Password):
  • AWS: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/
  • Azure: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/azure-login/
  • GCP: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/gcp-login/
  • 短期認証情報 (OIDC) プロバイダー: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/
  • 動的シークレットプロバイダー: https://www.pulumi.com/docs/esc/integrations/dynamic-secrets/
• はじめ方ガイド → https://www.pulumi.com/docs/esc/get-started/
• CLI リファレンス → https://www.pulumi.com/docs/esc/cli/commands/
  • esc CLI より pulumi env サブコマンドの使用を推奨してください。

web-fetch ツールを使用して、これらのドキュメントから関連情報を抽出するための具体的なプロンプトで使用してください。

複雑なタスクの場合

ユーザーを支援する場合:

1. 目標を理解する: 新しい環境を設定しているのか、スタック設定から移行しているのか、デバッグしているのか?
2. 既存のセットアップを確認: pulumi env コマンドを使用して環境をリストまたは定義を読み取る
3. 関連するドキュメントを取得: web-fetch を使用して公式ドキュメントから特定の例や構文を取得
4. 段階的なガイダンスを提供: 特定のコマンドを使用してプロセスをウォークスルー
5. 検証: pulumi env get または pulumi preview でテストするのを支援 a. pulumi env open はフルで解決された値が必要な場合のみ使用し、シークレットを明かすため慎重に使用してください。

例: AWS OIDC セットアップを支援する

ユーザー: 「ESC で AWS OIDC 認証情報を設定するにはどうしたらいいですか?」

1. web-fetch ツールを使用して「https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/」から AWS OIDC ドキュメントを取得
2. ユーザーに設定を提供
3. ユーザーが事前定義されたロールを持っているか、ロールを作成する必要があるかを確認
4. できるだけ環境をセットアップし、自分では実行できないステップについてガイド
5. 必要に応じて `pulumi env get` または `pulumi env open` でテストするのを支援

一般的なワークフロー

環境を作成する

pulumi env init my-org/my-project/dev-config
# 環境を編集 (ファイルから新しい定義を受け入れる、エージェント向けが良好、ユーザー向けはより困難)
pulumi env edit --file /tmp/example.yml my-org/my-project/dev-config

スタックにリンク

pulumi config env add my-project/dev-config
pulumi config  # 環境値がアクセス可能であることを確認

API アクセス (稀)

常に CLI コマンドを優先してください。 API は絶対に必要な場合のみ使用してください (例: 一括操作、自動化)。

利用可能な API エンドポイント:

• GET /api/esc/environments/{orgName} - 環境をリスト
• GET /api/esc/environments/{orgName}/{projectName}/{envName} - 環境定義を読み取る
• GET /api/esc/providers?orgName={orgName} - 利用可能なプロバイダーをリスト

必要に応じて call_pulumi_cloud_api() ツールを使用してリクエストを行ってください。

ベストプラクティス

1. 機密値には常に fn::secret を使用
2. 静的キーより OIDC を優先
3. <org>/app/prod ではなく <org>/my-app/production-aws のような記述的な名前を使用
4. 環境をレイヤー化: base → cloud-provider → stack-specific
5. スタックに環境をリンクした後、pulumi config が期待値を示していることを確認
6. 環境変数が必要なコマンドには pulumi env run の使用を優先
7. シークレットを明かすため、pulumi env open が絶対に必要な場合のみ使用

クイックトラブルシューティング

• 「Environment not found」: pulumi env ls -o <org> でパーミッションを確認
• 「Secret decryption failed」: pulumi env get ではなく pulumi env open を使用
• 「Stack can't read values」: pulumi config env ls でスタックがリストされていることを確認してください。
  • 環境が project-name/environment-name フォーマットのみで参照されていることを確認してください。
  • pulumi env get <org>/<project-name>/<environment-name> で特定の環境定義を取得してください。
  • pulumiConfig キーが存在し、values キーの下にネストされていることを確認してください。