【実務・中級編】Pulumi ESC（Environments, Secrets, and Configurations）完全ガイド：次世代シークレット・設定管理の全貌 – インフラ構成管理（IaC）活用バイブル

Pulumi ESC（Environments, Secrets, and Configurations）完全ガイド：次世代シークレット・設定管理の全貌

こんにちは。大規模クラウドインフラの自動化とSREを統括しているテックリードです。

これまで、私たちはIaCにおけるシークレット管理と環境変数（Configuration）のジレンマに頭を悩ませてきました。「`.env`ファイル地獄」「GitにうっかりコミットされたAPIキー」「CI/CDパイプラインごとにバラバラに散らばるシークレットストア」「環境（dev/staging/prod）をまたぐ複雑な設定の継承とオーバーライド」――。

これらに終止符を打つために登場したのが、Pulumi ESC（Environments, Secrets, and Configurations） です。

本記事では、Pulumi ESCの設計思想の深淵に触れ、外部IDP（OIDC）との安全な連携、環境間の継承、そして現場の生産性を極限まで高める実践的なワークフローと設定のベストプラクティスを余すところなく伝授します。

—

1. なぜ従来のシークレット管理・設定管理は破綻するのか？

多くのチームがAWS Secrets Manager、HashiCorp Vault、あるいはGitHub ActionsのSecretsを使っています。しかし、インフラストラクチャの規模が拡大するにつれて、次のような構造的な矛盾が生じます。

1. コンテキストの断絶: インフラコード（Pulumi/Terraform）とアプリケーション設定（YAML/JSON）、シークレットが別々の場所に存在し、統合的なプレビューが困難。
2. 静的なオーバーライドの限界: 「stagingはdevと9割同じだが、データベースのインスタンスサイズだけ変えたい」といった要件に対し、コードの重複や複雑な条件分岐が発生する。
3. 静的クレデンシャルのリスク: 長期有効なAWSのアクセスキーなどをCI/CDや開発者の手元に配る必要があり、漏洩リスクが常に伴う。

Pulumi ESCは、これらを「階層的な環境定義（Environment）」「動的なシークレットプロバイダ統合」「OIDCベースの短寿命クレデンシャル生成」という3つの柱で完全に解決します。

—

2. Pulumi ESCのアーキテクチャと基本概念

ESCは、Pulumiのインフラストラクチャとは独立して動作する「設定とシークレットのオーケストレーションレイヤー」です。

[ 外部IDP (GitHub/AWS OIDC) ]
│ (動的トークン交換)
▼
[ Pulumi ESC ] ─── (継承・合成) ───> dev / staging / prod
│
├── AWS Secrets Manager / Vault / 1Password
└── Pulumi IaC / App Runtime

ESCの最大の特徴は、「環境（Environment）」というYAMLファーストのドキュメントをベースに、複数のソースから設定やシークレットを安全にインポート・合成（Composition）できる点にあります。

—

3. 実践：セキュアで美しいESC環境定義ファイルのベストプラクティス

ここでは、`base`（共通設定）を定義し、それを継承・オーバーライドして `production` 環境を構築する実用的なYAML構成例を示します。

共通ベース環境: `base.yaml`

すべての環境の土台となる設定です。ここでは外部シークレットストアからの値の動的取得や、共通変数を定義します。

esc/environments/base.yaml
values:
# 共通のタグやリージョン定義
fn::config:
region: ap-northeast-1
environment: base

# AWS OIDCを用いた動的なロール引き受け (長期クレデンシャルを排除)
aws:
fn::open::aws-login:
oidc:
roleArn: arn:aws:iam::123456789012:role/PulumiESCExecutionRole
sessionName: pulumi-esc-base-session

# 外部シークレットマネージャー（例: AWS Secrets Manager）からの値の動的ロード
database:
# ESCが自動的に暗号化・マスク処理を行う
password:
fn::open::aws-secretsmanager:
secretId: “prod/db/master-password”
versionStage: “AWSCURRENT”
key: “password”

プロダクション環境: `production.yaml`

`base` を継承し、プロダクション固有の設定でオーバーライドします。

esc/environments/production.yaml
values:
# base環境をインポート（継承）

  • fn::import: base

# プロダクション固有の設定で上書き
fn::config:
environment: production
instanceType: t4g.xlarge # baseより強力なインスタンスを指定
replicaCount: 3

# プロダクション専用の追加シークレット
api:
stripeKey:
fn::open::aws-secretsmanager:
secretId: “prod/stripe/api-key”
key: “live_key”

この構成により、設定のDRY（Don’t Repeat Yourself）原則が完全に守られ、どの環境にどんな値が流し込まれているかがESCのCLIやUI上で一目瞭然になります。

—

4. 現場の生産性を爆発させるプロの実践テクニック

ここからは、日々の開発スピードを劇的に高め、チーム全体の運用負荷を下げるための実践的なノウハウを公開します。

