Light, fluffy, and always free - The AWS Local Emulator alternative
docs(cloudformation): document the per-service provisioner path for new resource types (#2153)
Hector Venturaee15447ba41b
diff --git a/AGENTS.md b/AGENTS.mdindex 9677be5497..32d3925a29 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -263,6 +263,40 @@ When adding functionality:---+## Adding a CloudFormation Resource Type++**Do not add cases to `CloudFormationResourceProvisioner`.** That class is a legacy+monolith being dismantled; new types go in per-service provisioners under+`services/cloudformation/provisioners/`.++1. Add the type to the existing `<Service>CfnProvisioner`, or create one:+ `@ApplicationScoped`, injecting only the service it wraps. CDI discovery via+ `CloudFormationResourceRegistry` handles registration — no manual wiring, but a+ missing `@ApplicationScoped` silently means the type is never provisioned.+2. `resourceTypes()` lists the `AWS::*` types; `provision(resource, props, ctx)`+ does the work, switching on `resource.getResourceType()` when it serves several.+3. Set **both** reference mechanisms — they are separate:+ - `resource.setPhysicalId(...)` backs `Ref`+ - `resource.getAttributes().put(...)` backs `Fn::GetAtt`, one entry per attribute+ Omitting an attribute does not fail; `Fn::GetAtt` resolves to the literal+ `"LogicalId.Attr"`. Source the attribute names from the type's registry schema in+ `local/aws/cfn-resource-schemas/us-east-1/` (`readOnlyProperties`), and validate+ `required` from the same file.+4. **`provision` serves create *and* update.** On `UpdateStack` it is re-invoked with+ the prior physical id and attributes already populated on the resource. Branch on+ that instead of creating unconditionally.+5. Override `delete(...)` when the type has a backing delete; tolerate already-deleted.+6. Tests: focused unit test mocking one service (`SqsCfnProvisionerTest` is the+ pattern) plus an integration test asserting the **exact `Fn::GetAtt` keys**. An+ unmapped type is stubbed as `CREATE_COMPLETE` with a fake ARN, so asserting status+ alone cannot detect a type that was never wired.+7. Update the resource-type table in `docs/services/cloudformation.md`.++References: `SqsCfnProvisioner` (smallest), `Ec2LaunchTemplateCfnProvisioner`+(update-in-place and replacement).++---+## Code Style- Use constructor injection@@ -345,6 +379,10 @@ Treat release workflows as critical infrastructure.- Producing inconsistent URLs or ARNs- Testing only with raw HTTP- Introducing unnecessary new patterns+- Adding a CloudFormation type to `CloudFormationResourceProvisioner` instead of a+ per-service provisioner+- Setting a CloudFormation resource's physical id but not its `Fn::GetAtt`+ attributes (they are two separate mechanisms, and the miss is silent)---diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7bf0731608..cc3a150c36 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -146,6 +146,40 @@ ln -s AGENTS.md COPILOT.mdAlways implement the **real AWS wire protocol** — never invent custom endpoints. The AWS SDK must work against Floci without modification.+## Adding a CloudFormation Resource Type++CloudFormation resource types live in **per-service provisioner classes**, not in+`CloudFormationResourceProvisioner`. That class is a legacy monolith being dismantled — please do+not add cases to it. If the service you need already has a `*CfnProvisioner`, add your type there;+otherwise create one.++1. Create `services/cloudformation/provisioners/<Service>CfnProvisioner.java`, annotate it+ `@ApplicationScoped`, and inject **only** the service it wraps. Registration is automatic —+ `CloudFormationResourceRegistry` discovers it via CDI. (Forgetting `@ApplicationScoped` compiles+ and unit-tests green, but the type is never wired.)+2. Implement `resourceTypes()` returning every `AWS::*` type the class serves, and `provision(...)`.+ When you serve more than one type, switch on `resource.getResourceType()`.+3. In `provision`, set **both**:+ - `resource.setPhysicalId(...)` — this is what `Ref` resolves to+ - `resource.getAttributes().put("Name", value)` for every `Fn::GetAtt` attribute — a *separate*+ map. Forgetting it does not fail: `Fn::GetAtt` silently resolves to the literal string+ `"LogicalId.Attr"`. Take the attribute names from the resource's registry schema under+ `local/aws/cfn-resource-schemas/us-east-1/` (`readOnlyProperties`).+4. **`provision` is also the update path.** On `UpdateStack` it is called again with the previous+ physical id and attributes already set on the resource. Check for an existing physical id and+ update in place rather than creating unconditionally, which would otherwise throw+ `AlreadyExists` or orphan the old resource.+5. Override `delete(...)` if the type has a backing delete. Deleting a resource that is already gone+ should be tolerated.+6. Add a focused unit test (mock only your service — see `SqsCfnProvisionerTest`) and an integration+ test. Assert the **specific `Fn::GetAtt` attribute keys**, not just `CREATE_COMPLETE`: an+ unmapped type is stubbed out as a successful no-op, so a status-only assertion passes even when+ nothing was provisioned.+7. Add the type to the table in `docs/services/cloudformation.md`.++`SqsCfnProvisioner` is the smallest reference implementation; `Ec2LaunchTemplateCfnProvisioner`+shows update-in-place and replacement handling.+## Pull Request Guidelines1. Branch off `main`: `git checkout -b feature/my-feature`diff --git a/docs/services/cloudformation.md b/docs/services/cloudformation.mdindex f93d0413ce..4ad8ea6c45 100644--- a/docs/services/cloudformation.md+++ b/docs/services/cloudformation.md@@ -47,6 +47,10 @@ Resource types provisioned during `CreateStack` / `UpdateStack` / `DeleteStack`.the backing service and sets a real physical ID plus the `Ref` / `Fn::GetAtt` attributes used bycross-resource references.+> Adding a type? See [Adding a CloudFormation Resource Type](../../CONTRIBUTING.md#adding-a-cloudformation-resource-type).+> Types live in per-service provisioners under `services/cloudformation/provisioners/`; keep this+> table in step with them.+| Service | Resource types ||---|---|| S3 | `Bucket`, `BucketPolicy` (accepted; policy not enforced) |@@ -62,7 +66,7 @@ cross-resource references.| ECS | `Cluster`, `TaskDefinition`, `Service` || EKS | `Cluster`, `Nodegroup` || RDS | `DBInstance`, `DBCluster`, `DBSubnetGroup`, `DBParameterGroup`, `DBClusterParameterGroup` (DBInstance/DBCluster start real containers) |-| EC2 | `VPC`, `Subnet`, `SecurityGroup`, `InternetGateway`, `RouteTable`, `SubnetRouteTableAssociation`, `Route`, `NatGateway`, `EIP`, `Instance` |+| EC2 | `VPC`, `Subnet`, `SecurityGroup`, `InternetGateway`, `RouteTable`, `SubnetRouteTableAssociation`, `Route`, `NatGateway`, `EIP`, `Instance`, `LaunchTemplate`, `VPCGatewayAttachment` || Elastic Load Balancing v2 | `LoadBalancer`, `TargetGroup`, `Listener`, `ListenerRule` || Auto Scaling | `LaunchConfiguration`, `AutoScalingGroup` || Route 53 | `HostedZone`, `RecordSet` |@@ -71,7 +75,7 @@ cross-resource references.| Step Functions | `StateMachine` || Batch | `ComputeEnvironment`, `JobQueue`, `JobDefinition` || Cognito | `UserPool`, `UserPoolClient` |-| EventBridge | `Events::Rule` |+| EventBridge | `Rule`, `EventBus`, `EventBusPolicy` || Pipes | `Pipe` || Kinesis | `Stream` || Kinesis Data Firehose | `DeliveryStream` |