refactor(modules): remove thin-composition layer; rewrite all module READMEs
The L2 thin-composition layer (composition.json + contract_resolver.py + contract schema + sample contracts) has been removed completely. The implementation was unsatisfactory and is deferred for a later redesign. - Delete: composition.json x2, contract_resolver.py, contracts/ x2, contract.schema.json - Patch: run_platform.sh now loads a pre-existing IR instance instead of resolving a contract (the downstream adapter/checkov/confidence/outbox pipeline is unchanged) - Prune: L2 entries removed from registry.json (L1 entries unchanged) - Rewrite: all 7 L1 module READMEs in plain language (no jargon), each with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning sections derived from interface.json - Add: 2 L2 placeholder READMEs noting the composition is under redesign - Add: modules-ir/README.md catalog index + README-TEMPLATE.md ---ci--- project: acdl phase: 17 milestone: v1.3 status: execute ---/ci---
This commit is contained in:
@@ -0,0 +1,48 @@
|
||||
# <module-name> — <plain-language description>
|
||||
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
One or two sentences describing what this module provisions, in plain
|
||||
language. No jargon. A reader should know after this paragraph whether
|
||||
this module is what they need.
|
||||
|
||||
## Resources
|
||||
|
||||
Terraform resources this module creates:
|
||||
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| `<name>` | `aws_<type>` | what it does |
|
||||
|
||||
## Inputs
|
||||
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `<name>` | string | yes | — | description |
|
||||
|
||||
## Outputs
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `<name>` | string | description |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
# A concrete snippet showing how to reference this module or what a
|
||||
# consumer writes to use it.
|
||||
```
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
Resources this module could be extended with for the future compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA). Not implemented yet — listed
|
||||
so the redesign can plan for them.
|
||||
|
||||
- **<area>** — <what could be added, e.g. KMS key for encryption>
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR
|
||||
bumps require a new registry entry (immutable publication); old entries
|
||||
enter a 12-month deprecation window.
|
||||
@@ -0,0 +1,51 @@
|
||||
# ACDL Modules
|
||||
|
||||
Reusable building blocks for cloud infrastructure. Each module is
|
||||
self-documented with a `README.md` following the
|
||||
[template](README-TEMPLATE.md).
|
||||
|
||||
## How the modules work
|
||||
|
||||
There are two kinds of module:
|
||||
|
||||
- **L1 primitives** — a single cloud resource or a small group of
|
||||
related resources (e.g. a VPC with subnets and routing). Each L1 has
|
||||
an `interface.json` declaring its inputs and outputs, and a `README.md`
|
||||
in plain language.
|
||||
- **L2 compositions** — a composition that references multiple L1s to
|
||||
deploy a complete stack (e.g. an ECS Fargate microservice). **The L2
|
||||
composition layer is being redesigned.** The previous implementation
|
||||
has been removed; a new mechanism will be designed in a later phase.
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) compiles a
|
||||
module instance to Terraform. Each module's README documents which
|
||||
Terraform resources it creates.
|
||||
|
||||
## L1 primitives
|
||||
|
||||
| Module | What it creates | README |
|
||||
|--------|----------------|--------|
|
||||
| `l1-s3` | `aws_s3_bucket` — a single S3 bucket | [README](l1/l1-s3/README.md) |
|
||||
| `l1-vpc` | `aws_vpc` + `aws_subnet` + `aws_route_table` + `aws_internet_gateway` — VPC with subnets and routing | [README](l1/l1-vpc/README.md) |
|
||||
| `l1-ecs-cluster` | `aws_ecs_cluster` — ECS Fargate cluster | [README](l1/l1-ecs-cluster/README.md) |
|
||||
| `l1-ecs-service` | `aws_ecs_task_definition` + `aws_ecs_service` — Fargate service with task definition | [README](l1/l1-ecs-service/README.md) |
|
||||
| `l1-iam-role` | `aws_iam_role` — IAM role with assume-role policy | [README](l1/l1-iam-role/README.md) |
|
||||
| `l1-alb` | `aws_lb` + `aws_lb_target_group` + `aws_lb_listener` — Application Load Balancer | [README](l1/l1-alb/README.md) |
|
||||
| `l1-ecr` | `aws_ecr_repository` — ECR container image repository | [README](l1/l1-ecr/README.md) |
|
||||
|
||||
## L2 compositions
|
||||
|
||||
| Module | What it references | README |
|
||||
|--------|--------------------|--------|
|
||||
| `l2-microservice` | 6 L1s (vpc, cluster, ecr, iam-role, alb, ecs-service) — **under redesign** | [README](l2/l2-microservice/README.md) |
|
||||
| `l2-static-asset` | 1 L1 (s3) — **under redesign** | [README](l2/l2-static-asset/README.md) |
|
||||
|
||||
## Registry
|
||||
|
||||
Module versions are tracked in `registry.json`. Only L1 entries are
|
||||
active; L2 entries have been pruned pending the composition redesign.
|
||||
|
||||
## Template
|
||||
|
||||
New modules should use [README-TEMPLATE.md](README-TEMPLATE.md) as
|
||||
their starting point.
|
||||
@@ -1,55 +1,70 @@
|
||||
# l1-alb — Application Load Balancer primitive (multi-resource L1)
|
||||
# l1-alb — Application Load Balancer (load balancer + target group + listener)
|
||||
|
||||
An L1 module for an Application Load Balancer (load balancer + target
|
||||
group + listener). Substrate-agnostic (the IR types are
|
||||
`aws:elbv2:loadbalancer`, `aws:elbv2:listener`, `aws:elbv2:targetgroup`,
|
||||
not Terraform resource types). This is a multi-resource L1: the
|
||||
interface declares the group's inputs/outputs plus a `resources` array
|
||||
listing the IR types it emits. The IR instance (Phase 14/15) will have
|
||||
multiple `resources` entries all with `module: "l1-alb@1.0.0"`.
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
An Application Load Balancer with a target group and a listener. This is
|
||||
a multi-resource module: it creates a load balancer, a target group, and
|
||||
a listener that forwards traffic to the target group. The target group
|
||||
is what `l1-ecs-service` registers its tasks with.
|
||||
|
||||
See `interface.json`: inputs `name` (string), `subnets` (string,
|
||||
comma-separated, ref to l1-vpc), `security_group` (string), `port`
|
||||
(number, default 80), `protocol` (string, default "HTTP"), `region`
|
||||
(string); outputs `lb_arn` (arn) + `listener_arn` (arn) +
|
||||
`target_group_arn` (arn); no NFRs.
|
||||
## Resources
|
||||
|
||||
The `resources` array lists the emitted IR types:
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| load_balancer | `aws_lb` | Application load balancer in the VPC subnets |
|
||||
| target_group | `aws_lb_target_group` | Target group for the ECS service tasks |
|
||||
| listener | `aws_lb_listener` | Listener forwarding the LB port to the target group |
|
||||
|
||||
- `aws:elbv2:loadbalancer` — application load balancer in the VPC
|
||||
subnets.
|
||||
- `aws:elbv2:targetgroup` — target group for the ECS service tasks.
|
||||
- `aws:elbv2:listener` — listener forwarding the LB port to the target
|
||||
group.
|
||||
## Inputs
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `name` | string | yes | — | Name tag for the load balancer and child resources |
|
||||
| `subnets` | string | yes | — | Comma-separated subnet ids (from `l1-vpc`) |
|
||||
| `security_group` | string | yes | — | Security group id for the load balancer |
|
||||
| `port` | number | no | 80 | Listener port |
|
||||
| `protocol` | string | no | `HTTP` | Listener protocol |
|
||||
| `region` | string | yes | — | AWS region the load balancer is created in |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates each
|
||||
emitted IR resource to Terraform:
|
||||
## Outputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:elbv2:loadbalancer` | `resource "aws_lb" "<id>" { ... }` |
|
||||
| `resource.inputs.name` | `name = <value>` arg |
|
||||
| `resource.inputs.subnets` | `subnets = [<value>]` arg (comma-split) |
|
||||
| `resource.inputs.security_group` | `security_groups = [<value>]` arg (comma-split) |
|
||||
| `resource.outputs.lb_arn` | `output "lb_arn" { value = aws_lb.<id>.id }` |
|
||||
| `resource.type = aws:elbv2:targetgroup` | `resource "aws_lb_target_group" "<id>" { ... }` |
|
||||
| `resource.inputs.port` | `port = <value>` arg |
|
||||
| `resource.inputs.protocol` | `protocol = <value>` arg |
|
||||
| `resource.outputs.target_group_arn` | `output "target_group_arn" { value = aws_lb_target_group.<id>.arn }` |
|
||||
| `resource.type = aws:elbv2:listener` | `resource "aws_lb_listener" "<id>" { ... }` |
|
||||
| `resource.inputs.lb_arn` | `load_balancer_arn = <value>` arg (identity) |
|
||||
| `resource.inputs.port` | `port = <value>` arg |
|
||||
| `resource.inputs.protocol` | `protocol = <value>` arg |
|
||||
| `resource.outputs.listener_arn` | `output "listener_arn" { value = aws_lb_listener.<id>.id }` |
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `lb_arn` | arn | The load balancer ARN |
|
||||
| `listener_arn` | arn | The listener ARN |
|
||||
| `target_group_arn` | arn | The target group ARN |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
## Usage
|
||||
|
||||
## Versioning (W3.D)
|
||||
```json
|
||||
{
|
||||
"id": "alb",
|
||||
"type": "aws:elbv2:loadbalancer",
|
||||
"module": "l1-alb@1.0.0",
|
||||
"inputs": {
|
||||
"name": "acdl-microservice",
|
||||
"subnets": "ref:vpc.subnet_ids",
|
||||
"security_group": "ref:roles.role_arn",
|
||||
"port": 8080,
|
||||
"protocol": "HTTP",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `target_group_arn` output is referenced by `l1-ecs-service` as its
|
||||
`lb_target_group_arn` input to wire the service to the ALB.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **TLS / HTTPS listener** — add `aws_acm_certificate` + `ssl_policy` + `certificate_arn` for encryption in transit (SOC2 CC6.1, PCI-DSS 4.1, HIPAA §164.312(e)(1), GDPR Art.32).
|
||||
- **Access logs** — add `access_logs { bucket = ..., prefix = ... }` to the load balancer (SOX, SOC2 CC7.2, DORA ICT audit trail).
|
||||
- **Security group rules** — add ingress/egress rules restricting traffic to known sources (SOC2 CC6.6, PCI-DSS 1.2).
|
||||
- **Health check** — add a `health_check` block to the target group (SOC2 CC7.3 monitoring, DORA operational resilience).
|
||||
- **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).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,31 +1,57 @@
|
||||
# l1-ecr — ECR repository primitive
|
||||
# l1-ecr — ECR repository
|
||||
|
||||
An L1 module for an ECR repository that hosts the ECS task image.
|
||||
Single-purpose, substrate-agnostic (the IR type is
|
||||
`aws:ecr:repository`, not a Terraform resource type).
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
A single ECR repository that hosts the container image for the ECS
|
||||
task. The simplest container-registry module — one resource, two
|
||||
inputs, two outputs.
|
||||
|
||||
See `interface.json`: inputs `name` + `region` (strings), outputs
|
||||
`repository_url` (string) + `repository_arn` (arn), no NFRs.
|
||||
## Resources
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| repository | `aws_ecr_repository` | The ECR repository |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
## Inputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ecr:repository` | `resource "aws_ecr_repository" "<id>" { ... }` |
|
||||
| `resource.inputs.name` | `name = <value>` arg |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.repository_url` | `output "repository_url" { value = aws_ecr_repository.<id>.repository_url }` |
|
||||
| `resource.outputs.repository_arn` | `output "repository_arn" { value = aws_ecr_repository.<id>.arn }` |
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `name` | string | yes | — | The ECR repository name |
|
||||
| `region` | string | yes | — | AWS region the repository is created in |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
## Outputs
|
||||
|
||||
## Versioning (W3.D)
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `repository_url` | string | The ECR repository URL |
|
||||
| `repository_arn` | arn | The ECR repository ARN |
|
||||
|
||||
## Usage
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "ecr",
|
||||
"type": "aws:ecr:repository",
|
||||
"module": "l1-ecr@1.0.0",
|
||||
"inputs": {
|
||||
"name": "acdl-microservice",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `repository_url` output is used to build the `image` input for
|
||||
`l1-ecs-service` (e.g. `<repository_url>:latest`).
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Image scanning** — add `image_scanning_configuration { scan_on_push = true }` for vulnerability scanning (SOC2 CC7.6, DORA ICT risk testing, HIPAA security monitoring).
|
||||
- **Encryption** — add `encryption_configuration { encryption_type = "KMS", kms_key = ... }` with a customer-managed key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **Image tag immutability** — add `image_tag_mutability = "IMMUTABLE"` to prevent tag overwriting (SOX §802, SOC2 CC6.1 integrity, DORA audit integrity).
|
||||
- **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)).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,31 +1,55 @@
|
||||
# l1-ecs-cluster — ECS Fargate cluster primitive
|
||||
# l1-ecs-cluster — ECS Fargate cluster
|
||||
|
||||
An L1 module for an ECS Fargate cluster. Single-purpose,
|
||||
substrate-agnostic (the IR type is `aws:ecs:cluster`, not a Terraform
|
||||
resource type).
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
An ECS Fargate cluster. The simplest ECS module — one resource, two
|
||||
inputs, two outputs. The cluster is the container orchestration
|
||||
boundary that `l1-ecs-service` references for task placement.
|
||||
|
||||
See `interface.json`: inputs `name` + `region` (strings), outputs
|
||||
`cluster_arn` (arn) + `cluster_id` (string), no NFRs.
|
||||
## Resources
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| cluster | `aws_ecs_cluster` | The ECS Fargate cluster |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
## Inputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ecs:cluster` | `resource "aws_ecs_cluster" "<id>" { ... }` |
|
||||
| `resource.inputs.name` | `name = <value>` arg |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.cluster_arn` | `output "cluster_arn" { value = aws_ecs_cluster.<id>.arn }` |
|
||||
| `resource.outputs.cluster_id` | `output "cluster_id" { value = aws_ecs_cluster.<id>.id }` |
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `name` | string | yes | — | The ECS cluster name |
|
||||
| `region` | string | yes | — | AWS region the cluster is created in |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
## Outputs
|
||||
|
||||
## Versioning (W3.D)
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `cluster_arn` | arn | The ECS cluster ARN |
|
||||
| `cluster_id` | string | The ECS cluster id (name) |
|
||||
|
||||
## Usage
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "cluster",
|
||||
"type": "aws:ecs:cluster",
|
||||
"module": "l1-ecs-cluster@1.0.0",
|
||||
"inputs": {
|
||||
"name": "acdl-microservice",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `cluster_arn` output is referenced by `l1-ecs-service` as its
|
||||
`cluster_arn` input.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Container Insights** — add `configuration { container_insights = "enabled" }` for observability (SOC2 CC7.3, DORA ICT risk monitoring).
|
||||
- **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).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,54 +1,77 @@
|
||||
# l1-ecs-service — ECS Fargate service primitive (multi-resource L1)
|
||||
# l1-ecs-service — ECS Fargate service (task definition + service)
|
||||
|
||||
An L1 module for an ECS Fargate service (task definition + service).
|
||||
Substrate-agnostic (the IR types are `aws:ecs:task_definition` and
|
||||
`aws:ecs:service`, not Terraform resource types). This is a
|
||||
multi-resource L1: the interface declares the group's inputs/outputs
|
||||
plus a `resources` array listing the IR types it emits. The IR instance
|
||||
(Phase 14/15) will have multiple `resources` entries all with
|
||||
`module: "l1-ecs-service@1.0.0"`.
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
An ECS Fargate service with its task definition. Runs a container image
|
||||
on Fargate, optionally behind an ALB target group. This is a
|
||||
multi-resource module: it creates a task definition and a service that
|
||||
runs it.
|
||||
|
||||
See `interface.json`: inputs `image` (string, ECR image URL), `port`
|
||||
(number), `cpu` (number, default 256), `memory` (number, default 512),
|
||||
`env` (optional JSON map string), `cluster_arn` (arn, ref to
|
||||
l1-ecs-cluster), `subnets` (string, ref to l1-vpc), `security_group`
|
||||
(string), `lb_target_group_arn` (arn, optional, ref to l1-alb), `region`
|
||||
(string); outputs `service_arn` (arn) + `task_def_arn` (arn); no NFRs.
|
||||
## Resources
|
||||
|
||||
The `resources` array lists the emitted IR types:
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| task_definition | `aws_ecs_task_definition` | Fargate task definition with container image, CPU, memory, port, env |
|
||||
| service | `aws_ecs_service` | Fargate service running the task definition in a cluster + subnets |
|
||||
|
||||
- `aws:ecs:task_definition` — Fargate task definition. The adapter
|
||||
jsonencodes `image`/`port`/`env` into `container_definitions`.
|
||||
- `aws:ecs:service` — Fargate service running the task definition in the
|
||||
cluster + subnets (+ optional ALB target group wiring).
|
||||
## Inputs
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `image` | string | yes | — | ECR image URL for the task container |
|
||||
| `port` | number | yes | — | Container port the service listens on |
|
||||
| `cpu` | number | no | 256 | Task CPU units (Fargate) |
|
||||
| `memory` | number | no | 512 | Task memory in MiB (Fargate) |
|
||||
| `env` | string | no | — | Environment variables as a JSON map string |
|
||||
| `cluster_arn` | arn | yes | — | ECS cluster ARN (from `l1-ecs-cluster`) |
|
||||
| `subnets` | string | yes | — | Comma-separated subnet ids (from `l1-vpc`) |
|
||||
| `security_group` | string | yes | — | Security group id for the service ENIs |
|
||||
| `lb_target_group_arn` | arn | no | — | Optional ALB target group ARN (from `l1-alb`) |
|
||||
| `region` | string | yes | — | AWS region the service is created in |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates each
|
||||
emitted IR resource to Terraform:
|
||||
## Outputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ecs:task_definition` | `resource "aws_ecs_task_definition" "<id>" { ... }` |
|
||||
| `resource.inputs.image` + `port` + `env` | `container_definitions = jsonencode(...)` (adapter-built) |
|
||||
| `resource.inputs.cpu` | `cpu = <value>` arg |
|
||||
| `resource.inputs.memory` | `memory = <value>` arg |
|
||||
| `resource.outputs.task_def_arn` | `output "task_def_arn" { value = aws_ecs_task_definition.<id>.arn }` |
|
||||
| `resource.type = aws:ecs:service` | `resource "aws_ecs_service" "<id>" { ... }` |
|
||||
| `resource.inputs.cluster_arn` | `cluster = <value>` arg (identity) |
|
||||
| `resource.inputs.subnets` | `network_configuration { subnets = [...] }` (emit as-is) |
|
||||
| `resource.inputs.security_group` | `network_configuration { security_groups = [...] }` (emit as-is) |
|
||||
| `resource.inputs.lb_target_group_arn` | `load_balancer { target_group_arn = <value> }` (emit as-is) |
|
||||
| `resource.outputs.service_arn` | `output "service_arn" { value = aws_ecs_service.<id>.id }` |
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `service_arn` | arn | The ECS service ARN |
|
||||
| `task_def_arn` | arn | The ECS task definition ARN |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates. The `container_definitions` JSON is built
|
||||
by the adapter from the IR `image`/`port`/`env` inputs (the one
|
||||
transformation the adapter owns for ECS task definitions).
|
||||
## Usage
|
||||
|
||||
## Versioning (W3.D)
|
||||
```json
|
||||
{
|
||||
"id": "service",
|
||||
"type": "aws:ecs:task_definition",
|
||||
"module": "l1-ecs-service@1.0.0",
|
||||
"inputs": {
|
||||
"image": "581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest",
|
||||
"port": 8080,
|
||||
"cpu": 256,
|
||||
"memory": 512,
|
||||
"cluster_arn": "ref:cluster.cluster_arn",
|
||||
"subnets": "ref:vpc.subnet_ids",
|
||||
"security_group": "ref:roles.role_arn",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `image`, `port`, and `env` inputs are compiled into a
|
||||
`container_definitions` JSON block by the adapter. The service is
|
||||
placed in the cluster with the given subnets and security group, and
|
||||
optionally wired to the ALB target group if `lb_target_group_arn` is
|
||||
provided.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **CloudWatch Logs** — add `logConfiguration` to the container definition with a log group + retention policy (SOX, SOC2 CC7.2, HIPAA §164.312(b), DORA ICT incident logging).
|
||||
- **Task execution role separation** — add a separate `aws_iam_role` for execution vs. the task role (SOC2 CC6.3 segregation of duties at runtime).
|
||||
- **Secrets injection** — add `secrets` block referencing AWS Secrets Manager / SSM Parameter Store with KMS encryption (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv)).
|
||||
- **Execute command** — add `enable_execute_command` with KMS encryption for session audit (SOC2 CC7.2).
|
||||
- **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).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,35 +1,63 @@
|
||||
# l1-iam-role — IAM role primitive
|
||||
# l1-iam-role — IAM role
|
||||
|
||||
An L1 module for an IAM role (used as the ECS task execution role).
|
||||
Single-purpose, substrate-agnostic (the IR type is `aws:iam:role`, not a
|
||||
Terraform resource type).
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
A single IAM role with an assume-role policy and optional managed
|
||||
policy attachments. Used as the ECS task execution role.
|
||||
|
||||
See `interface.json`: inputs `role_name` (string), `assume_role_policy`
|
||||
(JSON string), `managed_policies` (optional comma-separated ARNs),
|
||||
`region` (string); outputs `role_arn` (arn) + `role_id` (string), no
|
||||
NFRs.
|
||||
## Resources
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| role | `aws_iam_role` | The IAM role with assume-role policy |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
## Inputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:iam:role` | `resource "aws_iam_role" "<id>" { ... }` |
|
||||
| `resource.inputs.role_name` | `name = <value>` arg |
|
||||
| `resource.inputs.assume_role_policy` | `assume_role_policy = <value>` arg (JSON string) |
|
||||
| `resource.inputs.managed_policies` | `managed_policy_arns = [<arns>]` arg (comma-split) |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.role_arn` | `output "role_arn" { value = aws_iam_role.<id>.arn }` |
|
||||
| `resource.outputs.role_id` | `output "role_id" { value = aws_iam_role.<id>.id }` |
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `role_name` | string | yes | — | The IAM role name |
|
||||
| `assume_role_policy` | string | yes | — | Assume-role policy document (JSON string) |
|
||||
| `managed_policies` | string | no | — | Comma-separated list of managed policy ARNs to attach |
|
||||
| `region` | string | yes | — | AWS region the role is created in |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
## Outputs
|
||||
|
||||
## Versioning (W3.D)
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `role_arn` | arn | The IAM role ARN |
|
||||
| `role_id` | string | The IAM role id |
|
||||
|
||||
## Usage
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "roles",
|
||||
"type": "aws:iam:role",
|
||||
"module": "l1-iam-role@1.0.0",
|
||||
"inputs": {
|
||||
"role_name": "acdl-microservice-exec",
|
||||
"assume_role_policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"ecs-tasks.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}",
|
||||
"managed_policies": "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `assume_role_policy` is a JSON string — the adapter jsonencodes it
|
||||
into the Terraform `assume_role_policy` argument. The
|
||||
`managed_policies` input is a comma-separated list of ARNs, emitted as
|
||||
`managed_policy_arns = [...]`.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Permissions boundary** — add `permissions_boundary` to enforce least-privilege guardrails (SOC2 CC6.1, SOX ITGC, DORA ICT access control).
|
||||
- **Inline policy** — add `aws_iam_role_policy` for fine-grained least-privilege instead of broad managed policies (SOC2 CC6.1, HIPAA §164.308(a)(4)).
|
||||
- **MFA conditions** — add `condition` blocks requiring MFA for assume-role (SOC2 CC6.1, HIPAA §164.312(d)).
|
||||
- **Source IP / region conditions** — add `aws:SourceIp` / `aws:RequestedRegion` conditions for data residency enforcement (GDPR Art.44-49, DORA ICT third-party risk).
|
||||
- **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).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,39 +1,62 @@
|
||||
# l1-s3 — S3 bucket primitive
|
||||
# l1-s3 — S3 bucket
|
||||
|
||||
The first real L1 module for the v1.1 spike. Single-purpose,
|
||||
substrate-agnostic (the IR type is `aws:s3:bucket`, not a Terraform
|
||||
resource type).
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
A single S3 bucket for object storage. The simplest module — one
|
||||
resource, two inputs, two outputs. Versioning is enabled by default.
|
||||
|
||||
See `interface.json`: inputs `bucket_name` + `region` (strings), outputs
|
||||
`bucket_arn` (arn) + `bucket_name` (string), NFR `versioning` (bool,
|
||||
default true).
|
||||
## Resources
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| bucket | `aws_s3_bucket` | The S3 bucket itself |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
## Inputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:s3:bucket` | `resource "aws_s3_bucket" "<id>" { ... }` |
|
||||
| `resource.inputs.bucket_name` | `bucket = <value>` arg |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.bucket_arn` | `output "bucket_arn" { value = aws_s3_bucket.<id>.arn }` |
|
||||
| `resource.outputs.bucket_name` | `output "bucket_name" { value = aws_s3_bucket.<id>.id }` |
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `bucket_name` | string | yes | — | Globally-unique S3 bucket name |
|
||||
| `region` | string | yes | — | AWS region the bucket is created in |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
## Outputs
|
||||
|
||||
## Spike instance
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `bucket_arn` | arn | The S3 bucket ARN |
|
||||
| `bucket_name` | string | The bucket name (echoes the input) |
|
||||
|
||||
`spike_instance.json` is a concrete stack instance (with values
|
||||
`bucket_name=acdl-spike-bucket`, `region=us-east-1`) that validates
|
||||
against `schemas/ir.schema.json`. The adapter consumes this instance
|
||||
(not the interface contract) to emit Terraform.
|
||||
## NFRs
|
||||
|
||||
## Versioning (W3.D)
|
||||
| Name | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `versioning` | boolean | true | Enable S3 versioning |
|
||||
|
||||
## Usage
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "s3",
|
||||
"type": "aws:s3:bucket",
|
||||
"module": "l1-s3@1.0.0",
|
||||
"inputs": {
|
||||
"bucket_name": "acdl-spike-bucket",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A concrete instance is at `spike_instance.json` (used by the platform
|
||||
pipeline as the regression baseline).
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Encryption at rest** — add `aws_s3_bucket_server_side_encryption_configuration` with a customer-managed KMS key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **Object Lock** — add `aws_s3_bucket_object_lock_configuration` in compliance mode with 7-year retention for immutable evidence (SOX §802, DORA audit trail).
|
||||
- **Access logging** — add `aws_s3_bucket_logging` to a target logging bucket (SOC2 CC7.2).
|
||||
- **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)).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,51 +1,66 @@
|
||||
# l1-vpc — VPC primitive (multi-resource L1)
|
||||
# l1-vpc — VPC with subnets and routing
|
||||
|
||||
An L1 module for a VPC with subnets and a route table. Substrate-agnostic
|
||||
(the IR types are `aws:ec2:vpc`, `aws:ec2:subnet`, `aws:ec2:routetable`,
|
||||
not Terraform resource types). This is a multi-resource L1: the
|
||||
interface declares the group's inputs/outputs plus a `resources` array
|
||||
listing the IR types it emits. The IR instance (Phase 14/15) will have
|
||||
multiple `resources` entries all with `module: "l1-vpc@1.0.0"`.
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
A VPC with one subnet per availability zone and a route table with a
|
||||
default route through an internet gateway. The networking foundation
|
||||
that other modules (ALB, ECS service) reference for subnet ids.
|
||||
|
||||
See `interface.json`: inputs `cidr` (string, e.g. "10.0.0.0/16"), `azs`
|
||||
(string, comma-separated, e.g. "us-east-1a,us-east-1b"), `name` (string,
|
||||
used for tagging), `region` (string); outputs `vpc_id` (string),
|
||||
`subnet_ids` (string, comma-separated), `igw_id` (string); no NFRs.
|
||||
## Resources
|
||||
|
||||
The `resources` array lists the emitted IR types:
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| vpc | `aws_vpc` | The VPC itself |
|
||||
| subnet | `aws_subnet` | One subnet per availability zone |
|
||||
| route_table | `aws_route_table` | Route table with default route 0.0.0.0/0 |
|
||||
| internet_gateway | `aws_internet_gateway` | IGW for public internet access |
|
||||
| route_table_association | `aws_route_table_association` | Binds subnet to route table |
|
||||
|
||||
- `aws:ec2:vpc` — the VPC itself (cidr → cidr_block, name → tag).
|
||||
- `aws:ec2:subnet` — one subnet per availability zone (`azs` split on
|
||||
comma); inputs include the parent VPC id.
|
||||
- `aws:ec2:routetable` — route table bound to the VPC with an internet
|
||||
gateway + default route (0.0.0.0/0 → igw).
|
||||
## Inputs
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `cidr` | string | yes | — | VPC CIDR block, e.g. `10.0.0.0/16` |
|
||||
| `azs` | string | yes | — | Comma-separated availability zones, e.g. `us-east-1a,us-east-1b` |
|
||||
| `name` | string | yes | — | Name tag for the VPC and child resources |
|
||||
| `region` | string | yes | — | AWS region the VPC is created in |
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates each
|
||||
emitted IR resource to Terraform:
|
||||
## Outputs
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ec2:vpc` | `resource "aws_vpc" "<id>" { ... }` |
|
||||
| `resource.inputs.cidr` | `cidr_block = <value>` arg |
|
||||
| `resource.inputs.name` | `tags = { Name = <value> }` (emit as-is) |
|
||||
| `resource.outputs.vpc_id` | `output "vpc_id" { value = aws_vpc.<id>.id }` |
|
||||
| `resource.type = aws:ec2:subnet` | `resource "aws_subnet" "<id>" { ... }` |
|
||||
| `resource.inputs.cidr` | `cidr_block = <value>` arg |
|
||||
| `resource.inputs.az` | `availability_zone = <value>` arg |
|
||||
| `resource.outputs.subnet_id` | `output "subnet_id" { value = aws_subnet.<id>.id }` |
|
||||
| `resource.type = aws:ec2:routetable` | `resource "aws_route_table" "<id>" { ... }` |
|
||||
| `resource.inputs.vpc_id` | `vpc_id = <value>` arg |
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `vpc_id` | string | The VPC id |
|
||||
| `subnet_ids` | string | Comma-separated subnet ids |
|
||||
|
||||
The internet gateway + default route are emitted as part of the route
|
||||
table resource's IR (the `igw_id` output is wired via the route table's
|
||||
inputs). The adapter is a thin layer (ARCHITECTURE.md §12.2); it does
|
||||
not own L1 content — it only translates.
|
||||
## Usage
|
||||
|
||||
## Versioning (W3.D)
|
||||
```json
|
||||
{
|
||||
"id": "vpc",
|
||||
"type": "aws:ec2:vpc",
|
||||
"module": "l1-vpc@1.0.0",
|
||||
"inputs": {
|
||||
"cidr": "10.0.0.0/16",
|
||||
"azs": "us-east-1a,us-east-1b",
|
||||
"name": "acdl-microservice",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `azs` input is split on comma; one subnet is created per zone. The
|
||||
route table gets a default route `0.0.0.0/0` → internet gateway. Other
|
||||
modules reference `subnet_ids` for their network placement.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **VPC Flow Logs** — add `aws_flow_log` + CloudWatch Logs group / S3 destination (SOX ITGC, SOC2 CC7.2, HIPAA §164.312(b), DORA ICT risk logging).
|
||||
- **Private subnets + NAT gateway** — add private subnets with a NAT gateway so ECS tasks don't need public IPs (SOC2 CC6.6, PCI-DSS 1.3, HIPAA network isolation).
|
||||
- **VPC endpoints** — add S3, ECR, KMS, DynamoDB, CloudWatch interface/gateway endpoints to keep traffic off the public internet (SOC2 CC6.7, GDPR Art.32(1)(a), DORA ICT third-party risk).
|
||||
- **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).
|
||||
|
||||
## Versioning
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
|
||||
@@ -1,85 +1,57 @@
|
||||
# l2-microservice — thin-composition (ECS Fargate microservice)
|
||||
# l2-microservice — ECS Fargate microservice (composition being redesigned)
|
||||
|
||||
The v1.2 L2. A thin-composition that references 6 L1s (depth 1):
|
||||
`l1-vpc`, `l1-ecs-cluster`, `l1-ecr`, `l1-iam-role`, `l1-alb`,
|
||||
`l1-ecs-service`. The contract's inputs (`name`, `cidr`, `azs`,
|
||||
`image`, `port`, `cpu`, `memory`, `env`, `protocol`, `region`,
|
||||
`role_name`, `assume_role_policy`, `managed_policies`) map to the
|
||||
children's inputs through two wire kinds.
|
||||
> **Module kind:** L2 composition | **Version:** TBD | **Status:** Under redesign
|
||||
|
||||
## Composition (the IR-typed thin-composition tree)
|
||||
A composition that references multiple L1 primitives to deploy an ECS
|
||||
Fargate microservice end-to-end (VPC, cluster, ECR, IAM role, ALB,
|
||||
ECS service).
|
||||
|
||||
See `composition.json`: `kind=l2`, `depth=1`, six children.
|
||||
**The composition layer is being redesigned.** The previous
|
||||
thin-composition implementation (a `composition.json` with children +
|
||||
wires) has been removed. A new composition mechanism will be designed
|
||||
in a later phase.
|
||||
|
||||
### Children
|
||||
## Resources
|
||||
|
||||
| child id | L1 module | IR type(s) |
|
||||
|----------|-----------|------------|
|
||||
| `vpc` | `l1-vpc@1.0.0` | `aws:ec2:vpc`, `aws:ec2:subnet`, `aws:ec2:routetable` |
|
||||
| `cluster` | `l1-ecs-cluster@1.0.0` | `aws:ecs:cluster` |
|
||||
| `ecr` | `l1-ecr@1.0.0` | `aws:ecr:repository` |
|
||||
| `roles` | `l1-iam-role@1.0.0` | `aws:iam:role` |
|
||||
| `alb` | `l1-alb@1.0.0` | `aws:elbv2:loadbalancer`, `aws:elbv2:listener`, `aws:elbv2:targetgroup` |
|
||||
| `service` | `l1-ecs-service@1.0.0` | `aws:ecs:task_definition`, `aws:ecs:service` |
|
||||
TBD — the composition will reference these L1 primitives:
|
||||
|
||||
Multi-resource L1s (`vpc`, `alb`, `service`) declare a `resources`
|
||||
array in their `interface.json`; the resolver expands each child into
|
||||
one IR resource per `resources` entry (id scheme `<child_id>-<type_suffix>`
|
||||
where `type_suffix` is the last segment of the IR type with underscores
|
||||
stripped — e.g. `vpc-vpc`, `vpc-subnet`, `vpc-routetable`,
|
||||
`alb-loadbalancer`, `alb-targetgroup`, `alb-listener`,
|
||||
`service-taskdefinition`, `service-service`. The hyphen separator keeps
|
||||
the id valid against `schemas/ir.schema.json`'s
|
||||
`^[a-z][a-z0-9-]*$` resource id pattern). Single-resource L1s keep the
|
||||
child id verbatim (`cluster`, `ecr`, `roles`).
|
||||
| L1 module | Purpose | README |
|
||||
|-----------|---------|--------|
|
||||
| `l1-vpc` | VPC, subnets, routing | [README](../l1/l1-vpc/README.md) |
|
||||
| `l1-ecs-cluster` | ECS Fargate cluster | [README](../l1/l1-ecs-cluster/README.md) |
|
||||
| `l1-ecr` | ECR image repository | [README](../l1/l1-ecr/README.md) |
|
||||
| `l1-iam-role` | IAM task execution role | [README](../l1/l1-iam-role/README.md) |
|
||||
| `l1-alb` | Application Load Balancer | [README](../l1/l1-alb/README.md) |
|
||||
| `l1-ecs-service` | ECS task definition + service | [README](../l1/l1-ecs-service/README.md) |
|
||||
|
||||
### Wire kinds
|
||||
## Inputs
|
||||
|
||||
1. **Contract→child passthrough** — wire name = contract input name;
|
||||
target = child id, input = child's input name. For contract inputs
|
||||
that fan out to multiple children (`name`, `port`, `region`), the
|
||||
wire value is an array of `{target, input}` objects; otherwise a
|
||||
single object. Resolves to the concrete contract value.
|
||||
TBD — will be defined when the composition mechanism is redesigned.
|
||||
|
||||
2. **Child→child references** — wire with `source: "child:<id>.<output>"`.
|
||||
The value is only known at apply time, so the resolver emits the IR
|
||||
input as the string `ref:<ir_resource_id>.<output>` (the IR resource
|
||||
id of the *producing* child's first resource — for single-resource
|
||||
L1s that is the child id, for multi-resource L1s it is
|
||||
`<child_id>-<type_suffix>` of the first resource in the `resources`
|
||||
array that declares the output). The adapter translates `ref:` to a
|
||||
Terraform interpolation.
|
||||
## Outputs
|
||||
|
||||
Wires used by this composition:
|
||||
TBD — will be defined when the composition mechanism is redesigned.
|
||||
|
||||
- Passthrough: `name` (→vpc/cluster/ecr/alb), `cidr` (→vpc), `azs`
|
||||
(→vpc), `image` (→service), `port` (→service/alb), `cpu` (→service),
|
||||
`memory` (→service), `env` (→service), `protocol` (→alb), `region`
|
||||
(→all 6), `role_name` (→roles), `assume_role_policy` (→roles),
|
||||
`managed_policies` (→roles).
|
||||
- Child→child: `cluster_arn` (cluster→service), `subnet_ids`
|
||||
(vpc→service/alb `subnets`), `target_group_arn` (alb→service
|
||||
`lb_target_group_arn`), `role_arn` (roles→service/alb
|
||||
`security_group`).
|
||||
## Usage
|
||||
|
||||
## IR → Terraform mapping (D-P10-1)
|
||||
TBD — the composition mechanism is being redesigned. Until then, use
|
||||
the L1 primitives directly. See each L1 module's README for usage
|
||||
examples.
|
||||
|
||||
The Terraform adapter consumes the *resolved IR instance* (which has
|
||||
`kind=l2` + all 6 L1s expanded into one IR resource per entry in each
|
||||
L1's `resources` array, with `ref:` strings on the consumer inputs).
|
||||
For a depth-1 thin-composition, the L2 root module **IS** the union of
|
||||
the L1 resources — no separate `module "l1_x" { source = "..." }`
|
||||
blocks. The existing adapter `TYPE_MAP` + `INPUT_MAP` + `OUTPUT_MAP`
|
||||
tables handle every IR type. `ref:<id>.<output>` inputs are translated
|
||||
to `${<tf_type>.<id>.<attr>}` (attribute mapped through `OUTPUT_MAP`
|
||||
for the referenced resource's type). The `relationships` array records
|
||||
the parent composition tree; ordering is implicit in the resource list.
|
||||
## Compliance extension points
|
||||
|
||||
v1.3+ may emit real `module "l1_x" { source = "..." }` blocks once L1s
|
||||
are published Terraform modules rather than inline resources.
|
||||
The composition will need to wire compliance resources across L1s
|
||||
when the compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
|
||||
|
||||
## Versioning (W3.D)
|
||||
- **KMS key** — shared encryption key referenced by S3, ECR, CloudWatch Logs, and Secrets Manager.
|
||||
- **CloudTrail** — management-plane audit trail for the entire stack.
|
||||
- **VPC Flow Logs** — network audit trail.
|
||||
- **Security groups** — proper network segmentation between ALB, service, and data tiers.
|
||||
- **Private subnets** — ECS tasks in private subnets with NAT egress.
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
a 12-month deprecation window.
|
||||
See each L1 module's README for per-module compliance extension points.
|
||||
|
||||
## Versioning
|
||||
|
||||
Versioning will be defined when the composition mechanism is
|
||||
redesigned.
|
||||
@@ -1,55 +0,0 @@
|
||||
{
|
||||
"name": "l2-microservice",
|
||||
"version": "1.0.0",
|
||||
"kind": "l2",
|
||||
"depth": 1,
|
||||
"description": "Thin-composition: an ECS Fargate microservice. References 6 L1s (vpc, cluster, ecr, roles, alb, service).",
|
||||
"children": [
|
||||
{"id": "vpc", "module": "l1-vpc@1.0.0"},
|
||||
{"id": "cluster", "module": "l1-ecs-cluster@1.0.0"},
|
||||
{"id": "ecr", "module": "l1-ecr@1.0.0"},
|
||||
{"id": "roles", "module": "l1-iam-role@1.0.0"},
|
||||
{"id": "alb", "module": "l1-alb@1.0.0"},
|
||||
{"id": "service", "module": "l1-ecs-service@1.0.0"}
|
||||
],
|
||||
"wires": {
|
||||
"name": [
|
||||
{"target": "vpc", "input": "name"},
|
||||
{"target": "cluster", "input": "name"},
|
||||
{"target": "ecr", "input": "name"},
|
||||
{"target": "alb", "input": "name"}
|
||||
],
|
||||
"cidr": {"target": "vpc", "input": "cidr"},
|
||||
"azs": {"target": "vpc", "input": "azs"},
|
||||
"image": {"target": "service", "input": "image"},
|
||||
"port": [
|
||||
{"target": "service", "input": "port"},
|
||||
{"target": "alb", "input": "port"}
|
||||
],
|
||||
"cpu": {"target": "service", "input": "cpu"},
|
||||
"memory": {"target": "service", "input": "memory"},
|
||||
"env": {"target": "service", "input": "env"},
|
||||
"protocol": {"target": "alb", "input": "protocol"},
|
||||
"region": [
|
||||
{"target": "vpc", "input": "region"},
|
||||
{"target": "cluster", "input": "region"},
|
||||
{"target": "ecr", "input": "region"},
|
||||
{"target": "roles", "input": "region"},
|
||||
{"target": "alb", "input": "region"},
|
||||
{"target": "service", "input": "region"}
|
||||
],
|
||||
"role_name": {"target": "roles", "input": "role_name"},
|
||||
"assume_role_policy": {"target": "roles", "input": "assume_role_policy"},
|
||||
"managed_policies": {"target": "roles", "input": "managed_policies"},
|
||||
"cluster_arn": {"target": "service", "input": "cluster_arn", "source": "child:cluster.cluster_arn"},
|
||||
"subnet_ids": [
|
||||
{"target": "service", "input": "subnets", "source": "child:vpc.subnet_ids"},
|
||||
{"target": "alb", "input": "subnets", "source": "child:vpc.subnet_ids"}
|
||||
],
|
||||
"target_group_arn": {"target": "service", "input": "lb_target_group_arn", "source": "child:alb.target_group_arn"},
|
||||
"role_arn": [
|
||||
{"target": "service", "input": "security_group", "source": "child:roles.role_arn"},
|
||||
{"target": "alb", "input": "security_group", "source": "child:roles.role_arn"}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,31 +1,51 @@
|
||||
# l2-static-asset — thin-composition (S3 static asset)
|
||||
# l2-static-asset — S3 static asset (composition being redesigned)
|
||||
|
||||
The v1.1 spike's L2. A thin-composition that references `l1-s3` only
|
||||
(depth 1). The contract's inputs (`bucket_name`, `region`) map 1:1
|
||||
through the wires to the L1's inputs.
|
||||
> **Module kind:** L2 composition | **Version:** TBD | **Status:** Under redesign
|
||||
|
||||
## Composition (the IR-typed thin-composition tree)
|
||||
A composition that references the `l1-s3` primitive to deploy a single
|
||||
S3 bucket for static asset hosting.
|
||||
|
||||
See `composition.json`: `kind=l2`, `depth=1`, one child `l1-s3@1.0.0`,
|
||||
wires `{bucket_name → s3.inputs.bucket_name, region → s3.inputs.region}`
|
||||
(passthrough).
|
||||
**The composition layer is being redesigned.** The previous
|
||||
thin-composition implementation (a `composition.json` with children +
|
||||
wires) has been removed. A new composition mechanism will be designed
|
||||
in a later phase.
|
||||
|
||||
## IR → Terraform mapping (D-P10-1)
|
||||
## Resources
|
||||
|
||||
The Terraform adapter consumes the *resolved IR instance* (which has
|
||||
`kind=l2` + the L1 resource `s3` in its `resources` array). For a
|
||||
depth-1 thin-composition, the L2 root module **IS** the L1's resource —
|
||||
no separate `module "l1_s3" { source = "..." }` block. The existing
|
||||
adapter `TYPE_MAP` + resource emission handle both l1 and l2 instances
|
||||
(the resources array is the same shape). The `relationships` array is
|
||||
ignored at the Terraform level for the spike (composition ordering is
|
||||
implicit in the single resource).
|
||||
TBD — the composition will reference this L1 primitive:
|
||||
|
||||
v1.2 may emit a real `module "l1_s3" { source = "..." }` block when L1s
|
||||
become published Terraform modules rather than inline resources.
|
||||
| L1 module | Purpose | README |
|
||||
|-----------|---------|--------|
|
||||
| `l1-s3` | S3 bucket | [README](../l1/l1-s3/README.md) |
|
||||
|
||||
## Versioning (W3.D)
|
||||
## Inputs
|
||||
|
||||
`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
|
||||
require a new registry entry (immutable publication); old entries enter
|
||||
a 12-month deprecation window.
|
||||
TBD — will be defined when the composition mechanism is redesigned.
|
||||
|
||||
## Outputs
|
||||
|
||||
TBD — will be defined when the composition mechanism is redesigned.
|
||||
|
||||
## Usage
|
||||
|
||||
TBD — the composition mechanism is being redesigned. Until then, use
|
||||
`l1-s3` directly. See the [l1-s3 README](../l1/l1-s3/README.md) for a
|
||||
usage example.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
The composition will need to wire compliance resources when the
|
||||
compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
|
||||
|
||||
- **KMS key** — shared encryption key for S3 SSE.
|
||||
- **S3 access logs** — access logging to a separate audit bucket.
|
||||
- **Object Lock** — 7-year immutable retention for evidence.
|
||||
- **Public access block** — prevent data exfiltration.
|
||||
|
||||
See the [l1-s3 README](../l1/l1-s3/README.md) for per-module compliance
|
||||
extension points.
|
||||
|
||||
## Versioning
|
||||
|
||||
Versioning will be defined when the composition mechanism is
|
||||
redesigned.
|
||||
@@ -1,17 +0,0 @@
|
||||
{
|
||||
"name": "l2-static-asset",
|
||||
"version": "1.0.0",
|
||||
"kind": "l2",
|
||||
"depth": 1,
|
||||
"description": "Thin-composition: a single S3 bucket for static asset hosting. References l1-s3 only (depth 1).",
|
||||
"children": [
|
||||
{
|
||||
"id": "s3",
|
||||
"module": "l1-s3@1.0.0"
|
||||
}
|
||||
],
|
||||
"wires": {
|
||||
"bucket_name": {"target": "s3", "input": "bucket_name"},
|
||||
"region": {"target": "s3", "input": "region"}
|
||||
}
|
||||
}
|
||||
@@ -47,19 +47,5 @@
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l2-static-asset": {
|
||||
"1.0.0": {
|
||||
"composition": "modules-ir/l2/l2-static-asset/composition.json",
|
||||
"published_at": "2026-07-21T19:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l2-microservice": {
|
||||
"1.0.0": {
|
||||
"composition": "modules-ir/l2/l2-microservice/composition.json",
|
||||
"published_at": "2026-07-21T22:00:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user