From 94065a4fbcf05fa6a97f66882afe7474d8d8fbaa Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 22 Jul 2026 20:23:48 +0000 Subject: [PATCH] feat(P27): add Examples section to every module README (D-058) Each module README (10 primitives + 2 patterns) now has a ## Examples section before ## Versioning, referencing and excerpting the validated simple.yaml + complex.yaml (+ mysql.yaml for RDS) example contracts. The RDS README includes a Multi-engine variation subsection (D-059). ---ci--- project: acdl phase: 27 milestone: v1.7 status: execute ---/ci--- --- modules/l1/alb/README.md | 42 +++++++++++++++++ modules/l1/cloudfront/README.md | 40 ++++++++++++++++ modules/l1/ecr/README.md | 34 ++++++++++++++ modules/l1/ecs-cluster/README.md | 34 ++++++++++++++ modules/l1/ecs-service/README.md | 41 ++++++++++++++++ modules/l1/iam-role/README.md | 34 ++++++++++++++ modules/l1/rds/README.md | 75 ++++++++++++++++++++++++++++++ modules/l1/s3/README.md | 39 ++++++++++++++++ modules/l1/vpc/README.md | 38 +++++++++++++++ modules/l1/waf/README.md | 37 +++++++++++++++ modules/l2/microservice/README.md | 42 +++++++++++++++++ modules/l2/static-assets/README.md | 42 +++++++++++++++++ 12 files changed, 498 insertions(+) diff --git a/modules/l1/alb/README.md b/modules/l1/alb/README.md index 37e9b6f..d7677fd 100644 --- a/modules/l1/alb/README.md +++ b/modules/l1/alb/README.md @@ -64,6 +64,48 @@ The `target_group_arn` output is referenced by `ecs-service` as its - **WAF** — add `aws_wafv2_web_acl_association` for application-layer protection (SOC2 CC7.6, PCI-DSS 6.5, DORA ICT risk). - **Deregistration delay** — add `deregistration_delay` for graceful draining (SOC2 CC9.1 resilience). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: alb +environment: dev +inputs: + name: my-alb + subnets: subnet-aaa,subnet-bbb + security_group: sg-xxx + port: 80 + protocol: HTTP + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex ALB with HTTPS + ACM cert (requires a consumer-supplied domain) +uses: acdl/pipelines/deploy.yaml@v1.6 +module: alb +environment: dev +inputs: + name: my-production-alb + subnets: subnet-aaa,subnet-bbb + security_group: sg-xxx + port: 443 + protocol: HTTPS + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/cloudfront/README.md b/modules/l1/cloudfront/README.md index 8ace2b3..5991654 100644 --- a/modules/l1/cloudfront/README.md +++ b/modules/l1/cloudfront/README.md @@ -71,6 +71,46 @@ inside a module composition (see `modules/l2/static-assets`). - **Field-level encryption** — add field-level encryption for PII fields in POST bodies (HIPAA §164.312(a)(2)(iv), GDPR Art.32). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +# Simple CloudFront distribution (S3 origin, no WAF) +uses: acdl/pipelines/deploy.yaml@v1.6 +module: cloudfront +environment: dev +inputs: + bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex CloudFront with WAF + custom TTL + viewer protocol redirect +uses: acdl/pipelines/deploy.yaml@v1.6 +module: cloudfront +environment: dev +inputs: + bucket_regional_domain_name: my-bucket.s3.us-east-1.amazonaws.com + price_class: PriceClass_100 + viewer_protocol_policy: redirect-to-https + default_ttl: 3600 + max_ttl: 86400 + waf_web_acl_arn: arn:aws:wafv2:us-east-1:000000000000:webacl/my-waf + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/ecr/README.md b/modules/l1/ecr/README.md index 77eb847..64dd4b2 100644 --- a/modules/l1/ecr/README.md +++ b/modules/l1/ecr/README.md @@ -51,6 +51,40 @@ The `repository_url` output is used to build the `image` input for - **Lifecycle policy** — add `aws_ecr_lifecycle_policy` to enforce image retention / cleanup (GDPR Art.5(2) data minimization, SOC2 CC5.2). - **Access policy** — add a repository policy restricting pull/push to known roles (SOC2 CC6.1, HIPAA §164.308(a)(4)). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: ecr +environment: dev +inputs: + name: my-repo + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex ECR with lifecycle policy + image scanning +uses: acdl/pipelines/deploy.yaml@v1.6 +module: ecr +environment: dev +inputs: + name: my-production-repo + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/ecs-cluster/README.md b/modules/l1/ecs-cluster/README.md index 73c8247..7e5bc0b 100644 --- a/modules/l1/ecs-cluster/README.md +++ b/modules/l1/ecs-cluster/README.md @@ -49,6 +49,40 @@ The `cluster_arn` output is referenced by `ecs-service` as its - **CloudWatch Logs** — add a log group with retention policy for cluster-level audit logs (SOX, SOC2 CC7.2, HIPAA §164.312(b)). - **Encryption** — add `settings { name = "containerInsights", value = "enabled" }` and KMS-based encryption for container data (HIPAA §164.312(a)(2)(iv), GDPR Art.32). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: ecs-cluster +environment: dev +inputs: + name: my-cluster + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex ECS cluster with container insights +uses: acdl/pipelines/deploy.yaml@v1.6 +module: ecs-cluster +environment: dev +inputs: + name: my-production-cluster + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/ecs-service/README.md b/modules/l1/ecs-service/README.md index 7ec1a0d..d9fa1ca 100644 --- a/modules/l1/ecs-service/README.md +++ b/modules/l1/ecs-service/README.md @@ -71,6 +71,47 @@ provided. - **Deployment circuit breaker** — add `deployment_circuit_breaker` block for resilience (SOC2 CC9.1, DORA operational resilience). - **Health check** — add a `health_check` block to the target group (currently missing despite the contract schema having a healthcheck field). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: ecs-service +environment: dev +inputs: + name: my-service + region: us-east-1 + image: public.ecr.aws/docker/library/nginx:latest + port: 80 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex ECS service with env vars + health check +uses: acdl/pipelines/deploy.yaml@v1.6 +module: ecs-service +environment: dev +inputs: + name: my-production-service + region: us-east-1 + image: public.ecr.aws/docker/library/nginx:latest + port: 8080 + env: + LOG_LEVEL: info + ENVIRONMENT: production +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/iam-role/README.md b/modules/l1/iam-role/README.md index 91cc719..c28d5dc 100644 --- a/modules/l1/iam-role/README.md +++ b/modules/l1/iam-role/README.md @@ -57,6 +57,40 @@ into the Terraform `assume_role_policy` argument. The - **Access Analyzer** — add `aws_accessanalyzer_analyzer` to verify least-privilege (SOC2 CC6.1, GDPR Art.32). - **Role separation** — add a separate task role vs. execution role (SOC2 CC6.3 segregation of duties). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: iam-role +environment: dev +inputs: + name: my-task-role + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex IAM role with managed policies +uses: acdl/pipelines/deploy.yaml@v1.6 +module: iam-role +environment: dev +inputs: + name: my-production-task-role + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/rds/README.md b/modules/l1/rds/README.md index 75f7e75..cd1f976 100644 --- a/modules/l1/rds/README.md +++ b/modules/l1/rds/README.md @@ -87,6 +87,81 @@ as the regression baseline). - **Read replicas** — add `aws_db_instance` with `replicate_source_db` for read scaling and DR failover (SOC2 CC9.1, DORA operational resilience). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +# Simple RDS postgres instance +uses: acdl/pipelines/deploy.yaml@v1.6 +module: rds +environment: dev +inputs: + engine: postgres + engine_version: "16.4" + instance_class: db.t3.micro + allocated_storage: 20 + db_name: my_app_db + username: db_admin + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex RDS postgres with multi-AZ + encryption +uses: acdl/pipelines/deploy.yaml@v1.6 +module: rds +environment: dev +inputs: + engine: postgres + engine_version: "16.4" + instance_class: db.r6g.large + allocated_storage: 100 + db_name: my_production_db + username: db_admin + multi_az: true + storage_encrypted: true + region: us-east-1 +``` + +### Multi-engine variation + +RDS supports multiple database engines. The `engine` input selects the engine; +the `engine_version` must match. + +#### PostgreSQL + +[`examples/simple.yaml`](examples/simple.yaml) — postgres 16.4 + +#### MySQL + +[`examples/mysql.yaml`](examples/mysql.yaml) — mysql 8.4 + +```yaml +# RDS mysql variation +uses: acdl/pipelines/deploy.yaml@v1.6 +module: rds +environment: dev +inputs: + engine: mysql + engine_version: "8.4" + instance_class: db.t3.micro + allocated_storage: 20 + db_name: my_mysql_db + username: db_admin + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/s3/README.md b/modules/l1/s3/README.md index 0a65c4e..46cff13 100644 --- a/modules/l1/s3/README.md +++ b/modules/l1/s3/README.md @@ -56,6 +56,45 @@ pipeline as the regression baseline). - **Public access block** — add `aws_s3_bucket_public_access_block` to prevent data exfiltration (SOC2 CC6.1, GDPR Art.32). - **Lifecycle policy** — add `aws_s3_bucket_lifecycle_configuration` for retention enforcement (GDPR Art.5(2), HIPAA §164.530(j)). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: s3 +environment: dev +inputs: + bucket_name: my-simple-bucket + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: s3 +environment: dev +inputs: + bucket_name: my-production-bucket + region: us-east-1 +``` + +> **Note:** the s3 primitive's compliance extensions (Object Lock, access +> logging, public access block, lifecycle policy) are documented in the +> Compliance extension points section above but not yet wired as inputs. +> The complex example uses the same inputs as the simple example; +> compliance extensions are roadmap. + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/vpc/README.md b/modules/l1/vpc/README.md index 924049b..56c5020 100644 --- a/modules/l1/vpc/README.md +++ b/modules/l1/vpc/README.md @@ -60,6 +60,44 @@ modules reference `subnet_ids` for their network placement. - **Security groups** — add `aws_security_group` as a first-class sub-resource (currently missing; needed for all regulated deployments) (SOC2 CC6.6, PCI-DSS 1.2). - **Network ACLs** — add `aws_network_acl` for subnet-level segmentation (PCI-DSS 1.3). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +uses: acdl/pipelines/deploy.yaml@v1.6 +module: vpc +environment: dev +inputs: + cidr: 10.0.0.0/16 + azs: us-east-1a,us-east-1b + name: my-vpc + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex VPC with 3 AZs and a custom CIDR +uses: acdl/pipelines/deploy.yaml@v1.6 +module: vpc +environment: dev +inputs: + cidr: 10.50.0.0/16 + azs: us-east-1a,us-east-1b,us-east-1c + name: my-production-vpc + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l1/waf/README.md b/modules/l1/waf/README.md index b93baae..6cebb5f 100644 --- a/modules/l1/waf/README.md +++ b/modules/l1/waf/README.md @@ -60,6 +60,43 @@ composition (see `modules/l2/static-assets`). - **Logging** — enable WAF access logging to S3/CloudWatch/Kinesis for auditability (SOC2 CC7.2, DORA audit trail). +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment: + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +# Simple WAF with managed rules only +uses: acdl/pipelines/deploy.yaml@v1.6 +module: waf +environment: dev +inputs: + name: my-waf + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs: + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex WAF with rate limiting + geo blocking (custom rules) +uses: acdl/pipelines/deploy.yaml@v1.6 +module: waf +environment: dev +inputs: + name: my-production-waf + scope: cloudfront + default_action: allow + region: us-east-1 +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l2/microservice/README.md b/modules/l2/microservice/README.md index e007c66..6eaac3b 100644 --- a/modules/l2/microservice/README.md +++ b/modules/l2/microservice/README.md @@ -63,6 +63,48 @@ compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands: See each primitive's README for per-module compliance extension points. +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment (minimal Fargate, no ALB): + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +# Simple microservice deployment (minimal Fargate, no ALB) +uses: acdl/pipelines/deploy.yaml@v1.6 +module: microservice +environment: dev +inputs: + bucket_name: my-microservice-demo + region: us-east-1 + image: public.ecr.aws/docker/library/nginx:latest + port: 80 +``` + +### Complex + +A production deployment with optional inputs (ALB + env vars + health check): + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex microservice with ALB + env vars + health check +uses: acdl/pipelines/deploy.yaml@v1.6 +module: microservice +environment: dev +inputs: + bucket_name: my-production-microservice + region: us-east-1 + image: public.ecr.aws/docker/library/nginx:latest + port: 8080 + env: + LOG_LEVEL: info + ENVIRONMENT: production +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps diff --git a/modules/l2/static-assets/README.md b/modules/l2/static-assets/README.md index 647bf15..2606f28 100644 --- a/modules/l2/static-assets/README.md +++ b/modules/l2/static-assets/README.md @@ -93,6 +93,48 @@ milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands: See the per-primitive READMEs for the per-module compliance extension points. +## Examples + +Validated example contracts are in [`examples/`](examples/). The platform-test +pipeline validates them against `schemas/contract.schema.json`. + +### Simple + +A minimal deployment (S3 bucket only — no CloudFront/WAF): + +[`examples/simple.yaml`](examples/simple.yaml) +```yaml +# Simple static-assets deployment (S3 bucket only — no CloudFront/WAF) +# This is the simplest way to deploy a static site: just an S3 bucket. +uses: acdl/pipelines/deploy.yaml@v1.6 +module: static-assets +environment: dev +inputs: + bucket_name: my-static-site + region: us-east-1 +``` + +### Complex + +A production deployment with optional inputs (S3 + CloudFront + WAF): + +[`examples/complex.yaml`](examples/complex.yaml) +```yaml +# Complex static-assets deployment (S3 + CloudFront + WAF) +# The full production stack: S3 origin + CloudFront CDN edge + WAF protection. +uses: acdl/pipelines/deploy.yaml@v1.6 +module: static-assets +environment: dev +inputs: + bucket_name: my-production-static-site + region: us-east-1 + price_class: PriceClass_100 + viewer_protocol_policy: redirect-to-https + default_ttl: 3600 + max_ttl: 86400 + waf_enabled: true +``` + ## Versioning `1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps