pulumi-overview

Pulumi

Pulumi は、仮想マシン、ストレージ、Kubernetes クラスター、データベースなど、あらゆるプロバイダーのクラウドインフラを作成、管理するためのツールです。コードを記述するか CLI コマンドを実行すると、Pulumi が変更内容をプレビューし、その後適用します。このスキルでは、単一の CLI コマンドからポリシーとスケジュールされたドリフト検出を備えたプロジェクトまで、Pulumi の利用方法を3つのレベルで説明します。タスクに合った最小のレベルから始めてください。

3つのレベル

レベル1は pulumi do です。プロジェクトファイルやプログラミング言語を使わず、あらゆるプロバイダーに対して直接 CRUD 操作を行う CLI です。レベル2は Python、TypeScript、Go、C#、Java の Pulumi プロジェクトです。複数の関連リソース、ループや条件分岐、再利用可能な抽象化、環境別のバリエーションが必要になった場合に使用します。レベル3では、プロジェクトに Pulumi Cloud を追加し、ESC の認証情報と構成、ポリシー、ホスト実行、ドリフト検出、スケジュール、監査を利用します。

レベル	種類	使用する場面
1	pulumi do	単一リソース、または複数ベンダーのブートストラップ
2	Pulumi プロジェクト（Python、TS、Go、C#、Java）	複数のリソース、抽象化、環境
3	ESC、ポリシー、デプロイ、ドリフト、スケジュール	ガバナンス、シークレット、スケジュール実行とホスト実行

ディレクトリに既存の Pulumi プロジェクトがない場合、単一のバケットを作成する依頼はレベル1のタスクです。そのためだけに新しいプロジェクトをスキャフォールディングしないでください。サブネットを備えた VPC と Kubernetes クラスターをプロビジョニングする依頼は、最初からレベル2です。既存のスタックで夜間のドリフト検出を設定する依頼はレベル3です。

別のツール（Terraform、CloudFormation、CDK、ARM、Bicep）から既存のインフラコードを変換する場合は、別の手順になります。レベルモデルとは関係なく、末尾の表に記載された移行スキルへ直接案内してください。

適切なレベルを選ぶには、ディレクトリに何があるかを把握する必要があります。ファイルシステムを確認できる場合は、確認してください。確認できない場合（エージェントのコンテキストが制限されている場合）は、Pulumi コマンドを実行する前に、ディレクトリに既存の Pulumi プロジェクトがあるかをユーザーに尋ねてください。確認のために Pulumi コマンドを実行しないでください。ログインが必要になるはずのコマンドを実行すると、ユーザーがすでに所有している可能性のあるアカウントとは別に、新しいエージェントアカウントがひそかにプロビジョニングされます。

---

レベル1：直接リソース操作に使う pulumi do

あらゆるプロバイダーに対する単発のリソース操作には pulumi do を使用します。例：Cloudflare DNS レコードの作成、バックアップ用の S3 バケットの作成、画像アップロード用の GCP ストレージバケットの作成、Azure 仮想マシンの起動、Datadog モニターの設定、Vercel デプロイのドメインの Cloudflare DNS への登録。プロジェクトファイル、ディレクトリ構成、プログラミング言語は必要ありません。

pulumi do はステートレスです。各コマンドは1回実行され、クラウドプロバイダーに対して直接操作します。create はリソースをプロビジョニングしてクラウド側の識別子を出力し、read、patch、delete はその識別子で指定したリソースに対して操作します。Pulumi のステートファイルには何も書き込まれないため、リソースグラフも、コマンド間で値を渡す ${...} の連携もありません。2つのリソースを連携させるには、一方のコマンドの出力を取得し、次のコマンドにリテラル値として渡します。

ディレクトリに Pulumi プロジェクト（Pulumi.yaml）がすでに存在する場合、そのプロジェクトが管理するリソースの変更に pulumi do を使用しないでください。変更はプログラムを通じて行います。

