Pulumi Automation API

このスキルを使用する場合

以下の場合にこのスキルを実行してください:

• 複数の Pulumi スタック全体でデプロイメントをオーケストレーションする
• カスタムアプリケーションに Pulumi オペレーションを組み込む
• セルフサービスインフラストラクチャプラットフォームを構築する
• 脆弱な Bash/Makefile オーケストレーションスクリプトを置き換える
• インフラストラクチャ管理用のカスタム CLI を作成する
• インフラストラクチャをプロビジョニングする Web アプリケーションを構築する

Automation API とは

Automation API は Pulumi オペレーションへのプログラムによるアクセスを提供します。CLI から pulumi up を実行する代わりに、同じオペレーションを実行するコード内の関数を呼び出します。

import * as automation from "@pulumi/pulumi/automation";

// スタックを作成または選択
const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    projectName: "my-project",
    program: async () => {
        // Pulumi プログラムをここに記述
    },
});

// pulumi up をプログラムで実行
const upResult = await stack.up({ onOutput: console.log });
console.log(`Update summary: ${JSON.stringify(upResult.summary)}`);

Automation API を使用する場合

良いユースケース

マルチスタックオーケストレーション:

インフラストラクチャを複数の焦点を絞ったプロジェクトに分割する場合、Automation API はスタック全体のオペレーションをオーケストレーションすることで、追加された複雑さを相殺するのに役立ちます:

infrastructure → platform → application
     ↓              ↓            ↓
   (VPC)      (Kubernetes)   (Services)

Automation API は手動介入なしに正確なシーケンシングを保証します。

セルフサービスプラットフォーム:

開発者が Pulumi を学ぶことなくインフラストラクチャをリクエストできる内部ツールを構築する:

• 環境プロビジョニング用の Web ポータル
• リソースを作成/破棄する Slack ボット
• 組織に合わせたカスタム CLI

組み込みインフラストラクチャ:

独自のインフラストラクチャをプロビジョニングするアプリケーション:

• テナントごとにリソースを作成する SaaS プラットフォーム
• テスト環境をスピンアップするテストフレームワーク
• 動的なインフラストラクチャニーズを持つ CI/CD システム

脆弱なスクリプトを置き換える:

複数の pulumi コマンドを結合する Bash スクリプトまたは Makefile がある場合、Automation API は以下を提供します:

• 適切なエラーハンドリング
• 型安全性
• 出力へのプログラムによるアクセス

使用しない場合

• 標準的なデプロイメントニーズを持つ単一プロジェクト
• オペレーションのプログラムによる制御が不要な場合

アーキテクチャの選択

ローカルソースとインラインソース

ローカルソース - 別のファイルにある Pulumi プログラム:

const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    workDir: "./infrastructure",  // 既存の Pulumi プロジェクトを指す
});

使用する場合:

• 異なるチームがオーケストレーターと Pulumi プログラムをメンテナンスする
• Pulumi プログラムが既に存在する
• 独立したバージョン管理とリリースサイクルが必要
• プラットフォームチームがアプリケーションチームのインフラストラクチャをオーケストレーションする

インラインソース - オーケストレーターに組み込まれた Pulumi プログラム:

import * as aws from "@pulumi/aws";

const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    projectName: "my-project",
    program: async () => {
        const bucket = new aws.s3.Bucket("my-bucket");
        return { bucketName: bucket.id };
    },
});

使用する場合:

• 単一チームがすべてをオーナーシップする
• オーケストレーションとインフラストラクチャ間のタイトなカップリングが望まれる
• コンパイル済みバイナリとして配布する (ソースファイルは不要)
• よりシンプルなデプロイメント成果物

言語の独立性

Automation API プログラムは、オーケストレーションする Pulumi プログラムと異なる言語を使用できます:

Orchestrator (Go) → manages → Pulumi Program (TypeScript)

これにより、プラットフォームチームが自分たちの好適言語を使用できる一方、アプリケーションチームは自分たちの言語を使用できます。

一般的なパターン

マルチスタックオーケストレーション

依存関係の順序で複数のスタックをデプロイする:

import * as automation from "@pulumi/pulumi/automation";

