improv(ci): verify output of Layer deployment (Partitions) GitHub Action (aws-powertools#4308)

Co-authored-by: Stefano Vozza <[email protected]>

Author: sdangol

.github/workflows/layers_partitions.yml

@@ -5,6 +5,16 @@
 # We pull each the version of the layer and store them as artifacts, the we upload them to each of the Partitioned AWS accounts.
 #
 # A number of safety checks are performed to ensure safety.
+#
+# === Automated activities ===
+# 1. [Setup] configure partition-specific regions, partition names, and STS audience based on target partition (China/GovCloud)
+# 2. [Download] retrieve the specified layer version from the main AWS partition (us-east-1) and store as artifacts
+# 3. [Copy & Verify] deploy the layer to all regions in the target partition and validate layer deployment by comparing SHA256, description, and version numbers
+#
+# === Manual activities ===
+# 1. After the `make-release` workflow finishes and the PR for the documentation update gets created, trigger this workflow manually via `workflow_dispatch` with environment, version, and partition inputs for each Gamma and Prod environment in the China and GovCloud partitions
+# 2. Monitor deployment progress and verify successful layer publication across all target regions
+# 3. Once this workflow is completed, the PR for the documentation update can me merged
 
 on:
   workflow_dispatch:
@@ -44,6 +54,7 @@ permissions:
   contents: read
 
 jobs:
+  # This job configures partition-specific settings including regions, partition names, and STS audience based on the target partition (China or GovCloud) selected in the workflow inputs.
   setup:
     runs-on: ubuntu-latest
     outputs:
@@ -65,6 +76,7 @@ jobs:
           echo regions='["us-gov-east-1", "us-gov-west-1"]'>> "$GITHUB_OUTPUT"
           echo partition='aws-us-gov'>> "$GITHUB_OUTPUT"
           echo aud='sts.amazonaws.com'>> "$GITHUB_OUTPUT"
+  # This job downloads the specified layer version from the main AWS partition (us-east-1) and stores both the layer zip file and metadata as GitHub Actions artifacts for use in deployment.
   download:
     runs-on: ubuntu-latest
     permissions:
@@ -96,7 +108,7 @@ jobs:
           path: AWSLambdaPowertoolsTypeScriptV2.json
           retention-days: 1
           if-no-files-found: error
-
+  # This job deploys the layer to all regions in the target partition using a matrix strategy. It performs integrity checks, publishes the layer, sets public permissions, and validates deployment.
   copy:
     name: Copy
     needs: 
@@ -153,6 +165,11 @@ jobs:
             --action lambda:GetLayerVersion \
             --principal '*' \
             --version-number "$LAYER_VERSION"
+      # This step retrieves the newly deployed layer metadata and compares it against the original source layer:
+      # 1. SHA256 hash verification - ensures the layer content is identical to the source
+      # 2. Description validation - confirms the version number in the description matches the source
+      # 3. Layer Version number verification - validates that the layer version numbers match between source and target
+      # 4. Tabular comparison output - displays side-by-side comparison of key layer properties
       - name: Verify Layer
         env:
           LAYER_VERSION: ${{ steps.create-layer.outputs.LAYER_VERSION }}
@@ -162,6 +179,12 @@ jobs:
           REMOTE_SHA=$(jq -r '.Content.CodeSha256' $layer_output)
           LOCAL_SHA=$(jq -r '.Content.CodeSha256' AWSLambdaPowertoolsTypeScriptV2.json)
           test "$REMOTE_SHA" == "$LOCAL_SHA" && echo "SHA OK: ${LOCAL_SHA}" || exit 1
+          REMOTE_DESCRIPTION=$(jq -r '.Description' $layer_output)
+          LOCAL_DESCRIPTION=$(jq -r '.Description' AWSLambdaPowertoolsTypeScriptV2.json)
+          test "$REMOTE_DESCRIPTION" == "$LOCAL_DESCRIPTION" && echo "Version number OK: ${LOCAL_DESCRIPTION}" || exit 1
+          REMOTE_LAYER_VERSION=$(jq -r '.LayerVersionArn' $layer_output | sed 's/.*://')
+          LOCAL_LAYER_VERSION=$(jq -r '.LayerVersionArn' AWSLambdaPowertoolsTypeScriptV2.json | sed 's/.*://')
+          test "$REMOTE_LAYER_VERSION" == "$LOCAL_LAYER_VERSION" && echo "Layer Version number OK: ${LOCAL_LAYER_VERSION}" || exit 1
           jq -s -r '["Layer Arn", "Runtimes", "Version", "Description", "SHA256"], ([.[0], .[1]] | .[] | [.LayerArn, (.CompatibleRuntimes | join("/")), .Version, .Description, .Content.CodeSha256]) |@tsv' AWSLambdaPowertoolsTypeScriptV2.json $layer_output | column -t -s $'\t'
 
       - name: Store Metadata - ${{ matrix.region }}

docs/maintainers.md

@@ -179,50 +179,32 @@ layer version that was deployed, as this will be used in the next steps.
 5. **Publish GovCloud Layers (Gamma)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch,
 targeting the `Gamma` deployment environment and the GovCloud partition, using the Lambda layer version from the
 step 4. This will publish the Lambda layers to the AWS GovCloud (US-East) and AWS GovCloud (US-West) Regions.
-6. **Verify GovCloud Layers (Gamma)**: Download the `AWSLambdaPowertoolsTypeScriptV2-us-gov-east-1.json` and
-`AWSLambdaPowertoolsTypeScriptV2-us-gov-west-1.json` ZIP files. Unzip the files, inspect the JSON files therein and
-ensure the version number in the `Description` field (i.e., `Powertools for AWS Lambda (TypeScript) version 2.20.0`)
-and the layer version in the `LayerVersionArn` field (i.e., `arn:aws-us-gov:lambda:us-gov-east-1:164754790254:layer:AWSLambdaPowertoolsTypeScriptV2:32`)
-are correct.
-7. **Publish GovCloud Layers (Prod)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch,
+6. **Publish GovCloud Layers (Prod)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch,
 targeting the `Prod` deployment environment and the GovCloud partition, using the Lambda layer version from step 4.
 This will publish the Lambda layers to the AWS GovCloud (US-East) and AWS GovCloud (US-West) Regions.
-8. **Verify GovCloud Layers (Prod)**: Download the `AWSLambdaPowertoolsTypeScriptV2-us-gov-east-1.json` and
-`AWSLambdaPowertoolsTypeScriptV2-us-gov-west-1.json` ZIP files. Unzip the files, inspect the JSON files therein and
-ensure the version number in the `Description` field (i.e., `Powertools for AWS Lambda (TypeScript) version 2.20.0`)
-and the layer version in the `LayerVersionArn` field (i.e., `arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsTypeScriptV2:32`)
-are correct.
-9. **Publish China Layer (Gamma)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch, targeting
+7. **Publish China Layer (Gamma)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch, targeting
 the `Gamma` deployment environment and the China partition, using the Lambda layer version from step 4. This will
 publish the Lambda layer to the AWS China (Beijing) Region.
-10. **Verify China Layer (Gamma)**: Download the `AWSLambdaPowertoolsTypeScriptV2-cn-north-1.json` ZIP file. Unzip
-the file, inspect the JSON file therein and ensure the version number in the `Description` field
-(i.e., `Powertools for AWS Lambda (TypeScript) version 2.20.0`) and the layer version in the `LayerVersionArn` field
-(i.e., `arn:aws-cn:lambda:cn-north-1:498595349401:layer:AWSLambdaPowertoolsTypeScriptV2:32`) are correct.
-11. **Publish China Layer (Prod)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch,
+8. **Publish China Layer (Prod)**: Run the `Layer Deployment (Partitions)` workflow with the `main` branch,
 targeting the `Prod` deployment environment and the China partition, and using the Lambda layer version from step 4.
 This will publish the Lambda layer to the AWS China (Beijing) Region.
-12. **Verify China Layer (Prod)**: Download the `AWSLambdaPowertoolsTypeScriptV2-cn-north-1.json` ZIP file. Unzip the
-file, inspect the JSON file therein and ensure the version number in the `Description` field
-(i.e., `Powertools for AWS Lambda (TypeScript) version 2.20.0`) and the layer version in the `LayerVersionArn`
-field (i.e., `arn:aws-cn:lambda:cn-north-1:498634801083:layer:AWSLambdaPowertoolsTypeScriptV2:32`) are correct.
-13. **Merge docs PR**: Once the `Layer Deployment (Partition)` workflow for the production China partition is complete,
+9. **Merge docs PR**: Once the `Layer Deployment (Partition)` workflow for the production China partition is complete,
 merge the PR from step 4 to update the documentation with the new version.
-14. **Update SSM Parameters (Beta)**: Run the `SSM Parameters` workflow with the `main` branch, targeting the `beta`
+10. **Update SSM Parameters (Beta)**: Run the `SSM Parameters` workflow with the `main` branch, targeting the `beta`
 deployment environment, and using the package version from npm (i.e., `2.20.0`) and Lambda layer version from step 4.
 This will update the SSM parameters with the new version.
-15. **Verify SSM Parameters (Beta)**: Use the AWS CLI to verify that the SSM parameters were updated correctly. Run
+11. **Verify SSM Parameters (Beta)**: Use the AWS CLI to verify that the SSM parameters were updated correctly. Run
 the following command: `aws ssm get-parameter --name=/aws/service/powertools/beta/typescript/generic/all/latest`
 and `aws ssm get-parameter --name=/aws/service/powertools/beta/typescript/generic/all/<version>` to verify that the
 SSM parameters were updated correctly.
-16. **Update SSM Parameters (Prod)**: Run the `SSM Parameters` workflow with the `main` branch, targeting the `prod`
+12. **Update SSM Parameters (Prod)**: Run the `SSM Parameters` workflow with the `main` branch, targeting the `prod`
 deployment environment, and using the package version from npm (i.e., `2.20.0`) and Lambda layer version from step 4.
 This will update the SSM parameters with the new version.
-17. **Verify SSM Parameters (Prod)**: Use the AWS CLI to verify that the SSM parameters were updated correctly. Run
+13. **Verify SSM Parameters (Prod)**: Use the AWS CLI to verify that the SSM parameters were updated correctly. Run
 the following command: `aws ssm get-parameter --name=/aws/service/powertools/typescript/generic/all/latest`
 and `aws ssm get-parameter --name=/aws/service/powertools/typescript/generic/all/<version>` to verify that the
 SSM parameters were updated correctly.
-18. **Update Docs**: Run the `Rebuild latest docs` workflow with the `main` branch using the package version from
+14. **Update Docs**: Run the `Rebuild latest docs` workflow with the `main` branch using the package version from
 npm (i.e. `2.20.0`). This will update the documentation with the new 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 section so you know what good looks like.