初回の呼び出しとサインアップ

標準的な呼び出し方は npx pulumi <command> です。Node.js がインストールされているマシンであれば、事前に Pulumi をセットアップしなくても実行できます。pulumi が PATH にある場合、npx のシムはそちらに処理を委ねます。そうでない場合は、npm レジストリからコマンドを実行します。サインアップが発生するコマンドを実行する前に CLI が使用可能か確認するには、npx pulumi version を実行してください。このコマンドは Pulumi Cloud に接続しません。リソース動詞（create、read、patch、delete、list）には、pulumi do でリソースのサポートが追加された CLI v3.243.0 以降が必要です。npx pulumi は最新のリリースを取得しますが、PATH 上の pulumi は古いバージョンの場合があるため、バージョンが新しいことを確認してください。

pulumi do は Pulumi の状態を書き込みませんが、Pulumi レジストリを通じてプロバイダーパッケージを解決するため、Pulumi Cloud に接続する場合があります。保存済みの認証情報がないエージェントのコンテキストでは、初回の pulumi do によってエフェメラルなエージェントアカウントが気づかないうちに作成され、取得用のバナーが表示されることがあります。

CLI は、新しいアカウントと取得用 URL を記した1行を stderr に出力します。その URL はユーザーがアカウントの所有権を取得する唯一の方法なので、すぐにユーザーに伝え、最終回答でもう一度伝えてください。URL を伝えずにセッションが終了すると、リソースがクラウド上に取り残されます。アクセストークンの有効期限は3日で、取得用 URL の有効期限は30日です。どちらも Pulumi Cloud が設定するため、バナーに表示された有効期限をそのまま伝えてください。

同じセッションでアカウント作成のバナーが複数回表示された場合、認証情報がキャッシュされていない可能性があります。エージェントの認証情報は /tmp/.pulumi/credentials.json に、取得用メタデータは /tmp/.pulumi/agent-claim.json に書き込まれますが、取得用 URL 自体はこれらのファイルには保存されず、バナーに表示されます。各バナーから URL を記録し、作業を続ける前に最新の URL を伝えてください。

認証に失敗した場合は、ユーザーに pulumi login を実行してもらってください。pulumi login --local への切り替えや PULUMI_CONFIG_PASSPHRASE の設定は、どちらもユーザーのセットアップを知らないうちに変更するため、絶対に行わないでください。

プロバイダーの認証情報は Pulumi Cloud の認証情報とは別です。pulumi do は、プロバイダーのネイティブ CLI が使用するものと同じ環境変数（AWS_PROFILE、CLOUDFLARE_API_TOKEN、GOOGLE_APPLICATION_CREDENTIALS）から認証情報を読み取ります。設定されていない場合は、クラウドに接続するコマンドを呼び出す前にユーザーに確認してください。プロバイダーの認可エラーでコマンドが失敗した場合は、そのプロバイダーで必要な認証情報や設定を調べ、原因を推測するのではなく、ユーザーに指定してもらってください。プロジェクト作成後は、ESC（Level 3）が認証情報を永続的に保持する場所になります。

コマンドの形式

以下に、S3 バケットを作成し、作成時に出力されたクラウド ID を使って読み取る2つの呼び出し例を示します。

npx pulumi do aws:s3:Bucket create --yes --bucket my-data
npx pulumi do aws:s3:Bucket read my-data

形式は次のとおりです。

pulumi do <pkg:mod:type> create [flags]
pulumi do <pkg:mod:type> read|patch|delete <id> [flags]
pulumi do <pkg:mod:type> list [flags]

