writing-infrastructure-code

Infrastructure as Code

コードベースの自動化ツールを使用して、クラウドインフラストラクチャをプロビジョニングおよび管理します。このスキルでは、Terraform/OpenTofu、Pulumi、AWS CDK におけるツールの選定、状態管理、モジュール設計、運用パターンについて説明します。

使用する場面

次の場合にこのスキルを使用します：

• クラウドインフラストラクチャ（コンピューティング、ネットワーク、データベース、ストレージ）をプロビジョニングするとき
• 手動でのインフラストラクチャ管理から、コードベースのワークフローへ移行するとき
• 再利用可能なインフラストラクチャモジュールを設計するとき
• マルチクラウドまたはハイブリッドクラウドのデプロイを実装するとき
• 状態管理とドリフト検出のパターンを確立するとき
• インフラストラクチャのプロビジョニングを CI/CD パイプラインに統合するとき
• IaC ツールを評価するとき（Terraform と Pulumi、CDK の比較）

よくあるリクエスト：

• 「VPC のプロビジョニング用に Terraform モジュールを作成して」
• 「チームでの共同作業向けに、ロック機能付きのリモート状態を設定して」
• 「ユースケースに応じて Pulumi と Terraform を比較して」
• 「組み合わせ可能なインフラストラクチャモジュールを設計して」
• 「既存のインフラストラクチャにドリフト検出を実装して」

基本概念

Infrastructure as Code の基礎

主な原則：

1. 宣言型と命令型 - 望ましい状態を記述する（Terraform）か、プログラムでインフラストラクチャを構築します（Pulumi）
2. 冪等性 - 同じ入力から同じ出力が得られ、安全に再実行できます
3. バージョン管理 - インフラストラクチャの変更を Git で追跡します
4. 状態管理 - 実際のインフラストラクチャの状態を追跡します
5. モジュールの構成 - 再利用可能でバージョン管理されたインフラストラクチャコンポーネントを構成します

メリット：

• 再現性（同じコードで同じインフラストラクチャを構築）
• 監査可能性（Git の履歴ですべての変更を確認可能）
• 共同作業（インフラストラクチャの変更をコードレビュー）
• 自動化（CI/CD でインフラストラクチャをデプロイ）
• 災害復旧（コードから再構築）

ツール選定のフレームワーク

チーム構成とクラウド戦略に基づいて IaC ツールを選択します。

Terraform/OpenTofu - 宣言型、HCL ベース

• マルチクラウドおよびハイブリッドクラウドのデプロイ
• 運用／SRE チームが宣言型アプローチを好む場合
• 最大規模のプロバイダーエコシステム（AWS、GCP、Azure、3000 以上のプロバイダー）
• 成熟したモジュールレジストリとコミュニティ

Pulumi - 命令型、プログラミング言語ベース

• TypeScript/Python/Go に精通した開発者中心のチーム
• 複雑なロジックにプログラミングの構文（ループ、条件分岐、関数）が必要な場合
• 使い慣れたテストフレームワークを使ったネイティブな単体テスト
• 強い型付けと IDE サポート

AWS CDK - AWS ネイティブ、プログラミング言語ベース

• AWS のみのインフラストラクチャ
• AWS サービスとの緊密な統合
• L1/L2/L3 コンストラクトの抽象化
• 内部では CloudFormation を使用

判断フローチャート：

Multi-cloud required?
├─ YES → Team composition?
│  ├─ Ops/SRE focused → Terraform/OpenTofu
│  └─ Developer focused → Pulumi
└─ NO → AWS only?
   ├─ YES → Language preference?
   │  ├─ HCL/declarative → Terraform
   │  ├─ TypeScript/Python → AWS CDK
   │  └─ YAML/simple → CloudFormation
   └─ NO → GCP/Azure only?
      └─ Terraform or Pulumi

状態管理アーキテクチャ

ロック機能付きのリモート状態によって、チームでの共同作業が可能になります。

バックエンドの選択：

クラウドプロバイダー	推奨バックエンド	ロック機構
AWS	S3 + DynamoDB	DynamoDB テーブル
GCP	Google Cloud Storage	ネイティブ
Azure	Azure Blob Storage	リースベース
マルチクラウド	Terraform Cloud/Enterprise	組み込み
Pulumi	Pulumi Service	組み込み

状態の分離戦略：

1. ディレクトリによる分離（ほとんどのチームに推奨）

   • 環境ごとにディレクトリを分けます（prod/、staging/、dev/）
   • 状態ファイルを完全に分離します
   • 環境間で混在するリスクがありません

