Light, fluffy, and always free - The AWS Local Emulator alternative
docs(partition): document deployment, test coverage and known gaps (#5292)
Hector Venturada53fc1c051e
diff --git a/docs/configuration/partitions.md b/docs/configuration/partitions.mdindex e2f4312812..b84de1b8db 100644--- a/docs/configuration/partitions.md+++ b/docs/configuration/partitions.md@@ -33,6 +33,29 @@ A default region the vendored data does not know only warns. AWS launches regionthan the data is refreshed, and botocore's region-shape rules (`cn-*`, `us-gov-*`, ...)still place it; anything else falls back to `aws`, which is what the AWS SDKs do too.+### Running a China, GovCloud, ISO or EUSC deployment++Start Floci with a default region in the partition, then point clients at it with a region in+the same partition and an endpoint override:++```bash+docker run --rm -p 4566:4566 \+ -e FLOCI_DEFAULT_REGION=cn-north-1 \+ floci/floci:latest++AWS_DEFAULT_REGION=cn-north-1 bin/awslocal sts get-caller-identity+# "Arn": "arn:aws-cn:iam::000000000000:root"+```++With the AWS CLI directly, pass `--region cn-north-1 --endpoint-url http://localhost:4566`; with+an SDK, set the region and the endpoint override on the client. The override replaces the+partition's real host (`amazonaws.com.cn` here) for transport only: the SDK still signs for the+region you gave it, and that signing region is what places each request in its partition (see+below). If clients reach Floci on another host or port than `http://localhost:4566`, set+`FLOCI_BASE_URL` to match, or URLs Floci returns, such as SQS queue URLs and pre-signed URLs,+keep pointing at the default. `FLOCI_HOSTNAME` is enough when only the host differs: it replaces+the host and keeps the port.+## Which partition a request belongs toEach request's partition comes from the region in its SigV4 credential scope, exactly as@@ -166,12 +189,34 @@ partition.## How it is tested-Every partition-dependent rule has unit and integration tests over all eight partitions. On top-of that, the nightly Partition Compatibility workflow runs the Java SDK compatibility suite-against a Floci deployed with `FLOCI_DEFAULT_REGION=cn-north-1`, with the SDK clients signing for-`cn-north-1`, so the SDK's own China partition handling has to round-trip end to end. Its known-failures are listed in `.github/ci/compat-partition-allowlist-cn-north-1.txt`; the list only-shrinks.+- **The partition rules themselves** (partition and region lookup, ARN minting, hostnames,+ service principals, managed-policy rewriting, STS) have unit tests over all eight partitions.+- **Through the emulator**, IAM ARNs and Step Functions run in all eight partitions, and a smoke+ test creates one resource in every non-commercial partition for SNS, Kinesis, Firehose, API+ Gateway V2, ELBv2, Glue, IoT, ACM, CodeBuild, Batch and EFS and checks its ARN or host. A new+ service that mints ARNs or hosts needs a case there or a recorded exemption. Most other+ partition-dependent behaviour (S3 bucket rules, EC2 regions and DNS names, hosted zones, VPC+ endpoint names, Lambda layers, CloudFormation pseudo-parameters, strict mode) is tested in one or+ two partitions, nearly always China.+- **End to end**, the nightly Partition Compatibility workflow runs the Java SDK compatibility+ suite against a Floci deployed with `FLOCI_DEFAULT_REGION=cn-north-1`, with the SDK clients+ signing for `cn-north-1`, so the SDK's own China partition handling has to round-trip. Its list+ of known failures, `.github/ci/compat-partition-allowlist-cn-north-1.txt`, is empty, so any+ failure fails the run. No other partition, and no other compatibility suite (the Python, Go,+ Node and AWS CLI suites, CDK, Terraform, OpenTofu), runs outside the commercial partition.++## Known gaps++- **One process serving several partitions shares global state.** S3 bucket names are one+ namespace, and `ListBuckets` lists buckets created from every partition; IAM, Organizations,+ Route 53, CloudFront and the IAM Identity Center instance keep one set of resources per account,+ whichever partition a request is signed for. AWS keeps them per partition. A deployment that serves one partition is+ unaffected.+- **AWS managed policies** are the commercial catalog in every partition, with their ARNs and+ regional hosts rewritten; AWS publishes no per-partition list.+- **Client tooling** that computes partition values itself (CDK bootstrap and+ `AWS::Partition`, Terraform's `aws_partition`, SAM) is not tested outside the commercial+ partition, and neither is any partition but China end to end.## Open questionsdiff --git a/docs/services/api-gateway.md b/docs/services/api-gateway.mdindex 7c61fdce99..5809031a58 100644--- a/docs/services/api-gateway.md+++ b/docs/services/api-gateway.md@@ -522,6 +522,17 @@ setups, and `floci:override-id` wins when both are present. Every other tag is p---+## Partitions++Edge-optimized APIs and custom domains (`EDGE`) exist only in the commercial partition: China+has CloudFront but no edge-optimized API Gateway, and GovCloud, EUSC and the ISO partitions have+no CloudFront. Floci enforces this for custom domains only: creating a domain with `EDGE`, or+switching one to it, outside the commercial partition is a `BadRequestException`, and `REGIONAL`+domains work in every partition (private custom domains are not emulated). REST APIs are not+checked yet, so an `EDGE` REST API is still created in any partition. Invoke URLs use the+partition's DNS suffix+(`<api-id>.execute-api.cn-north-1.amazonaws.com.cn`). See [AWS Partitions](../configuration/partitions.md).+## Configuration| Variable | Default | Description |diff --git a/docs/services/iam.md b/docs/services/iam.mdindex 80f80f7913..1f17518426 100644--- a/docs/services/iam.md+++ b/docs/services/iam.md@@ -1265,6 +1265,14 @@ Three deviations to be aware of:service-linked mark comes from the action that minted the role rather than from its path. Sucha role stays fully modifiable, and `DeleteServiceLinkedRole` answers `NoSuchEntity` for it.+## Partitions++IAM is global, so its ARNs take the partition of the region a request is signed for:+`arn:aws-cn:iam::<account>:role/...` for a China-signed request. AWS managed policies keep the+`aws` owner in every partition (`arn:aws-cn:iam::aws:policy/ReadOnlyAccess`), with the commercial+catalog's documents rewritten for the partition. An assumed-role session stays in the partition+of the role it was issued for, whatever region later calls are signed for. See [AWS Partitions](../configuration/partitions.md).+## Configuration| Variable | Default | Description |diff --git a/docs/services/step-functions.md b/docs/services/step-functions.mdindex 4581c653c5..013dba33c1 100644--- a/docs/services/step-functions.md+++ b/docs/services/step-functions.md@@ -700,6 +700,13 @@ history is retained, and a previously running execution is marked `ABORTED` with`ExecutionAborted` event appended. After a further restart, the execution is already terminal, sono additional event is written.+## Partitions++Service integration resources carry the partition of the state machine's region+(`arn:aws-cn:states:::lambda:invoke` in China, as the CDK writes them), and Floci dispatches them+in every partition. State machine and execution ARNs follow the region they are created in. See+[AWS Partitions](../configuration/partitions.md).+## Configuration| Variable | Default | Description |diff --git a/docs/services/wafv2.md b/docs/services/wafv2.mdindex 33392a86c0..6f163e7a66 100644--- a/docs/services/wafv2.md+++ b/docs/services/wafv2.md@@ -50,7 +50,7 @@ Floci emulates the AWS WAF v2 management API. Web ACLs, IP sets, regex pattern s## Scope-WAF v2 resources are partitioned by `Scope`: `REGIONAL` (ALB, API Gateway, AppSync) or `CLOUDFRONT`. Pass `--scope` on every call; `CLOUDFRONT`-scoped requests must target `us-east-1` as on real AWS.+WAF v2 resources are partitioned by `Scope`: `REGIONAL` (ALB, API Gateway, AppSync) or `CLOUDFRONT`. Pass `--scope` on every call; `CLOUDFRONT`-scoped requests target the partition's CloudFront region (`us-east-1`, or `cn-northwest-1` in China) as on real AWS. The `CLOUDFRONT` scope exists only where CloudFront does, the commercial and China partitions; elsewhere it is a `WAFInvalidParameterException`. See [AWS Partitions](../configuration/partitions.md).## IP set addresses