• <pkg> はプロバイダーパッケージです（aws、azure-native、gcp、cloudflare、kubernetes など）。
• <mod> はパッケージ内のモジュールです（compute、storage、dns）。モジュールが index の場合は省略できます。たとえば、cloudflare:index/record:Record は cloudflare:Record として呼び出します。
• <type> はリソースの種類です（VirtualMachine、Bucket、Record）。
• <id> は既存リソースのクラウドプロバイダー ID で、create が id として出力する値です。create と list は位置引数を取りません。read、patch、delete はそれぞれ <id> を1つだけ取ります。
• [flags] はリソースのプロパティを設定します。または --input-file <file> を使ってボディファイルを渡します。フラグとファイルの組み合わせ方、およびファイルから指定する必要がある値については、「プロパティの入力」を参照してください。

選択する Pulumi の論理名はありません。CLI はリソースの種類から内部名を生成し、既存リソースはクラウド ID で指定します。

動詞

• create はリソースをプロビジョニングし、クラウドの id を含むプロパティを JSON で出力します。後でリソースを読み取ったり、パッチを適用したり、削除したりできるよう、その id を取得してください。対話形式ではない環境では --yes を渡してください。read と list では不要です。
• read <id> はプロバイダーからリソースの現在の状態を取得し、JSON で出力します。何も書き込みません。
• patch <id> はリソースの現在の入力を読み取り、フラグまたは --input-file で渡した最上位プロパティを重ね合わせて、リソースをその場で更新します。重ね合わせは浅い処理です。指定しなかったプロパティはそのまま維持されます。patch は更新のみを行い、リソースを置き換えることはできません。そのため、置き換えが必要な変更は、リソースを再作成せずに失敗します。コマンドではリソース ID を入力して確認する必要があります。対話形式ではない環境でこの確認を省略するには、--yes を渡してください。
• delete <id> はクラウドからリソースを削除します。これは取り消せません。実行する前に、対象のリソースについてユーザーから明示的な確認を得てください。--yes は、その確認を得た後にのみ使用し、対話形式ではない実行でデフォルトとして使わないでください。

pulumi do は、CRUD 以外に 2 つの操作もサポートします。pulumi do <pkg:mod:type> list [flags] は、リソースタイプの既存インスタンスを列挙しますが、一覧表示を実装しているタイプに限られます。ネイティブプロバイダーでは幅広くサポートされています。Terraform ブリッジプロバイダー（aws、azure、gcp）でもサポートされていますが、対応状況はリソースタイプによって異なるため、未対応のタイプではこの動詞は拒否されます。pulumi do <pkg:mod:function> [flags] は、プロバイダーがリソースとともに公開するステートレス関数を呼び出します。

プロパティの入力

プロパティは、プロパティごとのフラグ、ボディファイル、またはその両方から指定できます。フラグはボディの値に重ね合わせられます。フラグで設定できるのは最上位のスカラープロパティのみなので、ネストされた値や構造化された値（tags、ネストされたブロック）はボディファイルで指定する必要があります。ボディのデフォルト形式は PCL で、name = value のフラットな属性として記述します。YAML を使用するには --input yaml を渡してください（YAML コンバータープラグインが必要です）。

cat > bucket.pcl <<'EOF'
bucket = "my-data"
tags = {
  Environment = "dev"
}
EOF
npx pulumi do aws:s3:Bucket create --yes --input-file bucket.pcl

このセッションで初めて使うリソースのプロパティを作成する前に、npx pulumi package info <pkg> --module <mod> --resource <Type> を実行して、そのリソースに限定された入力と出力の説明を一覧表示してください。info で展開されないネスト型の定義を含む、機械可読なスキーマ全体が必要な場合に限り、npx pulumi package get-schema <pkg> を使用してください。大規模なプロバイダーでは数十 MB になるため、全体を読み込まないでください。プロパティ名はキャメルケースです（フラグではケバブケースになります）。名前を調べるには、モジュールとリソースを一覧表示するためにモジュールを指定せずに npx pulumi package info <pkg> を実行するか、カタログ（https://www.pulumi.com/registry/）を参照してください。

リソースの接続