2. ワークスペース

   • 単一のコードベースで複数の環境を管理します
   • 状態バックエンドを共有し、環境ごとに名前空間を分けます
   • リスク：誤って別の環境に対して操作する可能性があります

3. 階層化アーキテクチャ

   • ネットワーク、コンピューティング、データの各レイヤーで状態ファイルを分けます
   • 影響範囲を縮小します
   • リモート状態のデータソースを介してレイヤー間を参照します

状態管理に関する重要なルール：

• チーム環境では、必ずリモート状態を使用してください
• 保存時の状態ファイルの暗号化を有効にしてください
• 状態ストレージのバージョン管理を有効にしてください
• 同時変更を防ぐため、状態のロックを使用してください
• 状態ファイルを Git にコミットしないでください
• 機密性の高い出力には sensitive = true を設定してください

モジュール設計パターン

合成可能なモジュール構造：

modules/
├── vpc/              # Network foundation
├── security-group/   # Reusable security group patterns
├── rds/              # Database with backups, encryption
├── ecs-cluster/      # Container orchestration base
├── ecs-service/      # Individual microservice
└── alb/              # Application load balancer

モジュールのバージョン管理：

• 本番環境ではモジュールのバージョンを固定します（version = "5.1.0"）
• 内部モジュールにはセマンティックバージョニングを使用します
• モジュールの更新は、まず本番以外の環境でテストします
• モジュールのリリースごとに CHANGELOG を管理します

モジュール設計の原則：

• 明確な入力契約（必須変数とオプション変数）
• ドキュメント化された出力（利用側が参照できる内容）
• 可能な限り適切なデフォルト値を設定
• 入力に対する検証ルール
• 使用方法を示す examples ディレクトリ

モジュールを作成する場合：

• リソースグループが3回以上再利用される
• 境界と責任が明確である
• インターフェース契約が安定している
• チームにモジュールを保守する余力がある

モノリシックな構成を維持する場合：

• 一度限りのインフラストラクチャ
• 迅速なプロトタイピング段階
• リソース間の結合度が高い
• 小規模なチームで、インフラストラクチャがシンプル

クイックリファレンス

Terraform/OpenTofu コマンド

# Initialize providers and backend
terraform init

# Plan changes (preview)
terraform plan

# Apply changes
terraform apply

# Destroy infrastructure
terraform destroy

# Format HCL files
terraform fmt

# Validate syntax
terraform validate

# Show state
terraform state list
terraform state show <resource>

# Import existing resources
terraform import <resource.name> <id>

# Workspace management
terraform workspace list
terraform workspace new staging
terraform workspace select prod

Pulumi コマンド

# Initialize new project
pulumi new aws-typescript

# Preview changes
pulumi preview

# Apply changes
pulumi up

# Destroy infrastructure
pulumi destroy

# Show stack outputs
pulumi stack output

# Manage stacks
pulumi stack ls
pulumi stack select prod

# Import existing resources
pulumi import <type> <name> <id>

# Export/import state
pulumi stack export > state.json
pulumi stack import < state.json

AWS CDK コマンド

# Initialize new app
cdk init app --language typescript

# Synthesize CloudFormation
cdk synth

# Preview changes
cdk diff

# Deploy stack
cdk deploy

# Destroy stack
cdk destroy

# Bootstrap account/region
cdk bootstrap

# List stacks
cdk list

よく使われるパターンのチェックリスト

インフラストラクチャのプロビジョニング：

• ロック機能を備えたリモートステートを設定済み
• ステートファイルの暗号化を有効化済み
• プロバイダーのバージョンを固定済み
• モジュールのバージョンを固定済み（本番環境）
• 変数に説明と型を設定済み
• 機密性の高い出力に sensitive を指定済み
• タグ付け戦略を実装済み
• コスト配分タグを適用済み

モジュール開発：

• 使用例を含む明確な README を用意済み
• 必須変数とオプション変数を文書化済み
• 出力を説明付きで文書化済み
• 重要な入力の検証ルールを設定済み
• 動作するコードを含む examples ディレクトリを用意済み
• モジュールの動作をテスト済み（Terratest/CDK アサーション）
• バージョン追跡用の CHANGELOG を用意済み
• セマンティックバージョニングに準拠済み

運用準備：

