Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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.md
index 7bf0731608..cc3a150c36 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -146,6 +146,40 @@ ln -s AGENTS.md COPILOT.md
Always 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 Guidelines
1. Branch off `main`: `git checkout -b feature/my-feature`
diff --git a/docs/services/cloudformation.md b/docs/services/cloudformation.md
index 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 by
cross-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` |