pulumi do は状態を保持せず、リソースグラフもないため、コマンド間で ${...} 参照構文は使えません。あるリソースの出力を別のリソースに渡すには、最初のコマンドの JSON 出力からフィールドを読み取り、次のコマンドにリテラルのフラグとして渡してください。

# create prints JSON containing "id": "vpc-0abc123"
npx pulumi do aws:ec2:Vpc create --yes --cidr-block 10.0.0.0/16

# pass that id to the subnet
npx pulumi do aws:ec2:Subnet create --yes --vpc-id vpc-0abc123 --cidr-block 10.0.1.0/24

同じ方法で、プロバイダーをまたいでリソースを接続できます。ここでは random プロバイダーの値を AWS リソース名に渡しています。これはグローバルに一意な名前を取得する一般的な方法です。

# RandomPet prints JSON containing "id": "artistic-bull"
npx pulumi do random:RandomPet create --yes

# use it in the bucket name
npx pulumi do aws:s3:Bucket create --yes --bucket assets-artistic-bull

コマンドの実行に必要な値がコマンドの連鎖から得られない場合（既存のリソース ID や API ゾーン ID など）は、プロバイダー関数、プロバイダーがサポートする場合は list、またはユーザーから取得してください。値を捏造しないでください。

出力

デフォルトでは、create、read、patch はそれぞれ、対象リソースの JSON オブジェクトを 1 つ stdout に書き込みます。呼び出すたびに終了コードを確認してください。

{
  "id":     "my-data",
  "bucket": "my-data",
  "arn":    "arn:aws:s3:::my-data"
}

リソースのプロパティは最上位にあり、クラウド識別子を格納する id フィールドと並びます。ネストされた outputs オブジェクトも urn もなく、渡した型トークンも出力に含まれません。list は代わりに {id, name} エントリの JSON 配列を書き込み、関数は宣言された形式の結果を書き込みます。

レベル 2 への移行

ワンショットコマンドでは対応しきれなくなったら、レベル 2 に移行します。pulumi do は Pulumi の状態を残さないため、作成したリソースは通常のクラウドリソースです。pulumi import を使ってプロジェクトに取り込みます。Pulumi プロジェクト内で pulumi import を実行し、各リソースの完全な型トークン、論理名、create が返したクラウドの id を指定します。インポートすると、リソースがスタックの状態に記録され、デフォルトではプログラムコードが生成されます。

# the import type token is the full pkg:mod/type:Type form, not pulumi do's short aws:s3:Bucket
npx pulumi import aws:s3/bucket:Bucket assets my-data

生成されたコードをプログラムに移し、以降は pulumi do ではなく、プログラムでリソースを管理します。複数のリソースを一度に取り込むには、まとめて --file に渡します。

---

レベル 2：インフラストラクチャをコードで完全に管理

レベル 2 は Pulumi プロジェクトです。Python、TypeScript、Go、C#、Java で、関連するリソースとその依存関係を記述します。複数の関連リソース、ループや条件分岐、再利用可能な抽象化、環境ごとのバリエーションを扱う場合は、ここから始めます。レベル 1 のアドホックな作業が、数回の CLI 呼び出しで扱える範囲を超えた場合にも適したレベルです。既存のコードベースがある場合は、その言語に合わせます。特に指定がなければ TypeScript を使用します。

複雑なプログラムを書く前に、必ずスキル pulumi-best-practices を使用してください。このスキルでは、Output<T> と apply() の使い方、出力を入力として直接渡す方法、コンポーネントの構成と親子関係、シークレットの適切な取り扱い、安全なリファクタリングでの aliases の使用方法を説明します。

プロジェクトの初期設定

プロジェクトを始める最も手早い方法はテンプレートを使うことですが、必要に応じて手動でひな形を作成することもできます。

npx pulumi new aws-typescript
npx pulumi new gcp-go