1. 開発スピードを加速するESC CLIショートカット & 秘伝のエイリアス

開発中にシークレットや環境変数の解決結果を確認するためだけにCIを回すのは愚の骨頂です。手元のターミナルでESCの変数を爆速でプレビューするためのエイリアスを `.zshrc` や `.bashrc` に仕込みましょう。

Pulumi ESCの環境変数をローカルプロセスに一時注入して実行する神エイリアス
使用例: esc-run production npm run dev
alias esc-run=”pulumi esc run”

現在のESC環境の解決済みJSONを素早くダンプする
alias esc-dump=”pulumi esc open –show-secrets”

この `pulumi esc open` コマンドを使うことで、階層的に継承されたシークレットや環境変数が、最終的にどのような平文・暗号化ステータスになっているかを即座に確認できます。デバッグの効率が文字通り10倍になります。

2. チーム開発で絶対導入すべき「設定の共有化ルール」

複数人でインフラを触る際、「誰かのローカル環境にしか無い変数」が原因でデプロイが落ちる現象（いわゆる「私の環境では動く」問題）を防ぐため、以下のルールをチームに強制します。

  • ルールA: コード内にベタ書きのシークレット・環境変数を一切置かない

Pulumiの `Config` クラスで直接文字列を渡すのではなく、必ずESC環境を経由させます。

  • ルールB: 環境定義ファイル（YAML）はGitで完全にバージョン管理する

`pulumi/esc` リポジトリ（またはPulumi Cloudの組織内ストレージ）でYAMLを管理し、変更は必ずPull Request経由で行います。ESCの強力なLint機能とプレビューがレビューの質を高めます。

3. CI/CD（GitHub Actions）とのOIDC連携ワークフロー

長期的なAWSクレデンシャルをGitHub Actionsの Secrets に保存する時代は終わりました。Pulumi ESCとGitHub ActionsのOIDC（OpenID Connect）を連携させ、実行時のみ短寿命の権限を取得します。

.github/workflows/deploy.yml
name: Pulumi Deploy with ESC

on:
push:
branches: [ main ]

permissions:
id-token: Writers # OIDCトークンを発行するために必須
contents: read

jobs:
deploy:
runs-on: ubuntu-latest
steps:

  • name: Checkout Code

uses: actions/checkout@v4

# Pulumi CLIのセットアップ

  • name: Setup Pulumi

uses: pulumi/actions@v5

# Pulumi ESCを使って環境変数とシークレットを一時的にエクスポート

  • name: Login and Run via ESC

uses: pulumi/esc-action@v1
with:
environment: “my-org/production”
export-to-env: true # GitHub Actionsの環境変数に安全に展開

  • name: Run Pulumi Preview/Up

run: pulumi up –yes –stack production
env:
PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}

このワークフローには、AWSや外部サービスの永続的な認証情報が一切ハードコードされていないという美しさがあります。セキュリティ監査も一発でクリアできます。

—

5. Pulumiコード側でのESCデータの受け取り方

ESCでオーケストレーションされた設定とシークレットは、Pulumiのプログラム（TypeScript / Python / Go / C#）からシームレスに呼び出すことができます。

TypeScriptの例を見てみましょう。

import as pulumi from “@pulumi/pulumi”;
import as aws from “@pulumi/aws”;

// Pulumiのスタック設定から、現在関連付けられているESC環境名を取得
// （または直接ESC SDKを利用して環境変数をロード）
const config = new pulumi.Config();
const dbPassword = config.requireSecret(“database-password”);
const instanceType = config.require(“instanceType”);

// リソース構築への適用
const dbInstance = new aws.rds.Instance(“my-db”, {
instanceClass: instanceType,
password: dbPassword, // 自動的に暗号化ハンドリングされる
// …その他の設定
});

export const dbEndpoint = dbInstance.endpoint;

ESC側で `fn::open` や `fn::config` を通して整えられたデータは、Pulumiのシークレット型（`Output`）として安全に伝播し、ステートファイル内でも暗号化された状態で保持されます。

—

6. まとめ：次世代インフラ管理のスタンダードへ

Pulumi ESCは、単なる「設定ファイル置き場」ではありません。
「インフラストラクチャ、シークレット、アプリケーション設定の境界線を消し去り、セキュリティと開発生産性を高い次元で両立させるためのマストツール」です。

  • 静的シークレットの全廃（OIDCと動的プロバイダの活用）
  • DRYな設定管理（YAMLの継承とオーバーライド）
  • 開発者体験（DX）の向上（CLIによる即時プレビューとショートカット）

今日のインフラエンジニアリングにおいて、「セキュアであること」と「素早く動くこと」はトレードオフではありません。Pulumi ESCを使いこなし、あなたのチームのインフラ管理を次の次元へと引き上げてください。

スポンサーリンク
タイトルとURLをコピーしました