pulumi-esc

Pulumi ESC（環境、シークレット、構成）

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

ESC とは？

ESC を使うと、チームは次のことができます。

• シークレットと構成を一元管理：安全な場所に集約します
• 環境を合成：構成をインポートして階層化します
• 動的な認証情報を生成：OIDC を介して AWS、Azure、GCP 向けに生成します
• 外部のシークレットストアと統合：AWS Secrets Manager、Azure Key Vault、Vault、1Password と統合します
• バージョン管理と監査：すべての構成変更を管理、監査します
• アクセスを制御：きめ細かな RBAC でアクセスを制御します

主要な CLI コマンド

# Create a new environment
pulumi env init <org>/<project-name>/<environment-name>

# Edit environment (opens in editor)
pulumi env edit <org>/<project-name>/<environment-name>

# Set values
pulumi env set <org>/<project-name>/<environment-name> <key> <value>
pulumi env set <org>/<project-name>/<environment-name> <key> <value> --secret

# View definition (secrets hidden)
pulumi env get <org>/<project-name>/<environment-name>

# Open and resolve (reveals secrets)
pulumi env open <org>/<project-name>/<environment-name>

# Run command with environment
pulumi env run <org>/<project-name>/<environment-name> -- <command>

# Link to Pulumi stack
pulumi config env add <project-name>/<environment-name>

主な概念

コマンドの違い

• pulumi env get：静的な定義を表示します。シークレットは [secret] と表示されます
• pulumi env open：シークレットや動的な認証情報を含むすべての値を解決し、表示します
• pulumi env run：環境変数を読み込んだ状態でコマンドを実行します
• pulumi config env add：/ の部分のみを受け取ります

環境の構造

環境は、最上位に予約済みキーを持つ 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}

別のスタックの出力を読み取る

fn::open::pulumi-stacks プロバイダーを使って、別のスタックの出力を利用できます。以下の stacks キーと network キーは、任意に指定する名前です。関数が値を解決すると、stacks.network は指定したスタックの出力に置き換えられます。そのため、出力名（vpcId、subnetIds）は静的 YAML には現れず、出力元のスタックがエクスポートした値が使われます。間違えやすい点は次の 2 つです。

• スタックは、プロジェクト名を含む単一の stack: <project>/<stackName> フィールドで指定します。projectName と stackName のフィールドを別々に指定するのではありません。
• 出力はスタック名の直下に解決されます。.outputs. の階層はありません（${stacks.network.outputs.vpcId} ではなく ${stacks.network.vpcId} を使用します）。

例 — スタック名と出力名を独自の値に置き換えてください。

values:
  stacks:
    fn::open::pulumi-stacks:
      stacks:
        network:                 # arbitrary local name for the referenced stack
          stack: my-project/dev  # producer stack to read outputs from
  pulumiConfig:
    # vpcId / subnetIds are whatever the producer stack exports; after the function
    # resolves they are available directly under `stacks.network` (no `.outputs.`).
    vpcId: ${stacks.network.vpcId}
    subnetIds: ${stacks.network.subnetIds}

スキーマの全容：https://www.pulumi.com/docs/esc/providers/pulumi-stacks/

Pulumi Cloud コンソールで環境を表示する

環境のコンソール URL は https://app.pulumi.com/<org>/esc/<project>/<environment> です。ルートのセグメントは environments ではなく esc です。

ユーザーへの対応

簡単な質問の場合

「環境を作成するにはどうすればよいですか？」や「get と open の違いは何ですか？」といった基本的な質問には、上記の情報を使って直接回答してください。

詳細なドキュメントについて

ユーザーがさらに詳しい情報を必要としている場合は、ウェブ取得ツールを使って公式の 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/
  • Pulumi スタックの出力（fn::open::pulumi-stacks）：https://www.pulumi.com/docs/esc/providers/pulumi-stacks/
  • すべてのプロバイダー（一覧）：https://www.pulumi.com/docs/esc/providers/
• 入門ガイド → https://www.pulumi.com/docs/esc/get-started/
• CLI リファレンス → https://www.pulumi.com/docs/esc/cli/commands/
  • esc CLI よりも pulumi env サブコマンドを優先して使用してください。

これらのドキュメントから関連情報を抽出するため、ウェブ取得ツールには具体的なプロンプトを指定してください。

複雑なタスクの場合

ユーザーをサポートするときは、次の手順に従ってください。

1. 目的を把握する：新しい環境の設定、スタック構成からの移行、それともデバッグのどれが目的でしょうか？
2. 既存の設定を確認する：pulumi env コマンドを使って環境を一覧表示するか、定義を読み取ります
3. 関連ドキュメントを取得する：ウェブ取得を使って、公式ドキュメントから具体例や構文を取得します
4. 手順を段階的に説明する：具体的なコマンドを示しながら、プロセスを案内します
5. 検証する：pulumi env get または pulumi preview を使ってテストできるようサポートします a. 解決済みの値をすべて確認する必要がある場合に限り、pulumi env open を使用します。ただし、シークレットが表示されるため慎重に扱ってください。

例：AWS OIDC の設定を支援する

User: "How do I set up AWS OIDC credentials in ESC?"

