title: “ADR-001 — Infrastructure tooling for the mdBook static site deployment” created: 2026-10-23 updated: 2026-10-23 type: adr status: accepted tags:

aws
certification
devops
iac
decision

ADR-001 — Infrastructure tooling for the mdBook static site deployment

Context

The bhu-docs mdBook static site (public/book/) must be deployed on AWS using an S3 + CloudFront + OAC + ACM architecture. This is a personal, low-traffic setup.

The decision at hand is which tool to use to provision the infrastructure — not the architecture itself (the three target resources are the same regardless of tool: one S3 bucket, one CloudFront distribution with Origin Access Control, one ACM certificate in us-east-1).

Key constraints and priorities:

Learning context: preparing for the AWS Certified Cloud Practitioner (CLF-C02). Pedagogical value matters.
Idempotence: the setup should be re-runnable without side effects.
Reproducibility: it must be easy to tear down and recreate the whole stack.
Maintainability for a solo, occasional operator.

Decision

Adopt a two-phase approach:

Phase 1 — AWS CLI (learning pass). Provision the three resources with linear, readable aws CLI commands, run step by step, to understand the actual API calls and their dependency order. Defensive code is explicitly out of scope in this phase (no “already exists?” checks, no retries, no error handling) — it would add noise and hide the very sequence we want to learn.
Phase 2 — AWS CDK (production pass). Once the mechanics are understood, rebuild the infrastructure cleanly with the AWS CDK. This phase owns idempotence, clean teardown (cdk destroy), and maintainability.

CDK was chosen over Terraform as the final tool primarily because its engine, CloudFormation, is part of the CLF-C02 exam scope, so the deployment doubles as exam revision. CloudFormation also manages state server-side (in the stack), so there is no local state file to safeguard.

Options Considered

Option A — AWS CLI (bash scripts)

Pros:
- Maximum transparency: each command maps directly to an AWS API call.
- Nothing extra to install (SSO-configured AWS CLI already available).
- Best option to understand what actually happens behind each resource.
Cons:
- Not idempotent by nature; re-running errors out or duplicates.
- No state, no clean teardown — requires a separate, hand-maintained teardown script (empty bucket before delete, disable CloudFront distribution before removal, ~15 min propagation wait).
- CloudFront + OAC + ACM is verbose (large JSON config, manual DNS validation).

Option B — Terraform

Pros:
- Idempotent by design (plan / apply).
- terraform destroy tears everything down in the correct order — strong fit for destroy/recreate.
- Large community, many copyable “S3 + CloudFront + OAC” examples.
- High transferable professional value (multi-cloud, widely used).
Cons:
- State management is the operator’s responsibility (terraform.tfstate must not be lost; remote S3 backend introduces a chicken-and-egg bootstrap).
- HCL is an additional language to learn.
- Out of scope for CLF-C02.

Option C — AWS CDK

Pros:
- 100% AWS-native; CloudFormation/CDK are in the CLF-C02 exam scope (revision + build).
- State managed by AWS inside the CloudFormation stack — no local state file.
- High-level constructs (L2/L3) pre-wire OAC, bucket policy, and the ACM↔CloudFront link, so far less code than CLI or Terraform.
- Can be written in a familiar language (TypeScript, Python, or Java).
Cons:
- Heaviest toolchain to install/understand (Node.js + CDK CLI + cdk bootstrap).
- Abstraction hides detail — worse for learning the raw mechanics than the CLI.
- CloudFormation rollback states can be confusing for beginners.

Consequences

Positive:

The CLI-first pass builds genuine understanding of the API-level steps and their dependencies, which transfers directly to CLF-C02 concepts.
The CDK endgame gives idempotence, one-command teardown/recreate, no local state to guard, and exam-relevant CloudFormation experience.

Negative / trade-offs:

Doing two passes costs more time than going straight to CDK.
The CLI pass is intentionally throwaway and not maintainable — that is accepted and by design.

Notes:

The ACM certificate for CloudFront must be created in us-east-1 (AWS constraint). The account already defaults to us-east-1, so this is transparent, but it is a classic detail a CLI pass must handle manually.

AWS Certification Notes