Pulumi Automation API徹底解説：CLIの呪縛からの解放と、真のセルフサービス基盤の構築
インフラストラクチャをコード（IaC）で管理する時代は過ぎ去った。今や、インフラは「アプリケーションのライフサイクルに完全に組み込まれた動的なリソース」でなければならない。
TerraformのCLIやCDKTF、あるいはPulumi CLIをCI/CDパイプラインから呼び出すだけの構成に満足していないか？
「開発者がPRを投げて、Plan通して、Applyして…」というワークフローは、チケット駆動開発の亡霊であり、真のクラウドネイティブ・アジリティを殺している。
本稿では、Pulumiの真髄であり、多くのエンジニアがその存在を知りながらも踏み込んでいない領域——Pulumi Automation APIを解剖する。CLIというラッパーを完全に排除し、TypeScriptやPythonのランタイムから直接Pulumiのエンジンをインメモリでドライブする方法論、そしてそれを用いた「社内向けセルフサービス・インフラポータルの極限最適化実装」を叩き込む。
—
1. Automation APIの概要とユースケース：なぜCLIを捨て去るのか？
従来のIaCが抱える限界と、Automation APIの本質
通常のIaCツールは、CLIバイナリをサブプロセスとして起動し、標準入出力をパースしながらステートを同期する。このアプローチには致命的な欠点がある。
1. プロセス起動のオーバーヘッド: 大規模なスタックにおいて、CLIの起動と初期化コストがバカにならない。
2. エラーハンドリングの限界: 標準出力（stdout/stderr）の文字列パースによる例外処理は、堅牢なエンタープライズシステムでは悪夢でしかない。
3. 動的構成の構築困難さ: リクエストに応じてインフラのトポロジやシークレット、バックエンド設定を1秒ごとに変化させるようなメタ・オーケストレーションを行うには、CLIはあまりにも静的すぎる。
Automation APIは、PulumiのCLIをバイナリとしてではなく、ライブラリ（SDK）として直接プロセス内にインポートする。これにより、Pulumiエンジン、言語ランタイム、ステート管理バックエンドのすべてを、完全にプログラムの制御下に置くことができる。
圧倒的なユースケース
- マルチテナントSaaSの動的プロビジョニング: 顧客がサインアップした瞬間に、専用のAWS VPC、ECScluster、RDSインスタンスを数秒でコードベースから動的生成・アタッチする。
- カオスエンジニアリング＆テスト自動化: 統合テストのたびに一時的なインフラスタックを立ち上げ、テスト完了後にプログラムからミリ秒単位で完全に破棄（Destroy）する。
- セルフサービス・インフラポータルのコアエンジン: 開発者がJiraチケットを切る代わりに、社内ポータルのUIからポチった設定をそのままPulumiプログラムに流し込み、バックグラウンドで安全にデプロイを完結させる。
—
2. Node.js/Pythonプログラムから直接Pulumiのデプロイを制御する方法
ここでは、TypeScript（Node.js）を用いたAutomation APIの最も実践的な実装パターンを示す。単なる「スクリプトからの呼び出し」ではなく、インラインプログラム（Inline Program）と呼ばれる、ファイルすら必要としない動的スタック生成のコードを解説する。
実装例：インラインプログラムによる動的S3バケット生成
import as aws from “@pulumi/aws”;
import as pulumi from “@pulumi/pulumi”;
import { LocalWorkspace } from “@pulumi/pulumi/automation”;
async function deployInfrastructure(projectName: string, stackName: string, bucketTag: string) {
// 1. インラインプログラムの定義（ファイルに書き出さず、関数として記述）
const pulumiProgram = async () => {
// リソースの定義
const bucket = new aws.s3.Bucket(“my-automation-bucket”, {
bucketPrefix: `${projectName}-${stackName}-`,
tags: {
Environment: stackName,
ManagedBy: “AutomationAPI”,
CustomTag: bucketTag,
},
});
// 出力値の登録（Automation API側でキャッチ可能）
return {
bucketName: bucket.id,
bucketArn: bucket.arn,
};
};
// 2. ワークスペースの作成とスタックの初期化
// CLIがインストールされていないコンテナ環境でも、パッケージさえあれば動作する
const stack = await LocalWorkspace.createOrSelectStack({
projectName: projectName,
stackName: stackName,
program: pulumiProgram,
});
// 3. バックエンド設定とプロバイダープラグインの明示的ロード
await stack.workspace.setAllConfig({
“aws:region”: { value: “ap-northeast-1” },
});
console.log(“正在安装AWSプラグイン…”);
await stack.workspace.installPlugin(“aws”, “v6.0.0”);
console.log(“インフラストラクチャのプレビューとデプロイを実行中…”);
// 4. アップデート（Pulumi up相当）の実行とリアルタイムストリーミング
const upResult = await stack.up({
onOutput: (out) => console.log(`[Pulumi Engine]: ${out}`),
});
console.log(`デプロイ成功！ ステータス: ${upResult.summary.result}`);
return upResult.outputs;
}
// 実行エントリーポイント
deployInfrastructure(“enterprise-saas”, “staging”, “mission-critical”)
.then((outputs) => {
console.log(“Outputs:”, outputs);
})
.catch((err) => {
console.error(“デプロイメント失敗:”, err);
process.exit(1);
});
このコードの深淵なポイント
- ファイルI/Oの完全排除: `pulumiProgram`はクロージャとしてメモリ上に存在し、そのままPulumiの言語ランタイムにシリアライズされて渡される。ディスクI/Oが発生しないため、コンテナのストレージライフサイクルを汚さない。
- リアルタイム・オブザバビリティ: `onOutput`コールバックにより、エンジン内部のログを完全にキャプチャし、WebSocket等を通じてフロントエンドにライブストリーミングすることが容易に可能。
—
3. 社内向けインフラプロビジョニングWebアプリの構築例
Automation APIを実用的なシステムに昇華させるため、Fastify（Node.js）やFastAPI（Python）などのモダンなWebフレームワークと組み合わせた「社内セルフサービスポータル」の設計思想を解説する。
アーキテクチャ全体像
[開発者ブラウザ]
│ (HTTPS / JSON)
▼
[API Gateway / Web App (Node.js/Fastify)]
│
├─► [データベース (PostgreSQL + Prisma)] (スタックの状態管理、監査ログ)
│
└─► [Automation API エンジン]
│
├─► インメモリで Pulumi ランタイム起動
└─► Remote State (AWS S3 / Pulumi Service) と同期
並行実行制御と排他ロック（Concurreny & Locking）
インフラの自動化において最大の敵は「競合（Race Condition）」である。同じスタックに対して同時に二人の開発者がデプロイを走らせた場合、ステートファイルが破損するか、リソースの不整合が発生する。
Automation APIを用いる場合、Webアプリ層でアプリケーションレベルの分散ロック（Redis / Redlock等）を実装するか、データベースのトランザクション分離レベルを厳密に定義する必要がある。
import { LocalWorkspace } from “@pulumi/pulumi/automation”;
import Redis from “ioredis”;
const redis = new Redis();
async function acquireLock(stackName: string, ttlMs: number): Promise
const res = await redis.set(`lock:${stackName}`, “locked”, “PX”, ttlMs, “NX”);
return res === “OK”;
}
async function releaseLock(stackName: string) {
await redis.del(`lock:${stackName}`);
}
// セーフなデプロイメント・ラッパー
async function safeDeploy(stackName: string, action: () => Promise
const acquired = await acquireLock(stackName, 300000); // 5分間のロック
if (!acquired) {
throw new Error(`スタック ${stackName} は現在別のプロセスによってデプロイ中です。`);
}
try {
return await action();
} finally {
await releaseLock(stackName);
}
}
—
4. 運用コスト削減とガバナンス強化のポイント
Automation APIを本番環境へ投入するにあたり、SRE/インフラアーキテクトが絶対に担保しなければならない「ガバナンスとパフォーマンスの極意」を授ける。
A. ポリシー・アズ・コード（Policy as Code）の強制組み込み
CLIベースのOpa/Sentinel検証とは異なり、Automation APIでは、`stack.up()`を実行する直前、あるいはプログラムの定義フェーズにおいて、動的なバリデーションをコードレベルで強制できる。
// デプロイ前のポリシーチェックフック
function enforceGovernance(config: Record
if (config.environment === “production” && !config.enableEncryption) {
throw new Error(“ガバナンス違反: 本番環境では暗号化（enableEncryption）が必須です。”);
}
}
これにより、コンプライアンス違反のインフラがクラウドに一行たりとも記述される前に、アプリケーション層で弾き返すことができる。
B. メモリ消費とガベージコレクションの最適化
Automation APIを長期稼働するWebサーバー（Daemonプロセス）内で実行する場合、最大の懸念事項はメモリリークである。Pulumiの言語ランタイム（特にNode.jsプロセス）は、大量のスタック操作を行うとV8ヒープが肥大化しやすい。
- プロセス分離（Worker Threads / Child Processes）: 高負荷なデプロイメント処理は、メインのWebサーバープロセスとは別の、独立したWorkerプロセス（例: BullMQなどのジョブキューワーカー）にオフロードせよ。タスク完了後、プロセスごと破棄することで、メモリリークの芽を完全に断つ。
- プラグインキャッシュの共有: AWSやAzureなどのプロバイダープラグインは毎回ダウンロードするのではなく、コンテナイメージビルド時に事前配置（あるいは共有ボリューム上にキャッシュ）し、起動オーバーヘッドを極限まで削れ。
—
伝説的アーキテクトからの最終提言
Pulumi Automation APIは、単なる「APIラッパー」ではない。それは、「インフラストラクチャを完全にソフトウェアの支配下に置くための最終兵器」である。
CLIの制約に縛られ、シェルスクリプトの泥臭いエラーハンドリングに苦しむ時代は終わった。コードを書き、APIを叩き、インフラを意のままに伸縮させる。この領域に到達したエンジニアだけが、真のクラウドネイティブのスピードと美しさを手に入れることができる。
さあ、ターミナルを開き、`npm install @pulumi/pulumi/automation` を叩け。あなたの手で、究極のインフラ自動化エンジンを組み上げろ。