docs(cloudformation): generate the supported resource-type table

.github/workflows/docs-actions.yml

@@ -1,13 +1,16 @@
 name: Docs Action Tables
 
-# Keeps the generated "Supported Actions" tables in docs/services/*.md in sync with
-# handler source. Runs on handler changes (which can add/remove actions) and on doc or
-# tooling changes. Python-only, so it is fast and independent of the Java build job.
+# Keeps the generated tables in docs/services/*.md in sync with their sources: the
+# "Supported Actions" tables with handler source, and the CloudFormation "Supported Resource
+# Types" table with the provisioner inventory TSV. Runs on handler changes (which can add or
+# remove actions), inventory changes (which add or move resource types), and on doc or tooling
+# changes. Python-only, so it is fast and independent of the Java build job.
 
 on:
   pull_request:
     paths:
       - 'src/main/**'
+      - 'src/test/resources/cloudformation/**'
       - 'docs/services/**'
       - 'tools/docs/**'
       - 'Makefile'
@@ -17,6 +20,7 @@ on:
       - main
     paths:
       - 'src/main/**'
+      - 'src/test/resources/cloudformation/**'
       - 'docs/services/**'
       - 'tools/docs/**'
       - 'Makefile'

Makefile

@@ -12,13 +12,20 @@ PYTHON ?= python3
 
 docs-sync: ## Regenerate the action tables in docs/services from handler source (in place)
 	$(PYTHON) tools/docs/regen_action_docs.py
+	$(PYTHON) tools/docs/regen_cfn_resource_types.py
 
 docs-check: ## CI gate: regenerate and fail if anything is stale, unregistered, or undocumented
 	@$(PYTHON) tools/docs/regen_action_docs.py --strict || { \
 		echo ""; \
 		echo "error: action-table regeneration reported problems (see warnings above)."; \
 		exit 1; \
 	}
