fix(docs): keep China layer versions aligned (#8438)

Stage the installation page in release documentation updates and constrain ARN replacements by partition. This keeps China aligned without advancing GovCloud or implying continued Python 3.9 releases.

Fixes GH-8437

Author: dreamorosi

.github/workflows/publish_v3_layer.yml

@@ -284,7 +284,7 @@ jobs:
         id: create-pr
         uses: ./.github/actions/create-pr
         with:
-          files: "docs/index.md docs/includes/_layer_homepage_arm64.md docs/includes/_layer_homepage_x86.md examples CHANGELOG.md"
+          files: "docs/index.md docs/getting-started/install.md docs/includes/_layer_homepage_arm64.md docs/includes/_layer_homepage_x86.md examples CHANGELOG.md"
           temp_branch_prefix: "ci-layer-docs"
           pull_request_title: "chore(ci): layer docs update"
           github_token: ${{ secrets.GITHUB_TOKEN }}

docs/getting-started/install.md

@@ -84,12 +84,12 @@ We publish `prerelease` versions to PyPi for early feedback on unstable releases
 
 [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that contains pre-packaged dependencies. We compile and optimize all dependencies for both x86_64 and ARM architectures.
 
-Replace `{region}` with your AWS region (e.g., `eu-west-1`) and `{python_version}` without the period (e.g., `python313` for Python 3.13).
+Replace `{region}` with your AWS region (e.g., `eu-west-1`) and `{python_version}` with a currently supported runtime: `python310`, `python311`, `python312`, `python313`, or `python314`. Python 3.9 layers stopped at layer version 27.
 
 | Architecture | Layer ARN |
 | ------------ | --------- |
-| x86_64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` |
-| ARM64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` |
+| x86_64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:37` |
+| ARM64 | `arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:37` |
 
 ### All regional Layer ARNs
 
@@ -101,7 +101,7 @@ Replace `{region}` with your AWS region (e.g., `eu-west-1`) and `{python_version
 
 ??? tip "Want to inspect the Layer contents?"
     ```bash
-    aws lambda get-layer-version-by-arn --arn arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:27 --region eu-west-1
+    aws lambda get-layer-version-by-arn --arn arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:37 --region eu-west-1
     ```
     The pre-signed URL will be in the `Location` key.
 
@@ -167,8 +167,8 @@ We publish Layer ARNs to SSM Parameter Store for easier automation:
 
 | Region | Architecture | Layer ARN |
 | ------ | ------------ | --------- |
-| cn-north-1 | x86_64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:27` |
-| cn-north-1 | ARM64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:27` |
+| cn-north-1 | x86_64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:37` |
+| cn-north-1 | ARM64 | `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:37` |
 
 ### AWS GovCloud regions
 

docs/maintainers.md

@@ -170,9 +170,9 @@ Releasing a new version is a multi-step process that takes up to 2 hours to comp
 1. **Run [end-to-end tests](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/run-e2e-tests.yml)** and ensure they pass
 2. **Trigger Release v3 workflow** - Run the [`Release v3`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/release-v3.yml) workflow with two inputs: the new Powertools version (check [latest version](https://pypi.org/project/aws-lambda-powertools/)) and the new Lambda Layer version number. To find the new Lambda Layer version number, go to this [page](https://docs.powertools.aws.dev/lambda/python/latest/#python-313) and increase the version by one (N + 1).
 3. **Monitor the release workflow** - it runs tests, publishes to PyPI, deploys Lambda layers to Beta and Prod environments across all commercial regions, runs canary tests, and updates documentation. If it fails, see the [Re-run partial failed Release workflow](#re-run-partial-failed-release-workflow) section
-4. **Review and merge documentation/version PRs** - two PRs will be created to update documentation and bump version files. Review, approve and merge both (order doesn't matter)
-5. **Deploy GovCloud layers** - Run the [`Layer Deployment (GovCloud)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layer_govcloud.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2.
-6. **Deploy China layers** - Run the [`Layer Deployment (Partitions)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layers_partitions.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2.
+4. **Deploy GovCloud layers** - Run the [`Layer Deployment (GovCloud)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layer_govcloud.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2.
+5. **Deploy China layers** - Run the [`Layer Balancer (Partitions)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layers_partition_balance.yml) workflow for each supported Python runtime with the `develop` branch, `Prod` environment, `China` partition, both architectures, and the Layer version number from step 2. Run it first as a dry run, then publish after it succeeds.
+6. **Review and merge documentation/version PRs** - two PRs will be created to update documentation and bump version files. Review, approve and merge both after the partition deployments succeed (order doesn't matter).
 7. **Update documentation** - Run the [`Rebuild latest docs`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/rebuild_latest_docs.yml) workflow with `develop` branch and the PyPI package version
 
 Once complete, you can start drafting the release notes to let customers know **what changed and what's in it for them (a.k.a why they should care)**. We have guidelines in the [release notes](#drafting-release-notes) section so you know what good looks like.

layer_v3/scripts/update_layer_arn_v3.sh

@@ -2,8 +2,9 @@
 
 # This script is run during the publish_v3_layer.yml CI job,
 # and it is responsible for replacing the layer ARN in our documentation.
-# Our pipeline must generate the same layer number for all commercial regions + gov cloud
-# If this doesn't happens, we have an error and we must fix it in the deployment.
+# Our pipeline must generate the same layer number for all commercial regions.
+# China mirrors that version, and its documentation PR is merged after deployment.
+# GovCloud layer versions are updated independently.
 #
 # see .github/workflows/reusable_deploy_v3_layer_stack.yml
 
@@ -29,16 +30,12 @@ find ./docs ./examples -type f \( -name "*.md" -o -name "*.py" -o -name "*.yaml"
     # The regex matches the layer name and replaces only the version number at the end
 
     # Commercial AWS (arn:aws:lambda)
-    sed -i -E "s/(AWSLambdaPowertoolsPythonV3-python[0-9]+-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
-    sed -i -E "s/(AWSLambdaPowertoolsPythonV3-{python_version}-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
-    
+    sed -i -E "s/(arn:aws:lambda:[^[:space:]]*:layer:AWSLambdaPowertoolsPythonV3-python[0-9]+-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
+    sed -i -E "s/(arn:aws:lambda:[^[:space:]]*:layer:AWSLambdaPowertoolsPythonV3-{python_version}-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
+
     # AWS China (arn:aws-cn:lambda)
-    sed -i -E "s/(arn:aws-cn:lambda:[^:]+:[^:]+:layer:AWSLambdaPowertoolsPythonV3-python[0-9]+-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
-    sed -i -E "s/(arn:aws-cn:lambda:[^:]+:[^:]+:layer:AWSLambdaPowertoolsPythonV3-{python_version}-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
-    
-    # AWS GovCloud (arn:aws-us-gov:lambda)
-    sed -i -E "s/(arn:aws-us-gov:lambda:[^:]+:[^:]+:layer:AWSLambdaPowertoolsPythonV3-python[0-9]+-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
-    sed -i -E "s/(arn:aws-us-gov:lambda:[^:]+:[^:]+:layer:AWSLambdaPowertoolsPythonV3-{python_version}-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
+    sed -i -E "s/(arn:aws-cn:lambda:[^[:space:]]*:layer:AWSLambdaPowertoolsPythonV3-python[0-9]+-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
+    sed -i -E "s/(arn:aws-cn:lambda:[^[:space:]]*:layer:AWSLambdaPowertoolsPythonV3-{python_version}-((arm64)|(x86_64)):)[0-9]+/\1$new_version/g" "$file"
 
     if [ $? -eq 0 ]; then
         echo "Updated $file successfully"