hcl-guide.com — Terraform / HCL 学習ガイド

サマリ

プロジェクト	hcl-guide.com (Terraform / HCL 学習ガイド)
公開 URL	https://hcl-guide.com/
用途	Terraform / HCL を実務粒度まで体系的に学べる日本語学習サイト（全 27 章）
構成	素 HTML/CSS + S3 (private) + CloudFront (OAC) + ACM (us-east-1) + Route 53
IaC	Terraform 二段構成（bootstrap = state バケット + DynamoDB lock / site = 配信リソース全部）
運用形態	terraform apply 一発で全リソース立ち上げ、コンテンツ更新は aws s3 sync + CloudFront invalidation
月額運用費	数百円〜千円台（CloudFront 配信 + Route53 zone + Terraform state 用 S3/DDB）

全体アーキテクチャ

構成図は drawio (AWS 公式アイコン v2026 系) で作成しています。下のビューアは .drawio ファイルを 直接レンダリングしています。zoom / pan / 編集ボタンが使えます。

ソース: /diagrams/hcl-guide/architecture.drawio （drawio で開けば編集可能）

A. 訪問者の閲覧フロー

1. DNS ― ドメイン hcl-guide.com を Route 53 hosted zone で管理。apex の A/AAAA を CloudFront alias に設定。
2. ACM (us-east-1) ― hcl-guide.com の証明書を発行・DNS 検証・自動更新。
3. CloudFront ― TLS 終端 + キャッシュ。Origin Access Control で S3 直アクセス禁止。
4. S3 (private) ― public/ 配下の HTML/CSS/JS を配置。Public Access Block 全 true、CloudFront 経由のみ参照可能。

B. コンテンツ構成（27 章）

セクション	パス	章数
GitHub × Terraform 運用	/github/	7 章
HCL 言語	/hcl/	9 章
AWS リソース	/aws/	11 章
Azure	/azure.html	Coming Soon
GCP	/gcp.html	Coming Soon

各章は素 HTML で記述。共通 CSS (assets/style.css) と簡易 JS (assets/app.js) で タブ切替や目次生成を実装し、ビルドツールやランタイム JS フレームワークは使っていません。

C. Terraform 二段構成 (bootstrap + site)

Terraform の鶏卵問題（state 保存先の S3 バケット自体を Terraform で作りたい）を回避するため、 構成を 2 段に分けています。

1. terraform/bootstrap/ ― state バケット（S3）と DynamoDB ロックテーブルを作る。 state はローカル管理 (terraform.tfstate)、prevent_destroy で誤削除を防止。
2. terraform/site/ ― ACM 証明書・S3・CloudFront・Route 53 alias・コンテンツアップロードまでを一気に作成。 state は bootstrap で作った S3 バケットに格納、DynamoDB Lock で並行 apply を防止。

初回 apply 時に ACM 証明書の DNS 検証で 5〜15 分待つことがある以外は、terraform apply 一発で完結します。

D. デプロイフロー

• 大規模な構成変更: terraform/site で terraform apply。ファイルも含めて Terraform 管理
• コンテンツの軽微な更新: aws s3 sync public/ s3://...bucket... --delete で高速反映（state は更新されない点に注意）
• キャッシュ無効化: aws cloudfront create-invalidation --paths "/*" でワイルドカード一括

採用判断のポイント

項目	採用	理由
フロント	素 HTML/CSS + Vanilla JS	学習コンテンツの可読性とロード速度を最優先。ビルド工程を入れない
ホスティング	S3 + CloudFront (OAC)	iigtn-platform / hojinka.com と同一パターンで運用統一
IaC 構成	Terraform bootstrap + site の 2 段	state の鶏卵問題を構造的に解決
state ロック	S3 backend + DynamoDB Lock	複数環境からの並行 apply 防止、最小コスト
destroy 安全性	prevent_destroy on bootstrap	state バケットを誤って消すと復旧不可なので構造的に防止
コンテンツ更新	S3 sync 直流し OK	軽微な更新は Terraform 経由しなくてよい設計

運用上の工夫

• 章構成は静的タブ: ランディング (index.html) で 5 タブ（GitHub/HCL/AWS/Azure/GCP）に分岐、JS は localStorage でアクティブタブ記憶のみ
• OAC の Bucket Policy 条件: AWS:SourceArn で CloudFront Distribution ARN を厳密一致させ、他 Distribution からの誤参照を防止
• destroy 順序: site → bootstrap の順。bootstrap は prevent_destroy を一旦外す必要があり、これが「本気で消すための儀式」になる

これからやる予定

• Azure リソース章（10 章程度）を追加
• GCP リソース章を追加
• 各章末に Terraform コード例の terraform fmt + terraform validate を CI で自動チェック
• GitHub Actions OIDC を入れて手動 apply から自動 apply に移行（現状はローカル apply のみ）

関連リンク

• 本番サイト hcl-guide.com
• ← Works 一覧へ戻る
• iigtn-platform 解説書（同じ S3+CF パターンの詳解）