1. Use the web-fetch tool to get AWS OIDC documentation from "https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/"
2. Provide the user with the configuration
3. Ask the user if they have a pre-defined role or need one created for them
4. Set up as much of the environment as possible, then guide them through any steps that you can't do for them
5. Help them test with `pulumi env get` or `pulumi env open` if necessary

一般的なワークフロー

環境の作成

pulumi env init my-org/my-project/dev-config
# Edit environment (accepts new definition from a file, better for agents, more difficult for users)
pulumi env edit --file /tmp/example.yml my-org/my-project/dev-config

スタックへのリンク

pulumi config env add my-project/dev-config
pulumi config  # Verify environment values are accessible

API アクセス（まれなケース）

常に CLI コマンドを優先してください。 API は、本当に必要な場合（例：一括操作、自動化）に限り使用してください。

利用可能な API エンドポイントには次のものがあります。

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

必要に応じて、pulumi api CLI サブコマンドを使用してリクエストを送信します。例：pulumi api /api/esc/providers -F orgName={orgName}。

ベストプラクティス

1. 機密性の高い値には必ず fn::secret を使用してください
2. 静的キーよりも OIDC を優先してください
3. <org>/app/prod ではなく、<org>/my-app/production-aws のような説明的な名前を使用してください
4. 環境を階層化してください：ベース → クラウドプロバイダー → スタック固有
5. 環境をスタックにリンクした後、pulumi config に期待する値が表示されることを確認してください
6. 環境変数が必要なコマンドには、pulumi env run の使用を優先してください
7. シークレットが表示されるため、pulumi env open は本当に必要な場合に限り使用してください
8. 既存の環境を使用する前に、そのアカウントとロールを確認し、ユーザーの承認を得てください。名前だけを根拠に選択してはいけません。ユーザーの明示的な承認なしに、環境をスタックにリンク（pulumi config env add）してはいけません。また、--yes を渡してはいけません。

認証情報のエラーと既存の環境への対処

認証情報のエラー

まず、エラーメッセージに記載された修正方法を試してください。ログインの有効期限切れや未ログインの場合は、通常、ユーザーが再認証するだけで解決します。ほとんどのプロバイダーは、修正方法やコマンドを示しています。

• AWS SSO：Failed to refresh cached SSO credentials. Please refresh SSO login. → aws sso login
• AWS の一時的な認証情報：ExpiredToken: The security token included in the request is expired → セッションまたはキーを更新します
• Azure：az login を再実行します
• GCP：gcloud auth application-default login を再実行します
• Pulumi Cloud（401／認証されていない）：pulumi login

修正方法を伝え、ユーザーに再試行してもらってください。エラーに修正方法が記載されていない場合（たとえば、単に Unable to locate credentials と表示される場合や、ログインの有効期限切れではなくアカウントまたはプロファイルが間違っている可能性があるアクセス拒否の場合）は、推測で対応しないでください。プロジェクトの認証方法（プロバイダー設定、アクティブなプロファイル、リンク済みの ESC 環境など）を確認し、それに応じて対処してください。

プロジェクトが認証情報を取得する場所の変更（ESC 環境の追加または切り替え、プロバイダー設定の編集）は、期限切れのセッションに対する反射的な修正ではなく、意図的な変更です。ユーザーが希望する場合に限り、以下のルールに従って実施してください。

名前を基準に既存の環境を選択しない

名前が関連しているように見えるからといって（*-aws-oidc、*-creds、*-workshop など）、環境を選択しないでください。名前が一致していても、それが適切な環境であることや、ユーザーの作業に属することを意味しません。

既存の環境を提案する前に、次の手順を実施してください。

1. pulumi env get <org>/<project>/<env> で環境を調査します。
2. 認証先が、ユーザーのリソースが実際に存在する場所と一致していることを確認します。OIDC の roleArn は特定の AWS アカウントを示します。別のアカウント（共有のワークショップ、講師のロール、別のチームなど）を指している場合、その環境は不適切です。使用すると、誤ったアカウントに対して操作が実行されるか、失敗します。
3. 候補の環境をユーザーに提示し、使用する前に、その環境がユーザー自身のものであり、適切であることを確認します。

環境のリンクによって操作で使われる認証情報が変わるため、先に確認する

pulumi config env add はスタック設定（Pulumi.<stack>.yaml）を編集し、Pulumi の操作で使用される認証情報を変更します。ユーザーの明示的な確認なしに実行してはいけません。また、確認を省略するために --yes を渡してはいけません。何が変更されるかをユーザーに伝え、判断してもらってください。

成功したと伝える前に検証する

環境をリンクした後、環境を開くか実行するまで、解決された認証情報の値が [unknown] と表示されることがよくあります。検証するまでは、エラーが解消した、または次の操作が成功すると断言しないでください。pulumi config を確認し、成功を伝える前に認証情報が想定するアカウントに解決されることを確認してください。

簡単なトラブルシューティング

• 「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 でスタックが一覧に表示されていることを確認します。
  • 環境がプロジェクト名／環境名の形式だけで参照されていることを確認します。
  • pulumi env get <org>/<project-name>/<environment-name> で対象の環境定義を取得します。
  • pulumiConfig キーが存在し、values キーの下にネストされていることを確認します。