AWS AppConfig integration with Lambda extensions - AWS AppConfig

AWS AppConfig integration with Lambda extensions

An AWS Lambda extension is a companion process that augments the capabilities of a Lambda function. An extension can start before a function is invoked, run in parallel with a function, and continue to run after a function invocation is processed. In essence, a Lambda extension is like a client that runs in parallel to a Lambda invocation. This parallel client can interface with your function at any point during its lifecycle.

If you use AWS AppConfig to manage configurations for a Lambda function, then we recommend that you add the AWS AppConfig Lambda extension. This extension includes best practices that simplify using AWS AppConfig while reducing costs. Reduced costs result from fewer API calls to the AWS AppConfig service and, separately, reduced costs from shorter Lambda function processing times.

This topic includes information about the AWS AppConfig Lambda extension and the procedure for how to configure the extension to work with your Lambda function. For more information about Lambda extensions, see Lambda extensions in the AWS Lambda Developer Guide.

How it works

If you use AWS AppConfig to manage configurations for a Lambda function without Lambda extensions, then you must configure your Lambda function to receive configuration updates by integrating with the GetConfiguration API action. You integrate using the AWS SDK. The call to GetConfiguration includes the IDs of the AWS AppConfig application, the environment, the configuration profile, and a unique client ID.

You should also ensure that each call to GetConfiguration includes the ClientConfigurationVersion parameter. AWS AppConfig uses the value of this parameter to identify the configuration version used by AWS Lambda. If you don’t include the ClientConfigurationVersion parameter, you will incur additional charges for using AWS AppConfig.

You are charged for each call to the GetConfiguration API. You are also charged for Lambda processing, rounded up to the nearest 100 ms.

Integrating the AWS AppConfig Lambda extension with your Lambda function simplifies this process and reduces costs. The following diagram shows how it works.


                    A diagram of how the AWS AppConfig Lambda extension works
  1. You configure the AWS AppConfig Lambda extension as a layer of your Lambda function.

  2. The extension receives the GetConfiguration request from the function and checks the local cache. The local cache is an HTTP server.

  3. The cache is empty so the extension passes the call to the SDK, which calls the AWS AppConfig service.

  4. Upon receiving the configuration from the service, the extension stores it in the local cache and passes it to the Lambda function.

  5. The extension locates and returns subsequent calls to GetConfiguration from the local cache. The AWS AppConfig Lambda extension manages configuration caching and updating so the configuration persists between Lambda handler invocations. When a configuration is needed, the Lambda handler makes a request to the AWS AppConfig Lambda extension instead of the AWS AppConfig service. The configuration is cached locally and returns much faster, which reduces the cost of using AWS Lambda and AWS AppConfig.

The next time the Lambda function is invoked, the extension checks the elapsed time since it retrieved a configuration from AWS AppConfig. If the elapsed time is greater than the poll interval, the extension retrieves the latest configuration from AWS AppConfig and updates the cache.

Before you begin

Before you enable the AWS AppConfig Lambda extension, do the following:

  • Organize the dynamic configurations in your Lambda function so that you can externalize them into AWS AppConfig.

  • Configure AWS AppConfig to manage your configuration updates. For more information, see Working with AWS AppConfig.

  • You must add appconfig:GetConfiguration to the AWS Identity and Access Management (IAM) policy used by the Lambda function execution role. For more information, see AWS Lambda execution role in the AWS Lambda Developer Guide. For more information about AWS AppConfig permissions, see Configuring permissions for AWS AppConfig.

Note the following details about using the AWS AppConfig Lambda extension.

Note
  • The amount of time it takes for a configuration change to appear in a Lambda function, after you deploy an updated configuration from AWS AppConfig, depends on the deployment strategy you used for the deployment and the polling interval you configured for the extension.

  • AWS Lambda logs execution information about the AWS AppConfig Lambda extension along with the Lambda function by using Amazon CloudWatch Logs.

  • AWS Lambda records the ExtensionDurationOverhead metric. This metric measures extra time used by the extension after the function runs. For more information, see Monitoring and troubleshooting Lambda applications in the AWS Lambda Developer Guide.

Also, you can configure the extension by changing the following AWS Lambda environment variables, which are described in the following table. For more information, see Using AWS Lambda environment variables in the AWS Lambda Developer Guide.

Environment variable Details Default value

AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS

This environment variable controls how often the extension polls AWS AppConfig for an updated configuration in seconds.

45

AWS_APPCONFIG_EXTENSION_POLL_TIMEOUT_MILLIS

This environment variable controls the maximum amount of time the extension waits before retrieving configurations from the cache in milliseconds.

3000

AWS_APPCONFIG_EXTENSION_HTTP_PORT

This environment variable specifies the port on which the local HTTP server that hosts the extension runs.

2772

Adding the AWS AppConfig Lambda extension

To use the AWS AppConfig Lambda extension, you add the extension to your Lambda function as a layer. For information about how to add a layer to your function, see Configuring extensions in the AWS Lambda Developer Guide. The name of the extension in the AWS Lambda console is AWS-AppConfig-Extension. Also note that when you add the extension as a layer to your Lambda, you must specify an Amazon Resource Name (ARN). Choose an ARN from the following list that corresponds with the AWS Region where you created the Lambda.