+	@$(PYTHON) tools/docs/regen_cfn_resource_types.py --strict || { \
+		echo ""; \
+		echo "error: the CloudFormation resource-type table is stale or reported problems."; \
+		echo "       Run 'make docs-sync' and commit the result."; \
+		exit 1; \
+	}
 	@git diff --exit-code -- docs/ || { \
 		echo ""; \
 		echo "error: docs/services action tables are out of date."; \

docs/services/cloudformation.md

@@ -49,31 +49,32 @@ the backing service and sets a real physical ID plus the `Ref` / `Fn::GetAtt` at
 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.
+> Types live in per-service provisioners under `services/cloudformation/provisioners/`. This table
+> is generated from the provisioner inventory by `make docs-sync`; edit that, not the table.
 
+<!-- floci:cfn-types:start -->
 | Service | Resource types |
 |---|---|
 | S3 | `Bucket`, `BucketPolicy` (accepted; policy not enforced) |
 | SQS | `Queue`, `QueuePolicy` (accepted; policy not enforced) |
 | SNS | `Topic`, `Subscription` |
 | DynamoDB | `Table`, `GlobalTable` |
-| Lambda | `Function` (Zip via S3/inline `ZipFile`, and Image), `LayerVersion`, `EventSourceMapping` (SQS, Kinesis, DynamoDB Streams), `Version`, `Alias` (also what SAM's `AutoPublishAlias` expands into). Inline `ZipFile` packages include the `cfn-response` (Node.js) / `cfnresponse` (Python) module AWS injects for that code path, so Solutions-style custom-resource handlers work |
+| Lambda | `Function` (Zip via S3/inline `ZipFile`, and Image), `LayerVersion`, `EventSourceMapping` (SQS, Kinesis, DynamoDB Streams), `Version`, `Alias` (also what SAM's `AutoPublishAlias` expands into), `Permission`, `MicrovmImage`, `NetworkConnector`. Inline `ZipFile` packages include the `cfn-response` (Node.js) / `cfnresponse` (Python) module AWS injects for that code path, so Solutions-style custom-resource handlers work. |
 | IAM | `Role`, `User`, `AccessKey`, `Policy`, `ManagedPolicy`, `InstanceProfile` |
 | Organizations | `Organization`, `OrganizationalUnit`, `Account`, `Policy`, `ResourcePolicy` |
 | SSM | `Parameter` |
 | KMS | `Key`, `Alias` |
 | Secrets Manager | `Secret`, `SecretTargetAttachment` |
 | ECR | `Repository` |
-| ECS | `Cluster`, `TaskDefinition`, `Service` |
+| ECS | `Cluster`, `TaskDefinition`, `Service`, `CapacityProvider`, `ClusterCapacityProviderAssociations` |
 | EKS | `Cluster`, `Nodegroup` |
-| RDS | `DBInstance`, `DBCluster`, `DBSubnetGroup`, `DBParameterGroup`, `DBClusterParameterGroup` (DBInstance/DBCluster start real containers) |
-| EC2 | `VPC`, `Subnet`, `SecurityGroup` (including inline `SecurityGroupIngress`/`SecurityGroupEgress`), `SecurityGroupIngress`, `SecurityGroupEgress`, `InternetGateway`, `RouteTable`, `SubnetRouteTableAssociation`, `Route`, `NatGateway`, `EIP`, `Instance`, `LaunchTemplate`, `VPCGatewayAttachment`, `NetworkAcl`, `NetworkAclEntry`, `SubnetNetworkAclAssociation`, `FlowLog` |
+| RDS | `DBInstance` (starts a real container), `DBCluster` (starts a real container), `DBSubnetGroup`, `DBParameterGroup`, `DBClusterParameterGroup`, `DBProxy`, `DBProxyTargetGroup` |
+| EC2 | `VPC`, `Subnet`, `SecurityGroup` (inline `SecurityGroupIngress`/`SecurityGroupEgress` supported), `SecurityGroupIngress`, `SecurityGroupEgress`, `InternetGateway`, `RouteTable`, `SubnetRouteTableAssociation`, `Route`, `NatGateway`, `EIP`, `Instance`, `LaunchTemplate`, `VPCGatewayAttachment`, `VPCEndpoint`, `NetworkAcl`, `NetworkAclEntry`, `SubnetNetworkAclAssociation`, `FlowLog` |
 | Elastic Load Balancing v2 | `LoadBalancer`, `TargetGroup`, `Listener`, `ListenerRule` |
 | Auto Scaling | `LaunchConfiguration`, `AutoScalingGroup`, `LifecycleHook` |
 | Route 53 | `HostedZone`, `RecordSet` |
 | API Gateway (v1) | `RestApi`, `Resource`, `Authorizer`, `Method`, `Deployment`, `Stage`, `Account` |
-| API Gateway v2 | `Api`, `Route`, `Integration`, `Stage`, `Deployment` |
+| API Gateway v2 | `Api`, `Authorizer`, `Route`, `Integration`, `Stage`, `Deployment` |
 | Step Functions | `StateMachine` |
 | CodePipeline | `Pipeline`, `CustomActionType`, `Webhook` |
 | CodeBuild | `Project` |
@@ -83,12 +84,14 @@ cross-resource references.
 | Pipes | `Pipe` |
 | Kinesis | `Stream` |
 | Kinesis Data Firehose | `DeliveryStream` |
+| CloudFront | `Distribution` |
 | CloudWatch | `Alarm` |
 | CloudWatch Logs | `LogGroup` |
 | WAFv2 | `WebACL` |
 | Config | `ConfigRule` |
-| CloudFormation | `Stack` (nested stacks), `CustomResource` and `Custom::*` (Lambda-backed) |
+| CloudFormation | `CustomResource`, `Custom::DynamoDBReplica` (applied natively against DynamoDB, not via a provider Lambda), `Stack` (nested stacks), `Custom::*` (Lambda-backed) |
 | CDK | `CDK::Metadata` (accepted; no-op) |
+<!-- floci:cfn-types:end -->
 
 All other resource types are accepted without error and assigned a synthetic physical ID (with an
 `arn:aws:stub:::<logicalId>` ARN attribute), so templates with unsupported types still reach

tools/docs/cfn_resource_types.yaml

@@ -0,0 +1,165 @@
+# Presentation for the generated "Supported Resource Types" table in
+# docs/services/cloudformation.md. The set of types is NOT configured here: it comes from
+# src/test/resources/cloudformation/supported-resource-types.tsv, which CfnResourceInventoryTest
+# pins to the CDI-resolved provisioner registry and the legacy switch. This file only decides how
+# those types are labelled, ordered and annotated.
+#
+# Adding a resource type: add the provisioner, update the TSV, run `make docs-sync`. Touch this
+# file only for a new namespace (which needs a label) or to add a note.
+
+# Row order. Namespaces omitted here are appended alphabetically after these, so a forgotten
+# entry degrades to a sensible position rather than disappearing.
+order:
+  - AWS::S3
+  - AWS::SQS
+  - AWS::SNS
+  - AWS::DynamoDB
+  - AWS::Lambda
+  - AWS::IAM
+  - AWS::Organizations
+  - AWS::SSM
+  - AWS::KMS
+  - AWS::SecretsManager
+  - AWS::ECR
+  - AWS::ECS
+  - AWS::EKS
+  - AWS::RDS
+  - AWS::EC2
+  - AWS::ElasticLoadBalancingV2
+  - AWS::AutoScaling
+  - AWS::Route53
+  - AWS::ApiGateway
+  - AWS::ApiGatewayV2
+  - AWS::StepFunctions
+  - AWS::CodePipeline
+  - AWS::CodeBuild
+  - AWS::Batch
+  - AWS::Cognito
+  - AWS::Events
+  - AWS::Pipes
+  - AWS::Kinesis
+  - AWS::KinesisFirehose
+  - AWS::CloudFront
+  - AWS::CloudWatch
+  - AWS::Logs
+  - AWS::WAFv2
+  - AWS::Config
+  - AWS::CloudFormation
+  - Custom
+  - AWS::CDK
+
+# Namespaces folded into another row. Custom::* types are CloudFormation's own extension
+# mechanism, not a service of their own, so they belong in the CloudFormation row.
+merge_namespaces:
+  Custom: AWS::CloudFormation
+
+# Overrides the name shown for a type. Only needed where the bare leaf would be ambiguous.
+display_names:
+  AWS::CDK::Metadata: CDK::Metadata
+
+# Order of type names within a row. Listed names come first in this order; anything else is
+# appended alphabetically, so a newly provisioned type appears without needing an entry here.
+# Curated where the reading order carries meaning (primary resources before their accessories).
+type_order:
+  AWS::S3: [Bucket, BucketPolicy]
+  AWS::SQS: [Queue, QueuePolicy]
+  AWS::SNS: [Topic, Subscription]
+  AWS::DynamoDB: [Table, GlobalTable]
+  AWS::Lambda: [Function, LayerVersion, EventSourceMapping, Version, Alias, Permission]
+  AWS::IAM: [Role, User, AccessKey, Policy, ManagedPolicy, InstanceProfile]
+  AWS::Organizations: [Organization, OrganizationalUnit, Account, Policy, ResourcePolicy]
+  AWS::KMS: [Key, Alias]
+  AWS::SecretsManager: [Secret, SecretTargetAttachment]
+  AWS::ECS: [Cluster, TaskDefinition, Service]
+  AWS::EKS: [Cluster, Nodegroup]
+  AWS::RDS:
+    [DBInstance, DBCluster, DBSubnetGroup, DBParameterGroup, DBClusterParameterGroup]
+  AWS::EC2:
+    [VPC, Subnet, SecurityGroup, SecurityGroupIngress, SecurityGroupEgress, InternetGateway,
+     RouteTable, SubnetRouteTableAssociation, Route, NatGateway, EIP, Instance, LaunchTemplate,
+     VPCGatewayAttachment, VPCEndpoint, NetworkAcl, NetworkAclEntry, SubnetNetworkAclAssociation,
+     FlowLog]
+  AWS::ElasticLoadBalancingV2: [LoadBalancer, TargetGroup, Listener, ListenerRule]
+  AWS::AutoScaling: [LaunchConfiguration, AutoScalingGroup, LifecycleHook]
+  AWS::Route53: [HostedZone, RecordSet]
+  AWS::ApiGateway: [RestApi, Resource, Authorizer, Method, Deployment, Stage, Account]
+  AWS::ApiGatewayV2: [Api, Authorizer, Route, Integration, Stage, Deployment]
+  AWS::CodePipeline: [Pipeline, CustomActionType, Webhook]
+  AWS::Batch: [ComputeEnvironment, JobQueue, JobDefinition]
+  AWS::Cognito: [UserPool, UserPoolClient]
+  AWS::Events: [Rule, EventBus, EventBusPolicy]
+  AWS::CloudFormation: [CustomResource]
+
+# Namespace -> the service name shown in the Service column.
+service_labels:
+  AWS::ApiGateway: API Gateway (v1)
+  AWS::ApiGatewayV2: API Gateway v2
+  AWS::AutoScaling: Auto Scaling
+  AWS::Batch: Batch
+  AWS::CDK: CDK
+  AWS::CloudFormation: CloudFormation
+  AWS::CloudFront: CloudFront
+  AWS::CloudWatch: CloudWatch
+  AWS::CodeBuild: CodeBuild
+  AWS::CodePipeline: CodePipeline
+  AWS::Cognito: Cognito
+  AWS::Config: Config
+  AWS::DynamoDB: DynamoDB
+  AWS::EC2: EC2
+  AWS::ECR: ECR
+  AWS::ECS: ECS
+  AWS::EKS: EKS
+  AWS::ElasticLoadBalancingV2: Elastic Load Balancing v2
+  AWS::Events: EventBridge
+  AWS::IAM: IAM
+  AWS::KMS: KMS
+  AWS::Kinesis: Kinesis
+  AWS::KinesisFirehose: Kinesis Data Firehose
+  AWS::Lambda: Lambda
+  AWS::Logs: CloudWatch Logs
+  AWS::Organizations: Organizations
+  AWS::Pipes: Pipes
+  AWS::RDS: RDS
+  AWS::Route53: Route 53
+  AWS::S3: S3
+  AWS::SNS: SNS
+  AWS::SQS: SQS
+  AWS::SSM: SSM
+  AWS::SecretsManager: Secrets Manager
+  AWS::StepFunctions: Step Functions
+  AWS::WAFv2: WAFv2
+  Custom: CloudFormation
+
+# Parenthetical shown after a type name. Keyed by the full type.
+notes:
+  AWS::S3::BucketPolicy: accepted; policy not enforced
+  AWS::SQS::QueuePolicy: accepted; policy not enforced
+  AWS::Lambda::Function: Zip via S3/inline `ZipFile`, and Image
+  AWS::Lambda::EventSourceMapping: SQS, Kinesis, DynamoDB Streams
+  AWS::Lambda::Alias: also what SAM's `AutoPublishAlias` expands into
+  AWS::EC2::SecurityGroup: inline `SecurityGroupIngress`/`SecurityGroupEgress` supported
+  AWS::RDS::DBInstance: starts a real container
+  AWS::RDS::DBCluster: starts a real container
+  AWS::CDK::Metadata: accepted; no-op
+  Custom::DynamoDBReplica: applied natively against DynamoDB, not via a provider Lambda
+
+# Trailing prose appended to a row after its type list, for behaviour that belongs to the service
+# rather than to one type.
+row_notes:
+  AWS::Lambda: >-
+    Inline `ZipFile` packages include the `cfn-response` (Node.js) / `cfnresponse` (Python) module
+    AWS injects for that code path, so Solutions-style custom-resource handlers work.
+
+# Capabilities that belong in this table but are not provisioner types, so they cannot come from
+# the inventory. Each needs a reason, because an entry here is exempt from the drift check.
+extra_types:
+  AWS::CloudFormation:
+    - name: Stack
+      note: nested stacks
+      reason: >-
+        Handled by CloudFormationService as a child-stack lifecycle, not by a resource provisioner.
+    - name: Custom::*
+      note: Lambda-backed
+      reason: >-
+        A wildcard prefix, not an exact type. The registry is keyed by exact type, so this is
+        dispatched by a prefix branch and can never appear in the inventory.