• ドリフト検出をスケジュール済み
• plan/apply 用の CI/CD パイプラインを用意済み
• ステートのバックアップ戦略を策定済み
• 災害復旧手順を文書化済み
• チームのアクセス制御を設定済み（IAM/RBAC）
• コスト見積もりを統合済み（Infracost）
• セキュリティスキャンを統合済み（Checkov/tfsec）
• ドキュメントを最新の状態に維持済み

詳細ドキュメント

包括的なパターンと実装の詳細については、以下を参照してください。

ツール固有のパターン：

• references/terraform-patterns.md - Terraform/OpenTofu のベストプラクティスと HCL パターン
• references/pulumi-patterns.md - TypeScript/Python/Go での Pulumi

アーキテクチャと設計：

• references/state-management.md - リモートステート、ロック、分離戦略
• references/module-design.md - 合成可能なモジュール、バージョン管理、レジストリ

運用：

• references/drift-detection.md - インフラストラクチャのドリフト検出と修正

動作例

IaC パターンを実演する実践的な実装例：

Terraform の例：

• examples/terraform/vpc-module/ - パブリック／プライベートサブネットを備えたマルチ AZ VPC
• examples/terraform/ecs-service/ - ALB とオートスケーリングを備えた ECS サービス
• examples/terraform/rds-cluster/ - バックアップと暗号化を備えた Aurora クラスター
• examples/terraform/state-backend/ - S3 + DynamoDB バックエンドのセットアップ

Pulumi の例：

• examples/pulumi/typescript/vpc/ - TypeScript の VPC コンポーネント
• examples/pulumi/python/ecs-service/ - Python の ECS サービス
• examples/pulumi/go/rds-cluster/ - Go の RDS クラスター
• examples/pulumi/testing/ - Pulumi プログラムの単体テスト

AWS CDK の例：

• examples/cdk/typescript/vpc-stack/ - L2 コンストラクトを使用した VPC
• examples/cdk/typescript/ecs-fargate/ - ALB を備えた Fargate サービス
• examples/cdk/typescript/pipeline-stack/ - 自己変更型 CDK パイプライン
• examples/cdk/testing/ - CDK アサーションとスナップショットテスト

ユーティリティスクリプト

自動検証と運用のためのツール：

• scripts/validate-terraform.sh - Terraform の fmt、validate、tflint
• scripts/cost-estimate.sh - コスト分析用の Infracost ラッパー
• scripts/drift-check.sh - スケジュールされたドリフト検出
• scripts/security-scan.sh - Checkov/tfsec によるセキュリティスキャン
• scripts/state-backup.sh - ステートファイルのバックアップ自動化
• scripts/module-release.sh - モジュールのバージョン管理と公開

他のスキルとの連携

デプロイパイプライン：

• building-ci-pipelines - CI/CD での terraform plan/apply を自動化します
• gitops-workflows - GitOps ベースのインフラストラクチャデプロイ

プラットフォームエンジニアリング：

• kubernetes-operations - EKS、GKE、AKS クラスターをプロビジョニングします
• platform-engineering - 内部開発者プラットフォームのインフラストラクチャ

セキュリティ：

• secret-management - Vault、External Secrets Operator をプロビジョニングします
• security-hardening - インフラストラクチャのセキュリティ制御を実装します
• compliance-frameworks - コンプライアンスのためのポリシー・アズ・コード

運用：

• observability - 監視インフラストラクチャ（Prometheus、Grafana）をプロビジョニングします
• disaster-recovery - インフラストラクチャの再構築手順
• cost-optimization - IaC を通じてコスト管理を実装します

データプラットフォーム：

• data-architecture - データレイク、データウェアハウスをプロビジョニングします
• streaming-data - Kafka、Kinesis のインフラストラクチャをプロビジョニングします

ベストプラクティス

開発ワークフロー：

1. フィーチャーブランチでインフラストラクチャコードを記述します
2. ローカルで terraform plan / pulumi preview を実行します
3. plan の出力を添えてプルリクエストを提出します
4. コードレビューではセキュリティ、コスト、影響範囲に重点を置きます
5. CI で自動テストとセキュリティスキャンを実行します
6. 承認され、CI が成功した後にのみ適用します
7. デプロイ後にドリフトを監視します

状態管理：

• 初日からリモート状態を使用します（チームでローカル状態を使用することは避けてください）
• 環境ごとに状態ファイルを分けます
• 同時変更を防ぐため、状態ロックを有効にします
• ロールバックできるよう、状態ストレージのバージョン管理を有効にします
• 状態を保存時に暗号化します（機密データが含まれています）
• 別の場所に状態を定期的にバックアップします

