Light, fluffy, and always free - The AWS Local Emulator alternative
docs(cloudformation): correct the resource-type contributor steps (#2762)
Hector Ventura54654760b5fd
diff --git a/AGENTS.md b/AGENTS.mdindex b888a3685d..8ed8d1552f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -283,17 +283,36 @@ monolith being dismantled; new types go in per-service provisioners under`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+ the prior physical id and attributes already populated on the resource. Branch with+ `ctx.isUpdate()` / `ctx.priorPhysicalId()`, not by reading the id off the resource:+ `provision` assigns the new id as it runs, so a resource-derived check flips+ mid-method.+5. Override `delete(...)` when the type has a backing delete; tolerate already-deleted+ via `CfnDeletes.safeDelete`, passing the specific "already gone" error codes. Never+ a catch-all: a real failure such as `BucketNotEmpty` must propagate so the stack+ reports `DELETE_FAILED`. When the delete needs a create-time attribute rather than+ just the physical id, override `delete(StackResource, String)`.+6. **Register in `src/test/resources/cloudformation/supported-resource-types.tsv`**+ (`type<TAB>Owner`). `CfnResourceInventoryTest` diffs that file against the+ CDI-resolved registry, so it also catches a missing `@ApplicationScoped`.+7. **Add the provisioner to `CfnProvisionerFixture.inferredProvisioners()`** when it+ takes a single service, or a fixture test naming that service silently falls through+ to the stub arm.+8. Tests: focused unit test mocking one service (`SqsCfnProvisioner`'s test is thepattern) plus an integration test asserting the **exact `Fn::GetAtt` keys**. Anunmapped 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`.+ alone cannot detect a type that was never wired. Note the engine's constructor is+ package-private, so tests in `provisioners/` mock it.+9. Run `make docs-sync` and commit the result. The resource-type table in+ `docs/services/cloudformation.md` is **generated** from the step-6 inventory; hand+ edits fail `docs-check`. Labels, ordering and notes live in+ `tools/docs/cfn_resource_types.yaml`.+10. A schema `readOnlyProperties` entry you cannot set goes in+ `src/test/resources/cloudformation/getatt-attribute-gaps.tsv` with a reason;+ `CfnSchemaCoverageTest` requires every unset attribute to be fixed or recorded.References: `SqsCfnProvisioner` (smallest), `Ec2LaunchTemplateCfnProvisioner`-(update-in-place and replacement).+(update-in-place and replacement), `LogsCfnProvisioner` (reconcile-vs-replace update).---@@ -387,6 +406,11 @@ Treat release workflows as critical infrastructure.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)+- Hand-editing the resource-type table in `docs/services/cloudformation.md`, which is+ generated, run `make docs-sync` instead+- Adding a CloudFormation provisioner without a row in+ `supported-resource-types.tsv` or an entry in `CfnProvisionerFixture`, either of+ which leaves a type quietly served by the stub arm---diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a3ebf2a487..5067931fbe 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -168,19 +168,44 @@ otherwise create one.`"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.+ physical id and attributes already set on the resource. Use `ctx.isUpdate()` and+ `ctx.priorPhysicalId()` rather than reading the id back off the resource: `provision` assigns the+ new id as it works, so a resource-derived check changes meaning mid-method. 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`.+ should be tolerated: `CfnDeletes.safeDelete` does this, taking the specific error codes that+ mean "already gone" (never a catch-all: a real failure such as `BucketNotEmpty` must propagate so+ the stack reports `DELETE_FAILED`).+ If the delete needs more than the physical id (a create-time attribute such as a rule's event+ bus), override `delete(StackResource, String)` instead, which receives the whole resource.+6. **Register the type in `src/test/resources/cloudformation/supported-resource-types.tsv`**+ (`type<TAB>YourCfnProvisioner`). `CfnResourceInventoryTest` compares that file against the+ CDI-resolved registry, so it fails if you forget, which is also what catches a missing+ `@ApplicationScoped`.+7. **Make your provisioner reachable from `CfnProvisionerFixture`** if it takes a single service.+ That is three edits, not one: a `private <Svc>Service` field on `Builder`, a+ `public Builder <svc>(<Svc>Service v)` setter for it, and a construction arm in+ `inferredProvisioners()`. Tests name a service and the fixture wires the matching provisioner;+ without all three, a test exercising your type silently falls through to the stub arm instead.+ The setter is the step that gets missed: a field nothing can assign stays null, so its+ construction arm never runs. `CfnProvisionerFixtureTest` fails if the provisioner cannot be+ reached through the public builder.+8. Add a focused unit test (mock only your service, see `SqsCfnProvisioner`'s test) 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.+9. Run `make docs-sync` to regenerate the resource-type table in `docs/services/cloudformation.md`,+ and commit the result. **Do not hand-edit that table**: it is generated from the inventory in+ step 6. Presentation (service label, ordering, notes) lives in `tools/docs/cfn_resource_types.yaml`.+10. If your type has a schema `readOnlyProperties` entry you cannot set, add a row to+ `src/test/resources/cloudformation/getatt-attribute-gaps.tsv` with the reason.+ `CfnSchemaCoverageTest` requires every unset attribute to be either fixed or recorded, so+ "not emulated" stays distinguishable from "forgotten".`SqsCfnProvisioner` is the smallest reference implementation; `Ec2LaunchTemplateCfnProvisioner`-shows update-in-place and replacement handling.+shows update-in-place and replacement handling; `LogsCfnProvisioner` shows a full reconcile-vs-replace+update path.## Pull Request Guidelines