pulumi

Pulumi のベストプラクティス

AI エージェントと LLM 向けに設計された、Pulumi による Infrastructure as Code のパフォーマンスと信頼性に関する包括的なガイドです。8 つのカテゴリにわたる 46 個のルールが含まれており、影響度に基づいて優先順位が付けられています。自動リファクタリングやコード生成の指針として活用できます。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• Pulumi のインフラストラクチャコードを新しく作成するとき
• 再利用可能なコンポーネント抽象化を設計するとき
• シークレットや機密値を設定するとき
• スタックやスタック間参照を整理するとき
• インフラストラクチャ向けの CI/CD パイプラインを設定するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	状態管理とバックエンド	CRITICAL	pstate-
2	リソースグラフの最適化	CRITICAL	graph-
3	コンポーネント設計	HIGH	pcomp-
4	シークレットと設定	HIGH	secrets-
5	スタックの整理	MEDIUM-HIGH	stack-
6	リソースオプションとライフサイクル	MEDIUM	lifecycle-
7	テストと検証	MEDIUM	test-
8	自動化と CI/CD	LOW-MEDIUM	auto-

クイックリファレンス

1. 状態管理とバックエンド（CRITICAL）

• pstate-backend-selection - 本番スタックにはマネージドバックエンドを使用する
• pstate-checkpoint-skipping - 大規模スタックではチェックポイントのスキップを有効にする
• pstate-stack-size - スタック内のリソース数を 500 未満に保つ
• pstate-refresh-targeting - スタック全体ではなく、対象を指定してリフレッシュする
• pstate-export-import - 移行には状態のエクスポート／インポートを使用する
• pstate-import-existing - 管理を始める前に既存のリソースをインポートする

2. リソースグラフの最適化（CRITICAL）

• graph-parallel-resources - 最大限の並列処理ができるようにリソースを構成する
• graph-output-dependencies - 出力を使って実際の依存関係を表現する
• graph-explicit-depends - 外部依存関係にのみ dependsOn を使用する
• graph-avoid-apply-side-effects - apply 関数内での副作用を避ける
• graph-conditional-resources - リソースレベルで条件分岐を使用する
• graph-stack-references-minimal - スタック参照の階層を最小限にする

3. コンポーネント設計（HIGH）

• pcomp-component-resources - 再利用可能な抽象化には ComponentResource を使用する
• pcomp-parent-child - 子リソースに parent オプションを渡す
• pcomp-unique-naming - リソース名の一意性を確保するため、名前プレフィックスのパターンを使用する
• pcomp-register-outputs - コンポーネントの出力を明示的に登録する
• pcomp-multi-language - 複数の言語から利用できるようにコンポーネントを設計する
• pcomp-transformations - 横断的な関心事には transformations を使用する

4. シークレットと設定（HIGH）

• secrets-use-secret-config - 機密値にはシークレット設定を使用する
• secrets-avoid-state-exposure - 状態内でのシークレット漏えいを防ぐ
• secrets-external-providers - 本番環境では外部のシークレットマネージャーを使用する
• secrets-generate-random - random プロバイダーでシークレットを生成する
• secrets-provider-rotation - チームメンバーが離脱したらシークレットプロバイダーをローテーションする
• secrets-environment-isolation - 環境ごとにシークレットを分離する

5. スタックの整理（MEDIUM-HIGH）

• stack-separation-by-lifecycle - デプロイのライフサイクルごとにスタックを分ける
• stack-references-parameterized - スタック参照をパラメーター化する
• stack-output-minimal - 必要な出力のみをエクスポートする
• stack-naming-conventions - 一貫したスタック命名規則を使用する

6. リソースオプションとライフサイクル（MEDIUM）

• lifecycle-protect-stateful - ステートフルなリソースを保護する
• lifecycle-delete-before-replace - 一意制約がある場合は deleteBeforeReplace を使用する
• lifecycle-retain-on-delete - 共有リソースには retainOnDelete を使用する
• lifecycle-ignore-changes - 外部で管理されているプロパティには ignoreChanges を使用する
• lifecycle-replace-on-changes - 不変の依存関係には replaceOnChanges を使用する
• lifecycle-aliases - リソース名を安全に変更するためにエイリアスを使用する
• lifecycle-custom-timeouts - 長時間実行されるリソースにはカスタムタイムアウトを設定する

7. テストと検証（MEDIUM）

• test-unit-mocking - 高速な単体テストにはモックを使用します
• test-property-policies - プロパティテストにはポリシーをコードとして使用します
• test-integration-ephemeral - 統合テストには一時的なスタックを使用します
• test-preview-assertions - デプロイ前にプレビュー結果を検証します
• test-stack-reference-mocking - 単体テストではスタック参照をモックします

8. 自動化と CI/CD（LOW-MEDIUM）

• auto-automation-api-workflows - 複雑なワークフローには Automation API を使用します
• auto-inline-programs - 動的なインフラストラクチャにはインラインプログラムを使用します
• auto-ci-cd-preview - PR チェックでプレビューを実行します
• auto-deployments-api - GitOps には Pulumi Deployments を使用します
• auto-review-stacks - PR 環境にはレビュー用スタックを使用します
• auto-drift-detection - 本番環境ではドリフト検出を有効にします

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

完全版ドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。