feat(ssm): Parameters for resolving to versioned layers (#5754)

* feat(ssm): Parameters for resolving to versioned layers * add description block * fix typo * add docs * fix ssm placement --------- Co-authored-by: Leandro Damascena <[email protected]>
aws-powertools · Dec 20, 2024 · 1575b40 · 1575b40
1 parent 4e2e452
commit 1575b40
Show file tree

Hide file tree

Showing 2 changed files with 165 additions and 17 deletions.
diff --git a/.github/workflows/update_ssm.yml b/.github/workflows/update_ssm.yml
@@ -0,0 +1,109 @@
+# SSM Parameters update
+#
+# PROCESS
+# Creates parameters in regional AWS accounts for each layer we create, using the inputs to target specific releases
+# * environment: will prefix /beta/ into the parameter
+# * write_latest: will create a latest alias instead of a version number in the parameter
+# * package_version: semantic version number of the released layer (3.x.y)
+# * layer_version: this is sequential layer version from the ARN
+#
+# A successful parameter would look similar to:
+#   /aws/service/powertools/python/arm64/python3.8/3.1.0
+# And will have a value of:
+#   arn:aws:lambda:eu-west-1:017000801446:layer:AWSLambdaPowertoolsPythonV3-python38-arm64:4
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Environment to deploy to
+        type: choice
+        options:
+          - Beta
+          - Prod
+        required: true
+
+      write_latest:
+        description: Write to the latest path
+        type: boolean
+        required: false
+
+      package_version:
+        description: Semantic Version of published layer
+        type: string
+        required: true
+
+      layer_version:
+        description: Layer version
+        type: string
+        required: true
+
+name: SSM Parameters
+run-name: SSM Parameters - Python
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    environment: SSM
+    strategy:
+      matrix:
+        region: ["af-south-1", "ap-east-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3",
+            "ap-south-1", "ap-south-2", "ap-southeast-1", "ap-southeast-2", "ap-southeast-3",
+            "ap-southeast-4", "ca-central-1", "ca-west-1", "eu-central-1", "eu-central-2",
+            "eu-north-1", "eu-south-1", "eu-south-2", "eu-west-1", "eu-west-2", "eu-west-3",
+            "il-central-1", "me-central-1", "me-south-1", "sa-east-1", "us-east-1",
+            "us-east-2", "us-west-1", "us-west-2", "ap-southeast-5"
+          ]
+
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - id: transform
+        run: |
+          echo 'CONVERTED_REGION=${{ matrix.region }}' | tr 'a-z\-' 'A-Z_' >> "$GITHUB_OUTPUT"
+      - id: creds
+        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
+        with:
+          aws-region: ${{ matrix.region }}
+          role-to-assume: ${{ secrets[format('{0}', steps.transform.outputs.CONVERTED_REGION)] }}
+          mask-aws-account-id: true
+      - id: write-version
+        env:
+          prefix: ${{ inputs.environment == 'beta' && '/aws/service/powertools/beta' || '/aws/service/powertools' }}
+        run: |
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.8/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python38-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.9/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python39-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.10/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python310-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.11/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python311-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.12/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python312-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.13/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-arm64:${{ inputs.layer_version }}" --type String
+
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.8/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python38-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.9/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python39-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.10/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python310-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.11/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python311-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.12/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python312-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.13/${{ inputs.package_version }} --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:${{ inputs.layer_version }}" --type String
+
+      - id: write-latest
+        if: inputs.write_latest == true
+        env:
+          prefix: ${{ inputs.environment == 'beta' && '/aws/service/powertools/beta' || '/aws/service/powertools' }}
+        run: |
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.8/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python38-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.9/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python39-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.10/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python310-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.11/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python311-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.12/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python312-arm64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/arm64/python3.13/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-arm64:${{ inputs.layer_version }}" --type String
+
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.8/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python38-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.9/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python39-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.10/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python310-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.11/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python311-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.12/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python312-x86_64:${{ inputs.layer_version }}" --type String
+          aws ssm put-parameter --name ${{ env.prefix }}/python/x86_64/python3.13/latest --value "arn:aws:lambda:${{ matrix.region }}:017000801446:layer:AWSLambdaPowertoolsPythonV3-python313-x86_64:${{ inputs.layer_version }}" --type String
diff --git a/docs/index.md b/docs/index.md
@@ -72,32 +72,51 @@ You can install Powertools for AWS Lambda (Python) using your favorite dependenc
     | x86_64          | __arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:4__{: .copyMe}:clipboard:       |
     | ARM          | __arn:aws:lambda:{region}:017000801446:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:4__{: .copyMe}:clipboard: |
 
-=== "Lambda Layer (GovCloud)"
+    === "AWS Console"
 
-    [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that can contain additional code, pre-packaged dependencies, data,  or configuration files. We compile and optimize [all dependencies](#install), and remove duplicate dependencies [already available in the Lambda runtime](https://github.com/aws-powertools/powertools-lambda-layer-cdk/blob/d24716744f7d1f37617b4998c992c4c067e19e64/layer/Python/Dockerfile#L36){target="_blank"} to achieve the most optimal size.
+        You can add our layer using the [AWS Lambda Console _(direct link)_](https://console.aws.amazon.com/lambda/home#/add/layer){target="_blank"}:
 
-    For the latter, make sure to replace `{python_version}` without the period (.), e.g., `python313` for `Python 3.13`.
+        * Under Layers, choose `AWS layers` or `Specify an ARN`
+        * Click to copy the [correct ARN](#lambda-layer) value based on your AWS Lambda function architecture and region
 
-    **AWS GovCloud (us-gov-east-1)**
 
-    | Architecture | Layer ARN                                                                                                 |
-    | ------------ | --------------------------------------------------------------------------------------------------------- |
-    | x86_64          | __arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:4__{: .copyMe}:clipboard:       |
-    | ARM          | __arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:4__{: .copyMe}:clipboard: |
+    === "AWS SSM Parameter Store"
+        We offer Parameter Store aliases for releases too, allowing you to specify either specific versions or use the latest version on every deploy. To use these you can add these snippets to your AWS CloudFormation or Terraform projects:
 
-    **AWS GovCloud (us-gov-west-1)**
+        **CloudFormation**
 
-    | Architecture | Layer ARN                                                                                                 |
-    | ------------ | --------------------------------------------------------------------------------------------------------- |
-    | x86_64          | __arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:4__{: .copyMe}:clipboard:       |
-    | ARM          | __arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:4__{: .copyMe}:clipboard: |
+        Sample Placeholders:
 
-    === "AWS Console"
+        - `{arch}` is either `arm64` (Graviton based functions) or `x86_64`
+        - `{python_version}` is the Python version without the period (.), e.g., `python313` for `Python 3.13`.
+        - `{version}` is the semantic version number (e,g. 3.1.0) for a release or `latest`
 
-        You can add our layer using the [AWS Lambda Console _(direct link)_](https://console.aws.amazon.com/lambda/home#/add/layer){target="_blank"}:
+        ```yaml
+        MyFunction:
+            Type: "AWS::Lambda::Function"
+            Properties:
+                ...
+                Layers:
+                - {{resolve:ssm:/aws/service/powertools/python/{arch}/{python_version}/{version}}}
+        ```
 
-        * Under Layers, choose `AWS layers` or `Specify an ARN`
-        * Click to copy the [correct ARN](#lambda-layer) value based on your AWS Lambda function architecture and region
+        **Terraform**
+
+        Using the [`aws_ssm_parameter`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) data provider from the AWS Terraform provider allows you to lookup the value of parameters to use later in your project.
+
+        ```hcl
+        data "aws_ssm_parameter" "powertools_version" {
+            name = "/aws/service/powertools/python/{arch}/{python_version}/{version}"
+        }
+
+        resource "aws_lambda_function" "test_lambda" {
+            ...
+
+            runtime = "python3.13"
+
+            layers = [data.aws_ssm_parameter.powertools_version.value]
+        }
+        ```
 
     === "Infrastructure as Code (IaC)"
 
@@ -191,6 +210,26 @@ You can install Powertools for AWS Lambda (Python) using your favorite dependenc
 
         You'll find the pre-signed URL under `Location` key as part of the CLI command output.
 
+=== "Lambda Layer (GovCloud)"
+
+    [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html){target="_blank"} is a .zip file archive that can contain additional code, pre-packaged dependencies, data,  or configuration files. We compile and optimize [all dependencies](#install), and remove duplicate dependencies [already available in the Lambda runtime](https://github.com/aws-powertools/powertools-lambda-layer-cdk/blob/d24716744f7d1f37617b4998c992c4c067e19e64/layer/Python/Dockerfile#L36){target="_blank"} to achieve the most optimal size.
+
+    For the latter, make sure to replace `{python_version}` without the period (.), e.g., `python313` for `Python 3.13`.
+
+    **AWS GovCloud (us-gov-east-1)**
+
+    | Architecture | Layer ARN                                                                                                 |
+    | ------------ | --------------------------------------------------------------------------------------------------------- |
+    | x86_64          | __arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:4__{: .copyMe}:clipboard:       |
+    | ARM          | __arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:4__{: .copyMe}:clipboard: |
+
+    **AWS GovCloud (us-gov-west-1)**
+
+    | Architecture | Layer ARN                                                                                                 |
+    | ------------ | --------------------------------------------------------------------------------------------------------- |
+    | x86_64          | __arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-x86_64:4__{: .copyMe}:clipboard:       |
+    | ARM          | __arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsPythonV3-{python_version}-arm64:4__{: .copyMe}:clipboard: |
+
 === "Serverless Application Repository (SAR)"
 
     We provide a SAR App that deploys a CloudFormation stack with a copy of our Lambda Layer in your AWS account and region.