Retrieving configuration data using the Amazon AppConfig Agent Lambda extension

An Amazon 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 Amazon AppConfig feature flags or other dynamic configuration data in a Lambda function, then we recommend that you add the Amazon AppConfig Agent Lambda extension as a layer to your Lambda function. This makes calling feature flags simpler, and the extension itself includes best practices that simplify using Amazon AppConfig while reducing costs. Reduced costs result from fewer API calls to the Amazon AppConfig service and shorter Lambda function processing times. For more information about Lambda extensions, see Lambda extensions in the Amazon Lambda Developer Guide.

This topic includes information about the Amazon AppConfig Agent Lambda extension and the procedure for how to configure the extension to work with your Lambda function.

How it works

If you use Amazon 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 StartConfigurationSession and GetLatestConfiguration API actions.

Integrating the Amazon AppConfig Agent Lambda extension with your Lambda function simplifies this process. The extension takes care of calling the Amazon AppConfig service, managing a local cache of retrieved data, tracking the configuration tokens needed for the next service calls, and periodically checking for configuration updates in the background. The following diagram shows how it works.

Before you begin

Before you enable the Amazon AppConfig Agent Lambda extension, do the following:

Adding the Amazon AppConfig Agent Lambda extension

To use the Amazon AppConfig Agent Lambda extension, you need to add the extension to your Lambda. This can be done by adding the Amazon AppConfig Agent Lambda extension to your Lambda function as a layer or by enabling the extension on a Lambda function as a container image.

Adding the Amazon AppConfig Agent Lambda extension by using a layer and an ARN

To use the Amazon AppConfig Agent 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 Amazon Lambda Developer Guide. The name of the extension in the Amazon Lambda console is Amazon-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 one of the following lists that corresponds with the platform and Amazon Web Services Region where you created the Lambda.

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 Amazon 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 Amazon Lambda Developer Guide.

To add the Amazon AppConfig Agent Lambda extension as a container image, see Using a container image to add the Amazon AppConfig Agent Lambda extension.

Configuring the Amazon AppConfig Agent Lambda extension

You can configure the extension by changing the following Amazon Lambda environment variables. For more information, see Using Amazon Lambda environment variables in the Amazon Lambda Developer Guide.

Prefetching configuration data

The environment variable AWS_APPCONFIG_EXTENSION_PREFETCH_LIST can improve the start-up time of your function. When the Amazon AppConfig Agent Lambda extension is initialized, it retrieves the specified configuration from Amazon AppConfig before Lambda starts to initialize your function and invoke your handler. In some cases, the configuration data is already available in the local cache before your function requests it.

To use the prefetch capability, set the value of the environment variable to the path corresponding to your configuration data. For example, if your configuration corresponds to an application, environment, and configuration profile respectively named "my_application", "my_environment", and "my_configuration_data", the path would be /applications/my_application/environments/my_environment/configurations/my_configuration_data. You can specify multiple configuration items by listing them as a comma-separated list (If you have a resource name that includes a comma, use the resource’s ID value instead of its name).

Accessing configuration data from another account

The Amazon AppConfig Agent Lambda extension can retrieve configuration data from another account by specifying an IAM role that grants permissions to the data. To set this up, follow these steps:

"header: value"

Retrieving one or more flags from a feature flag configuration

For feature flag configurations (configurations of type AWS.AppConfig.FeatureFlags), the Lambda extension enables you to retrieve a single flag or a subset of flags in a configuration. Retrieving one or two flags is useful if your Lambda only needs to use a few flags from the configuration profile. The following examples use Python.

You can retrieve Amazon AppConfig configuration data from a local HTTP endpoint. To access a specific flag or a list of flags, use the ?flag=flag_name query parameter for an Amazon AppConfig configuration profile.

To access a single flag and its attributes

import urllib.request

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

To access multiple flags and their attributes

import urllib.request

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

Viewing Amazon AppConfig Agent Lambda extension logs

You can view log data for the Amazon AppConfig Agent Lambda extension in the Amazon Lambda logs. Log entries are prefaced with appconfig agent. Here's an example.

[appconfig agent] 2024/05/07 04:19:01 ERROR retrieve failure for 'SourceEventConfig:SourceEventConfigEnvironment:SourceEventConfigProfile': StartConfigurationSession: api error AccessDenied: User: arn:aws:sts::0123456789:assumed-role/us-east-1-LambdaRole/extension1 is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::0123456789:role/test1 (retry in 60s)