モジュール開発：

• まずモノリシックなコードから始め、パターンが見えてきたらモジュールを切り出します
• 再利用性を考慮して設計しますが、早すぎる抽象化は避けます
• すべての入力と出力をドキュメント化します
• examples/ ディレクトリに動作する例を用意します
• モジュール内でプロバイダーのバージョンを固定します
• 公開前にモジュールをテストします
• リリースにはセマンティックバージョニングを使用します

セキュリティ：

• 適用前に IaC のセキュリティ問題をスキャンします（Checkov、tfsec）
• コードにシークレットをコミットしないでください（シークレット参照を使用します）
• 機密性の高い出力には sensitive = true を設定します
• 最小権限の IAM ポリシーを実装します
• デフォルトですべてのリソースの暗号化を有効にします
• 内部モジュールにはプライベートモジュールレジストリを使用します

コスト管理：

• 変更を適用する前にコストを見積もります（Infracost）
• コスト配分のためにすべてのリソースにタグを付けます
• プルリクエストでコストへの影響を確認します
• ドリフトに対するコストアラートを設定します
• 使用状況に基づいてリソースのサイズを適正化します

運用上の卓越性：

• ドリフト検出を定期的にスケジュールします
• 災害復旧手順をドキュメント化します
• 一般的な運用のランブックを整備します
• 状態ファイルへのアクセスログを監視します
• 定期的にインフラストラクチャの再構築を実践します
• テストを行いながらプロバイダーのバージョンを最新に保ちます

よくある落とし穴

状態ファイルの問題：

• 状態の手動編集 - 直接編集ではなく、terraform state コマンドを使用します
• 状態ロックがない - 競合状態により状態が破損します
• チームでのローカル状態の使用 - チームメンバー間で状態に食い違いが生じます
• 大きな状態ファイル - レイヤーごとに複数の状態ファイルに分割します

モジュール設計：

• 過剰な抽象化 - 汎用的すぎて理解しにくくなります
• 抽象化不足 - あちこちでコードをコピーして貼り付けることになります
• バージョンの固定がない - 予期しない破壊的変更が発生します
• 例がない - ユーザーがモジュールの使い方を理解できません

運用：

• ドリフト検出がない - 手動変更が見過ごされます
• リソースの直接変更 - IaC を迂回するとドリフトが発生します
• ロールバック計画がない - apply の失敗から復旧できません
• plan の出力を無視する - apply 中に予想外のことが起きます

セキュリティ：

• コード内のシークレット - 認証情報がハードコードされています
• セキュリティスキャンがない - 本番環境に脆弱性が残ります
• 過度に許容的な IAM - 過剰な権限が付与されます
• 状態の暗号化がない - 機密データが漏えいします

トラブルシューティングガイド

状態ロックの問題：

terraform force-unlock <lock-id>  # Use only if certain no other process running

既存リソースのインポート：

terraform import aws_vpc.main vpc-12345678
pulumi import aws:ec2/vpc:Vpc main vpc-12345678

ドリフト検出：

terraform plan -detailed-exitcode  # Exit 2 = drift detected
pulumi preview --diff

ドリフトの詳細な修復方法については、references/drift-detection.md を参照してください。

状態の復旧：

# Terraform: Restore from S3 versioning
aws s3 cp s3://bucket/backup/terraform.tfstate terraform.tfstate

# Pulumi: Restore from checkpoint
pulumi stack export --version <timestamp> | pulumi stack import

関連スキル

クラウド固有の実装について：

• aws-patterns - AWS 固有のリソースパターン
• gcp-patterns - GCP 固有のリソースパターン
• azure-patterns - Azure 固有のリソースパターン

インフラストラクチャの運用について：

• kubernetes-operations - IaC を通じてプロビジョニングされた Kubernetes クラスターを管理します
• gitops-workflows - GitOps ベースのインフラストラクチャデプロイ
• platform-engineering - 社内開発者プラットフォーム

セキュリティとコンプライアンスについて：

• security-hardening - インフラストラクチャのセキュリティ制御
• secret-management - シークレットの注入とローテーション
• compliance-frameworks - コンプライアンス向けのポリシー・アズ・コード

デプロイの自動化について：

• building-ci-pipelines - インフラストラクチャコード向けの CI/CD
• deploying-applications - プロビジョニングされたインフラストラクチャへのアプリケーションのデプロイ

コストと可観測性について：

• cost-optimization - インフラストラクチャ向けの FinOps の実践
• observability - インフラストラクチャの健全性の監視