Retrieving configuration data without Amazon AppConfig Agent
On Nov 18, 2021, Amazon AppConfig released a new data plane service. This service replaces the
previous process of retrieving configuration data by using the GetConfiguration
API action. The data plane service uses two new API actions, StartConfigurationSession and GetLatestConfiguration. The data plane service also uses new
endpoints.
If you started using Amazon AppConfig before January 28, 2022, the service might be calling the
GetConfiguration
API action directly or it might be using a client provided by
Amazon, such as the Amazon AppConfig Agent Lambda extension, to call this API action. If you call the
GetConfiguration
API action directly, take steps to use the
StartConfigurationSession
and GetLatestConfiguration
API actions.
If you are using the Amazon AppConfig Agent Lambda extension, see the section titled How this
change impacts the Amazon AppConfig Agent Lambda extension later in this topic.
The new data plane API actions offer the following benefits over the
GetConfiguration
API action, which is now deprecated.
-
You don't need to manage a
ClientID
parameter. With the data plane service,ClientID
is managed internally by the session token created byStartConfigurationSession
. -
You no longer need to include
ClientConfigurationVersion
to indicate the cached version of your configuration data. With the data plane service,ClientConfigurationVersion
is managed internally by the session token created byStartConfigurationSession
. -
The new dedicated endpoint for data plane API calls improves code structure by separating control plane and data plane calls.
-
The new data plane service improves future extensibility for data plane operations. By utilizing a configuration session that manages configuration data retrieval, the Amazon AppConfig team can create more powerful enhancements in the future.
Migrating from GetConfiguration
to
GetLatestConfiguration
To start using the new data plane service, you need to update your code that calls the
GetConfiguration
API action. Start a configuration session by using the
StartConfigurationSession
API action, and then call the
GetLatestConfiguration
API action to retrieve configuration data. To improve
performance, we recommend you cache your configuration data locally. For more information,
see Retrieving configurations by
directly calling APIs.
How this change impacts the Amazon AppConfig Agent Lambda extension
This change has no direct impact on how the Amazon AppConfig Agent Lambda extension works. Older
versions of the Amazon AppConfig Agent Lambda extension called the GetConfiguration
API
action on your behalf. Newer versions call the data plane API actions. If you are using the
Amazon AppConfig Lambda extension, we recommend you update your extension to the most recent Amazon
Resource Name (ARN) and update permissions for the new API calls. For more information, see
Using Amazon AppConfig Agent with
Amazon Lambda.
Retrieving configurations by directly calling APIs
Your application retrieves configuration data by first establishing a configuration session using the StartConfigurationSession API operation. Your session's client then makes periodic calls to GetLatestConfiguration to check for and retrieve the latest data available.
When calling StartConfigurationSession
, your code sends the following
information:
-
Identifiers (ID or name) of an Amazon AppConfig application, environment, and configuration profile that the session tracks.
-
(Optional) The minimum amount of time the session's client must wait between calls to
GetLatestConfiguration
.
In response, Amazon AppConfig provides an InitialConfigurationToken
to be given to
the session's client and used the first time it calls GetLatestConfiguration
for that session.
Important
This token should only be used once in your first call to
GetLatestConfiguration
. You must use the new token in
the GetLatestConfiguration
response (NextPollConfigurationToken
)
in each subsequent call to GetLatestConfiguration
. To support long poll use
cases, the tokens are valid for up to 24 hours. If a GetLatestConfiguration
call uses an expired token, the system returns BadRequestException
.
When calling GetLatestConfiguration
, your client code sends the most recent
ConfigurationToken
value it has and receives in response:
-
NextPollConfigurationToken
: theConfigurationToken
value to use on the next call toGetLatestConfiguration
. -
NextPollIntervalInSeconds
: the duration the client should wait before making its next call toGetLatestConfiguration
. -
The configuration: the latest data intended for the session. This may be empty if the client already has the latest version of the configuration.
Important
Note the following important information.
-
The StartConfigurationSession API should only be called once per application, environment, configuration profile, and client to establish a session with the service. This is typically done in the startup of your application or immediately prior to the first retrieval of a configuration.
-
If your configuration is deployed using a
KmsKeyIdentifier
, your request to receive the configuration must include permission to callkms:Decrypt
. For more information, see Decrypt in the Amazon Key Management Service API Reference. -
The API operation previously used to retrieve configuration data,
GetConfiguration
, is deprecated. TheGetConfiguration
API operation does not support encrypted configurations.
Retrieving a configuration example
The following Amazon CLI example demonstrates how to retrieve configuration data by using
the Amazon AppConfig Data StartConfigurationSession
and
GetLatestConfiguration
API operations. The first command starts a
configuration session. This call includes the IDs (or names) of the Amazon AppConfig application,
the environment, and the configuration profile. The API returns an
InitialConfigurationToken
used to fetch your configuration data.
aws appconfigdata start-configuration-session \ --application-identifier
application_name_or_ID
\ --environment-identifierenvironment_name_or_ID
\ --configuration-profile-identifierconfiguration_profile_name_or_ID
The system responds with information in the following format.
{ "InitialConfigurationToken":
initial configuration token
}
After starting a session, use InitialConfigurationToken to call GetLatestConfiguration to fetch your configuration data. The configuration data
is saved to the mydata.json
file.
aws appconfigdata get-latest-configuration \ --configuration-token
initial configuration token
mydata.json
The first call to GetLatestConfiguration
uses the
ConfigurationToken
obtained from StartConfigurationSession
.
The following information is returned.
{ "NextPollConfigurationToken" :
next configuration token
, "ContentType" :content type of configuration
, "NextPollIntervalInSeconds" :60
}
Subsequent calls to GetLatestConfiguration
must provide NextPollConfigurationToken
from the
previous response.
aws appconfigdata get-latest-configuration \ --configuration-token
next configuration token
mydata.json
Important
Note the following important details about the GetLatestConfiguration
API operation:
-
The
GetLatestConfiguration
response includes aConfiguration
section that shows the configuration data. TheConfiguration
section only appears if the system finds new or updated configuration data. If the system doesn't find new or updated configuration data, then theConfiguration
data is empty. -
You receive a new
ConfigurationToken
in every response fromGetLatestConfiguration
. -
We recommend tuning the polling frequency of your
GetLatestConfiguration
API calls based on your budget, the expected frequency of your configuration deployments, and the number of targets for a configuration.