async function deploy() {
    const stacks = [
        { name: "infrastructure", dir: "./infra" },
        { name: "platform", dir: "./platform" },
        { name: "application", dir: "./app" },
    ];

    for (const stackInfo of stacks) {
        console.log(`Deploying ${stackInfo.name}...`);

        const stack = await automation.LocalWorkspace.createOrSelectStack({
            stackName: "prod",
            workDir: stackInfo.dir,
        });

        await stack.up({ onOutput: console.log });
        console.log(`${stackInfo.name} deployed successfully`);
    }
}

async function destroy() {
    // 逆順で破棄
    const stacks = [
        { name: "application", dir: "./app" },
        { name: "platform", dir: "./platform" },
        { name: "infrastructure", dir: "./infra" },
    ];

    for (const stackInfo of stacks) {
        console.log(`Destroying ${stackInfo.name}...`);

        const stack = await automation.LocalWorkspace.selectStack({
            stackName: "prod",
            workDir: stackInfo.dir,
        });

        await stack.destroy({ onOutput: console.log });
    }
}

構成の受け渡し

プログラムでスタック構成を設定する:

const stack = await automation.LocalWorkspace.createOrSelectStack({
    stackName: "dev",
    workDir: "./infrastructure",
});

// 構成値を設定
await stack.setConfig("aws:region", { value: "us-west-2" });
await stack.setConfig("dbPassword", { value: "secret", secret: true });

// その後デプロイ
await stack.up();

出力の読み取り

デプロイ後にスタック出力にアクセスする:

const upResult = await stack.up();

// すべての出力を取得
const outputs = await stack.outputs();
console.log(`VPC ID: ${outputs["vpcId"].value}`);

// または up 結果から
console.log(`Outputs: ${JSON.stringify(upResult.outputs)}`);

エラーハンドリング

デプロイメント失敗を適切に処理する:

try {
    const result = await stack.up({ onOutput: console.log });

    if (result.summary.result === "failed") {
        console.error("Deployment failed");
        process.exit(1);
    }
} catch (error) {
    console.error(`Deployment error: ${error}`);
    throw error;
}

並列スタックオペレーション

スタックが独立している場合、並列でデプロイする:

const independentStacks = [
    { name: "service-a", dir: "./service-a" },
    { name: "service-b", dir: "./service-b" },
    { name: "service-c", dir: "./service-c" },
];

await Promise.all(independentStacks.map(async (stackInfo) => {
    const stack = await automation.LocalWorkspace.createOrSelectStack({
        stackName: "prod",
        workDir: stackInfo.dir,
    });
    return stack.up({ onOutput: (msg) => console.log(`[${stackInfo.name}] ${msg}`) });
}));

ベストプラクティス

構成をコードから分離する

構成をファイルまたは環境変数に外部化する:

import * as fs from "fs";

interface DeployConfig {
    stacks: Array<{ name: string; dir: string; }>;
    environment: string;
}

const config: DeployConfig = JSON.parse(
    fs.readFileSync("./deploy-config.json", "utf-8")
);

for (const stackInfo of config.stacks) {
    const stack = await automation.LocalWorkspace.createOrSelectStack({
        stackName: config.environment,
        workDir: stackInfo.dir,
    });
    await stack.up();
}

これにより、ソースコードを公開せずにコンパイル済みバイナリを配布できます。

長時間のオペレーションの出力をストリーム処理する

リアルタイムフィードバック用に onOutput コールバックを使用する:

await stack.up({
    onOutput: (message) => {
        process.stdout.write(message);
        // またはロギングシステム、websocket など に送信
    },
});

クイックリファレンス

シナリオ	アプローチ
既存の Pulumi プロジェクト	workDir を使用したローカルソース
新しい組み込みインフラストラクチャ	program 関数を使用したインラインソース
異なるチーム	独立性のためのローカルソース
コンパイル済みバイナリ配布	インラインソースまたはバンドルされたローカル
マルチスタック依存関係	順序でのシーケンシャルデプロイメント
独立したスタック	Promise.all を使用した並列デプロイメント

関連スキル

• pulumi-best-practices: Pulumi プログラムのコードレベルパターン

リファレンス

• https://www.pulumi.com/docs/using-pulumi/automation-api/
• https://www.pulumi.com/docs/using-pulumi/automation-api/concepts-terminology/
• https://www.pulumi.com/blog/iac-recommended-practices-using-automation-api/