テンプレートは、作業ディレクトリ、Pulumi.yaml、初期スタック、言語のパッケージマニフェスト、スタータープログラムをセットアップします。npx pulumi template list でカタログ全体を確認するか、npx pulumi template list --name <filter> で名前を指定して絞り込めます。

基本的なライフサイクル

ライフサイクルのコマンドは、どの言語でも同じように使えます。

npx pulumi preview      # show what would change
npx pulumi up           # apply
npx pulumi refresh      # reconcile state with cloud reality

up の前に必ず preview を実行してください。変更内容を確認でき、費用もかかりません。

pulumi destroy はスタック内のすべてのリソースを削除します。Pulumi のドキュメントでは「一般に元に戻せない」と説明されています。スタック名についてユーザーから明示的な確認を得ずに、決して実行しないでください。

スタックと設定

スタックはプロジェクトの独立したインスタンスです。一般的なパターンは、dev、staging、prod という名前で環境ごとにスタックを作成することです。

npx pulumi stack init dev
npx pulumi stack select prod

npx pulumi config set aws:region us-west-2
npx pulumi config set --secret dbPassword "..."

プログラム内では、SDK の Config オブジェクトを使って設定値を読み取ります。操作名は言語によって異なるため、https://www.pulumi.com/docs/iac/concepts/config/#code の言語別の例を参照してください。Output<T>／apply() の使い方や、シークレットを適切に扱うための全般的な方法については、スキル pulumi-best-practices を使用してください。

スタックが操作するのは、状態で追跡されているリソースだけです。そのため、プログラムからリソースを削除すると、pulumi up によってクラウドからも削除されます。失うわけにはいかないリソースには、protect: true を設定してください。

IaC のリファレンス全体については、https://www.pulumi.com/docs/iac/ を参照してください。

---

レベル 3：ガバナンスと運用

レベル 3 では、状態管理以外にも Pulumi Cloud を活用します。ESC は、プロジェクトが利用するすべてのプロバイダーの認証情報を保持し、実行環境やシェルに提供します。ポリシー適用、ホステッド実行、ドリフト検出、スケジュールされた操作、監査も利用できます。

ESC：環境、シークレット、設定

ESC 環境では、クラウドのシークレットマネージャー、OIDC で発行される認証情報、その他の ESC 環境からシークレットと設定を組み合わせ、プログラムやスタックが利用する単一の解決済みバンドルを作成します。

npx pulumi env init my_org/aws/prod
npx pulumi env set my_org/aws/prod aws.region us-west-2
npx pulumi env open my_org/aws/prod
npx pulumi env run my_org/aws/prod -- aws s3 ls

プロバイダーが対応している場合は、環境 YAML に静的キーを記述するのではなく、OIDC を通じてクラウド認証情報を発行してください。 OIDC の信頼ポリシー、IdP の登録、ローテーションのパターンについては pulumi-esc に記載されています。ESC YAML を手作業で作成するのではなく、スキル pulumi-esc を使用してください。

env open は有効な認証情報を解決して出力するため、その出力をログやトランスクリプトに記録しないようにしてください。認証情報を出力せず、子プロセスに注入する env run -- <command> を優先してください。

ポリシー

Pulumi Policies は、プレビュー時と更新時にリソースグラフに対してポリシーパックを実行します。ポリシーによってデプロイを拒否したり、承認を必須にしたり、検出事項をリソースに注釈として付けたりできます。適用はクラウド API を呼び出す前に行われます。

npx pulumi policy new aws-typescript          # scaffold a pack from a policy template
npx pulumi policy publish my_org              # the pack name comes from PulumiPolicy.yaml
npx pulumi policy enable my_org/<pack-name> latest --policy-group production

ポリシーは、プログラムで使用するものと同じ TypeScript または Python で記述します。

デプロイ

Pulumi Deployments は、ローカルマシンではなく Pulumi が管理するインフラストラクチャ上で pulumi up、preview、destroy を実行します。独自のランナーを維持せずに CI を行う場合や、サーバー側で実行する必要がある操作に利用します。

