Using AWS AppConfig Agent with Amazon ECS and Amazon EKS
You can integrate AWS AppConfig with Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS) by using AWS AppConfig Agent. The agent functions as a sidecar container running alongside your Amazon ECS and Amazon EKS container applications. The agent enhances containerized application processing and management in the following ways:
-
The agent calls AWS AppConfig on your behalf by using an AWS Identity and Access Management (IAM) role and managing a local cache of configuration data. By pulling configuration data from the local cache, your application requires fewer code updates to manage configuration data, retrieves configuration data in milliseconds, and isn't affected by network issues that can disrupt calls for such data.*
-
The agent offers a native experience for retrieving and resolving AWS AppConfig feature flags.
-
Out of the box, the agent provides best practices for caching strategies, polling intervals, and local configuration data availability while tracking the configuration tokens needed for subsequent service calls.
-
While running in the background, the agent periodically polls the AWS AppConfig data plane for configuration data updates. Your containerized application can retrieve the data by connecting to localhost on port 2772 (a customizable default port value) and calling HTTP GET to retrieve the data.
-
AWS AppConfig Agent updates configuration data in your containers without having to restart or recycle those containers.
*AWS AppConfig Agent caches data the first time the service retrieves your configuration data. For this reason, the first call to retrieve data is slower than subsequent calls.
Before you begin
To integrate AWS AppConfig with your container applications, you must create AWS AppConfig artifacts and configuration data, including feature flags or freeform configuration data. For more information, see Creating feature flags and free form configuration data in AWS AppConfig.
To retrieve configuration data hosted by AWS AppConfig, your container applications must be
configured with access to the AWS AppConfig data plane. To give your applications access, update
the IAM permissions policy that is used by your container service IAM role.
Specifically, you must add the appconfig:StartConfigurationSession
and
appconfig:GetLatestConfiguration
actions to the policy. Container service
IAM roles include the following:
-
The Amazon ECS task role
-
The Amazon EKS node role
-
The AWS Fargate (Fargate) pod execution role (if your Amazon EKS containers use Fargate for compute processing)
For more information about adding permissions to a policy, see Adding and removing IAM identity permissions in the IAM User Guide.
Topics
Starting the AWS AppConfig agent for Amazon ECS integration
The AWS AppConfig Agent sidecar container is automatically available in your Amazon ECS environment. To use it, you must start it, as described in the following procedure.
To start Amazon ECS (console)
Open the console at https://console.aws.amazon.com/ecs/v2
. -
In the navigation pane, choose Task definitions.
-
Choose the task definition for your application, and then select the latest revision.
-
Choose Create new revision, Create new revision.
-
Choose Add more containers.
-
For Name, enter a unique name for the AWS AppConfig Agent container.
-
For Image URI, enter:
public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x
-
For Essential container, choose Yes.
-
In the Port mappings section, choose Add port mapping.
-
For Container port, enter
2772
.Note
AWS AppConfig Agent runs on port 2772, by default. You can specify a different port.
-
Choose Create. Amazon ECS creates a new container revision and displays the details.
-
In the navigation pane, choose Clusters, and then choose your application cluster in the list.
-
On the Services tab, select the service for your application.
-
Choose Update.
-
Under Deployment configuration, for Revision, choose the latest revision.
-
Choose Update. Amazon ECS deploys the latest task definition.
-
After the deployment finishes, you can verify that AWS AppConfig Agent is running on the Configuration and tasks tab. On the Tasks tab, choose the running task.
-
In the Containers section, verify that the AWS AppConfig Agent container is listed.
-
To verify that AWS AppConfig Agent started, choose the Logs tab. Locate a statement like the following for the AWS AppConfig Agent container:
[appconfig agent] 1970/01/01 00:00:00 INFO serving on localhost:2772
Note
You can adjust the default behavior of AWS AppConfig Agent by entering or changing environment variables. For information about the available environment variables, see (Optional) Using environment variables to configure AWS AppConfig Agent for Amazon ECS and Amazon EKS. For information about how to change environment variables in Amazon ECS, see Passing environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Starting the AWS AppConfig agent for Amazon EKS integration
The AWS AppConfig Agent sidecar container is automatically available in your Amazon EKS
environment. To use it, you must start it. The following procedure describes how to use
the Amazon EKS kubectl
command line tool to start the agent.
Note
Before you continue, ensure that your kubeconfig
file is up to date.
For more information about creating or editing a kubeconfig
file, see
Creating
or updating a kubeconfig file for an Amazon EKS cluster in the
Amazon EKS User Guide.
To start AWS AppConfig Agent (kubectl command line tool)
-
Open the manifest for your application and verify that your Amazon EKS application is running as a single-container deployment. Contents of the file should look similar to the following.
apiVersion: apps/v1 kind: Deployment metadata: name:
my-app
namespace:my-namespace
labels: app:my-application-label
spec: replicas: 1 selector: matchLabels: app:my-application-label
template: metadata: labels: app:my-application-label
spec: containers: - name:my-app
image:my-repo
/my-image
imagePullPolicy: IfNotPresent -
Add the AWS AppConfig Agent container definition details to your deployment manifest.
- name: appconfig-agent image: public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x ports: - name: http containerPort: 2772 protocol: TCP env: - name:
SERVICE_REGION
value: region imagePullPolicy: IfNotPresentNote
Note the following information.
-
AWS AppConfig Agent runs on port 2772, by default. You can specify a different port.
-
You can adjust the default behavior of AWS AppConfig Agent by entering environment variables. For more information, see (Optional) Using environment variables to configure AWS AppConfig Agent for Amazon ECS and Amazon EKS.
-
For
SERVICE_REGION
, specify the AWS Region code (for example,us-west-1
) where AWS AppConfig Agent retrieves configuration data.
-
-
Run the following
kubectl
command to apply the changes to your cluster. Replacemy-deployment
with the name of your deployment manifest.kubectl apply -f
my-deployment
.yml -
After the deployment finishes, verify that AWS AppConfig Agent is running. Use the following command to view the application pod log file.
kubectl logs -n
my-namespace
-c appconfig-agentmy-pod
Locate a statement like the following for the AWS AppConfig Agent container:
[appconfig agent] 1970/01/01 00:00:00 INFO serving on localhost:2772
Note
You can adjust the default behavior of AWS AppConfig Agent by entering or changing environment variables. For information about the available environment variables, see (Optional) Using environment variables to configure AWS AppConfig Agent for Amazon ECS and Amazon EKS.
(Optional) Using environment variables to configure AWS AppConfig Agent for Amazon ECS and Amazon EKS
You can configure AWS AppConfig Agent by changing the following environment variables for your agent container.
Environment variable | Details | Default value |
---|---|---|
|
This environment variable defines a token that must be provided when
requesting configuration data from the agent HTTP server. The value of the token
must be set in the HTTP request authorization header with an authorization type
of
|
None |
|
This environment variable enables AWS AppConfig Agent to save a backup of each configuration it retrieves to the specified directory. ImportantConfigurations backed up to disk are not encrypted. If your configuration contains sensitive data, AWS AppConfig recommends that you practice the principle of least privilege with your filesystem permissions. For more information, see Security in AWS AppConfig. |
None |
|
This environment variable specifies the port on which the HTTP server for the agent runs. |
2772 |
|
This environment variable specifies the level of detail that the agent logs.
Each level includes the current level and all higher levels. The variables are
case sensitive. From most to least detailed, the log levels are:
|
|
|
The disk location where logs are written. If not specified, logs are written to stderr. |
None |
|
This environment variable configures AWS AppConfig Agent to take advantage of additional per-configuration features like multi-account retrievals and save configuration to disk. You can enter one of the following values:
For more information about these features, see Using a manifest to enable additional retrieval features. |
true |
|
This environment variable configures the maximum number of connections that the agent uses to retrieve configurations from AWS AppConfig. |
3 |
|
This environment variable controls how often the agent polls AWS AppConfig for updated configuration data. You can specify a number of seconds for the interval. You can also specify a number with a time unit: s for seconds, m for minutes, and h for hours. If a unit isn't specified, the agent defaults to seconds. For example, 60, 60s, and 1m result in the same poll interval. |
45 seconds |
|
This environment variable specifies the configuration data the agent requests from AWS AppConfig as soon as it starts. |
None |
|
If set to |
true |
PROXY_HEADERS |
This environment variable specifies headers that are required by the proxy
referenced in the PROXY_URL environment variable. The value is a
comma-separated list of headers. Each header uses the following form.
|
None |
PROXY_URL |
This environment variable specifies the proxy URL to use for connections from
the agent to AWS services, including AWS AppConfig. HTTPS and
HTTP URLs are supported. |
None |
|
This environment variable controls the amount of time the agent waits for a response from AWS AppConfig. If the service does not respond, the request fails. If the request is for the initial data retrieval, the agent returns an error to your application. If the timeout occurs during a background check for updated data, the agent logs the error and tries again after a short delay. You can specify the number of milliseconds for the timeout. You can also specify a number with a time unit: ms for milliseconds and s for seconds. If a unit isn't specified, the agent defaults to milliseconds. As an example, 5000, 5000ms and 5s result in the same request timeout value. |
3000 milliseconds |
ROLE_ARN |
This environment variable specifies the Amazon Resource Name (ARN) of an IAM role. AWS AppConfig Agent assumes this role to retrieve configuration data. | None |
ROLE_EXTERNAL_ID |
This environment variable specifies the external ID to use with the assumed role ARN. | None |
ROLE_SESSION_NAME |
This environment variable specifies the session name to be associated with the credentials for the assumed IAM role. | None |
SERVICE_REGION |
This environment variable specifies an alternative AWS Region that AWS AppConfig Agent uses to call the AWS AppConfig service. If left undefined, the agent attempts to determine the current Region. If it can't, the agent fails to start. | None |
|
This environment variable configures AWS AppConfig Agent to wait until the manifest is processed before completing startup. |
true |
Retrieving configuration data
You can retrieve configuration data from AWS AppConfig Agent by using an HTTP localhost call.
The following examples use curl
with an HTTP client. You can call the agent
using any available HTTP client supported by your application language or available
libraries.
Note
To retrieve configuration data if your application uses a forward slash, for example "test-backend/test-service", you will need to use URL encoding.
To retrieve the full content of any deployed configuration
$ curl "http://localhost:2772/applications/
application_name
/environments/environment_name
/configurations/configuration_name
"
To retrieve a single flag and its attributes from an AWS AppConfig
configuration of type Feature Flag
$ curl "http://localhost:2772/applications/
application_name
/environments/environment_name
/configurations/configuration_name
?flag=flag_name
"
To access multiple flags and their attributes from an AWS AppConfig
configuration of type Feature Flag
$ curl "http://localhost:2772/applications/
application_name
/environments/environment_name
/configurations/configuration_name
?flag=flag_name_one
&flag=flag_name_two
"