Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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 region
than 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 to
Each 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 questions
diff --git a/docs/services/api-gateway.md b/docs/services/api-gateway.md
index 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.md
index 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. Such
a 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.md
index 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, so
no 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.md
index 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