Region ARN

US East (N. Virginia)

arn:aws:lambda:us-east-1:027255383542:layer:AWS-AppConfig-Extension:11

US East (Ohio)

arn:aws:lambda:us-east-2:728743619870:layer:AWS-AppConfig-Extension:15

US West (N. California)

arn:aws:lambda:us-west-1:958113053741:layer:AWS-AppConfig-Extension:11

US West (Oregon)

arn:aws:lambda:us-west-2:359756378197:layer:AWS-AppConfig-Extension:18

Canada (Central)

arn:aws:lambda:ca-central-1:039592058896:layer:AWS-AppConfig-Extension:15

Europe (Frankfurt)

arn:aws:lambda:eu-central-1:066940009817:layer:AWS-AppConfig-Extension:19

Europe (Ireland)

arn:aws:lambda:eu-west-1:434848589818:layer:AWS-AppConfig-Extension:11

Europe (London)

arn:aws:lambda:eu-west-2:282860088358:layer:AWS-AppConfig-Extension:15

Europe (Paris)

arn:aws:lambda:eu-west-3:493207061005:layer:AWS-AppConfig-Extension:15

Europe (Stockholm)

arn:aws:lambda:eu-north-1:646970417810:layer:AWS-AppConfig-Extension:19

Europe (Milan)

arn:aws:lambda:eu-south-1:203683718741:layer:AWS-AppConfig-Extension:15

Asia Pacific (Hong Kong)

arn:aws:lambda:ap-east-1:630222743974:layer:AWS-AppConfig-Extension:15

Asia Pacific (Tokyo)

arn:aws:lambda:ap-northeast-1:980059726660:layer:AWS-AppConfig-Extension:12

Asia Pacific (Seoul)

arn:aws:lambda:ap-northeast-2:826293736237:layer:AWS-AppConfig-Extension:19

Asia Pacific (Singapore)

arn:aws:lambda:ap-southeast-1:421114256042:layer:AWS-AppConfig-Extension:12

Asia Pacific (Sydney)

arn:aws:lambda:ap-southeast-2:080788657173:layer:AWS-AppConfig-Extension:19

Asia Pacific (Mumbai)

arn:aws:lambda:ap-south-1:554480029851:layer:AWS-AppConfig-Extension:20

South America (São Paulo)

arn:aws:lambda:sa-east-1:000010852771:layer:AWS-AppConfig-Extension:11

Africa (Cape Town)

arn:aws:lambda:af-south-1:574348263942:layer:AWS-AppConfig-Extension:15

Middle East (Bahrain)

arn:aws:lambda:me-south-1:559955524753:layer:AWS-AppConfig-Extension:15

Note

The AWS AppConfig Lambda extension is only available in AWS Regions where AWS AppConfig is available.

If you want to test the extension before you add it to your function, you can verify that it works by using the following code example.

import urllib.request def lambda_handler(event, context): url = f'http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name' config = urllib.request.urlopen(url).read() return config

To test it, create a new Lambda function for Python, add the extension, and then run the Lambda function. After you run the Lambda function, the AppConfig Lambda function returns the configuration you specified for the http://localhost:2772 path. For information about creating a Lambda function, see Create a Lambda function with the console in the AWS Lambda Developer Guide.

Integrating with OpenAPI

You can use the following YAML specification for OpenAPI to create an SDK using a tool like OpenAPI Generator. You can update this specification to include hard-coded values for Application, Environment, or Configuration. You can also add additional paths (if you have multiple configuration types) and include configuration schemas to generate configuration-specific typed models for your SDK clients. For more information about OpenAPI (which is also known as Swagger), see the OpenAPI specification.

openapi: 3.0.0 info: version: 1.0.0 title: AWS AppConfig Lambda extension API description: An API model for AWS AppConfig Lambda extension. servers: - url: https://localhost:{port}/ variables: port: default: '2772' paths: /applications/{Application}/environments/{Environment}/configurations/{Configuration}: get: operationId: getConfiguration tags: - configuration parameters: - in: path name: Application description: The application for the configuration to get. Specify either the application name or the application ID. required: true schema: type: string - in: path name: Environment description: The environment for the configuration to get. Specify either the environment name or the environment ID. required: true schema: type: string - in: path name: Configuration description: The configuration to get. Specify either the configuration name or the configuration ID. required: true schema: type: string responses: 200: headers: ConfigurationVersion: schema: type: string content: application/octet-stream: schema: type: string format: binary description: successful config retrieval 400: description: BadRequestException content: application/text: schema: $ref: '#/components/schemas/Error' 404: description: ResourceNotFoundException content: application/text: schema: $ref: '#/components/schemas/Error' 500: description: InternalServerException content: application/text: schema: $ref: '#/components/schemas/Error' 502: description: BadGatewayException content: application/text: schema: $ref: '#/components/schemas/Error' 504: description: GatewayTimeoutException content: application/text: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: string description: The response error