npx pulumi deployment run update --stack my_org/proj/prod

対象のスタックはあらかじめ存在している必要があります。誤った --stack の値を指定すると、失敗するのではなく、新しいスタックの作成を促される場合があります。

ドリフト検出とスケジュールされた操作

ドリフト検出では、スタックの状態をクラウドと比較し、差異が生じた項目を報告します。単発でローカル確認するには、プレビュー専用モードでリフレッシュを実行します。Pulumi Cloud では cron に基づいて操作をスケジュールできます（時刻は UTC）。専用のドリフト種別も用意されています。

# Ad-hoc local drift check
npx pulumi refresh --preview-only

# Scheduled drift detection (detection only)
npx pulumi stack schedule new --kind drift --cron "0 0 * * *"

# Scheduled secret rotation for an ESC environment
npx pulumi env schedule new my_org/aws/prod --cron "0 0 1 * *"

スケジュールはセッション終了後も実行され続ける自動化です。作成前に、操作、頻度、スタックをユーザーに確認してください。人の介在なしに動作する種別は 2 つあります。--kind drift --auto-remediate は検出したドリフトに対して pulumi up を実行し、--kind ttl は指定した時刻にスタックを破棄します。ユーザーが修復を求めていない限り、検出のみをデフォルトにしてください。

さらに読む

• ESC：https://www.pulumi.com/docs/esc/
• Pulumi Policies：https://www.pulumi.com/docs/insights/policy/
• Deployments：https://www.pulumi.com/docs/pulumi-cloud/deployments/
• ドリフト検出：https://www.pulumi.com/docs/pulumi-cloud/deployments/drift/

---

リファレンス

CLI フラグ、コマンドの形式、リソースのプロパティが不明な場合は、推測せずに調べてください。npx pulumi <command> --help では、CLI 自体のすべてのフラグとサブコマンドを確認できます。完全なリファレンス、プロバイダーカタログ、概念ドキュメントは https://www.pulumi.com/docs にあります。

---

専門スキルへの振り分け

作業が別のスキルで詳しく扱われる領域に進んだら、内容を独自に作り直すのではなく、そのスキルに引き継いでください。

スキル	読み込むタイミング
pulumi-best-practices	複雑な Level 2 プログラムを作成するとき
pulumi-component	ComponentResource 抽象化をパッケージ化または利用するとき
pulumi-esc	ESC 環境、OIDC 信頼ポリシー、ローテーションを定義するとき
pulumi-automation-api	Pulumi を別のプログラム（IDP、カスタム CI）に組み込むとき
provider-upgrade	意図しない変更を避けながら、スタック内のプロバイダーパッケージのバージョンをアップグレードするとき
package-usage	組織内のどのスタックで、どのバージョンのパッケージが使われているかを監査するとき
pulumi-context-api	組織全体のインフラストラクチャグラフにおける関係性や影響分析について質問するとき
pulumi-terraform-to-pulumi、pulumi-cdk-to-pulumi、cloudformation-to-pulumi、pulumi-arm-to-pulumi	これらのツールから移行するとき

エージェントが参照できるのは、ユーザーがインストールしたスキルだけです。そのため、参照先のスキルが存在しない場合があります。pulumi-best-practices、pulumi-component、pulumi-esc、pulumi-automation-api、provider-upgrade、package-usage、pulumi-context-api は、このスキルと同じ pulumi プラグインに含まれているため、このスキルが利用可能であれば使用できます。移行スキルは pulumi-migration プラグインから個別にインストールするため、存在しない場合があります。参照先のスキルが利用可能なら読み込んでください。利用できない場合も、そこで止まったり、その状況をエラーとして扱ったりせず、このスキルのガイダンスと https://www.pulumi.com/docs のドキュメントに沿って続け、作業を詳しく扱うスキルまたはプラグインをユーザーに伝えてください。