# 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.\$1 + 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. \$1AWS 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](creating-feature-flags-and-configuration-data.md). 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 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *IAM User Guide*. **Topics** + [Starting the AWS AppConfig agent for Amazon ECS integration](appconfig-integration-containers-agent-starting-ecs.md) + [Starting the AWS AppConfig agent for Amazon EKS integration](appconfig-integration-containers-agent-starting-eks.md) + [(Optional) Running AWS AppConfig as a DaemonSet in Amazon EKS](appconfig-integration-containers-agent-daemon.md) + [(Optional) Using environment variables to configure AWS AppConfig Agent for Amazon ECS and Amazon EKS](appconfig-integration-containers-agent-configuring.md) + [Retrieving configuration data for applications running in Amazon ECS and Amazon EKS](appconfig-integration-containers-agent-retrieving-data.md) # 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)** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Task definitions**. 1. Choose the task definition for your application, and then select the latest revision. 1. Choose **Create new revision**, **Create new revision**. 1. Choose **Add more containers**. 1. For** Name**, enter a unique name for the AWS AppConfig Agent container. 1. For **Image URI**, enter: **public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x** 1. For **Essential container**, choose **Yes**. 1. In the **Port mappings** section, choose **Add port mapping**. 1. For **Container port**, enter **2772**. **Note** AWS AppConfig Agent runs on port 2772, by default. You can specify a different port. 1. Choose **Create**. Amazon ECS creates a new container revision and displays the details. 1. In the navigation pane, choose **Clusters**, and then choose your application cluster in the list. 1. On the **Services** tab, select the service for your application. 1. Choose **Update**. 1. Under **Deployment configuration**, for **Revision**, choose the latest revision. 1. Choose **Update**. Amazon ECS deploys the latest task definition. 1. 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. 1. In the **Containers** section, verify that the AWS AppConfig Agent container is listed. 1. 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** Note the following information. AWS AppConfig Agent is a long-running process. As a best practice for Amazon ECS containers, configure health checks for your containers, specifically setting the container dependency to the HEALTHY condition. For more information, see [ContainerDependency](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html) in the *Amazon Elastic Container Service API Reference*. 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](appconfig-integration-containers-agent-configuring.md). For information about how to change environment variables in Amazon ECS, see [Passing environment variables to a container](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html) 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](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html) in the **Amazon EKS User Guide**. **To start AWS AppConfig Agent (kubectl command line tool)** 1. 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 ``` 1. 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: AWS Region imagePullPolicy: IfNotPresent ``` **Note** 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](appconfig-integration-containers-agent-configuring.md). For *AWS Region*, specify the AWS Region code (for example, `us-west-1`) where AWS AppConfig Agent retrieves configuration data. 1. Run the following `kubectl` command to apply the changes to your cluster. Replace *my-deployment* with the name of your deployment manifest. ``` kubectl apply -f my-deployment.yml ``` 1. 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-agent my-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](appconfig-integration-containers-agent-configuring.md). # (Optional) Running AWS AppConfig as a DaemonSet in Amazon EKS With Amazon EKS, you can run AWS AppConfig Agent as a sidecar, which results in one agent container *per application pod*. Or, if you prefer, you can run AWS AppConfig Agent as a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), which results in one agent container *per node in your cluster*. **Note** If you run AWS AppConfig Agent as a DaemonSet, the agent runs in a separate pod, which means you can't access it with calls to `localhost`. You must inject or otherwise discover the agent pod's IP address in order to call it. To run AWS AppConfig Agent as a DaemonSet, create a manifest file with the following contents. Replace *highlighted* text with details for your application and environment. For *AWS Region*, specify an AWS Region code (for example, `us-west-1`). ``` apiVersion: apps/v1 kind: DaemonSet metadata: name: aws-appconfig-agent namespace: my_namespace labels: app: my_application_label spec: selector: matchLabels: app: my_application_label template: metadata: labels: app: my_application_label spec: containers: - name: aws-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: AWS Region imagePullPolicy: IfNotPresent # set a high priority class to ensure the agent is running on every node priorityClassName: system-node-critical ``` Run the following command to apply the AWS AppConfig Agent DaemonSet to your cluster. Replace *aws\$1appconfig\$1agent\$1daemonset* with the name of your DaemonSet manifest. ``` kubectl apply -f aws_appconfig_agent_daemonset.yml ``` # (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. **Note** The following table includes a **Sample values** column. Depending on your monitor resolution, you might need to scroll to the bottom of the table and then scroll to the right to view the column. **** | Environment variable | Details | Default value | Sample value(s) | | --- | --- | --- | --- | | `ACCESS_TOKEN` | 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 `Bearer`. Here is an example. 
GET /applications/my_app/...
                  Host: localhost:2772
                  Authorization: Bearer
| None | MyAccessToken | | `BACKUP_DIRECTORY` | This environment variable enables AWS AppConfig Agent to save a backup of each configuration it retrieves to the specified directory. Configurations 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](appconfig-security.md). | None | /path/to/backups | | `HTTP_PORT` | This environment variable specifies the port on which the HTTP server for the agent runs. | 2772 | 2772 | | `HTTP_HOST` | The HTTP\$1HOST variable controls how the AWS AppConfig Agent binds to network interfaces. The binding behavior differs based on the runtime environment to ensure optimal security and accessibility. | ECS, EKS [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-containers-agent-configuring.html) EC2 and on-prem [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-containers-agent-configuring.html) | Custom Configuration Options. You can override the default behavior using these values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-containers-agent-configuring.html) | | `LOG_LEVEL` | This environment variable specifies the level of detail that the agent logs. Each level includes the current level and all higher levels. The value is case insensitive. From most to least detailed, the log levels are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `none`. The `trace` log includes detailed information, including timing information, about the agent. | info | trace debug info warn error fatal none | | `LOG_PATH` | The disk location where logs are written. If not specified, logs are written to stderr. | None | /path/to/logs/agent.log | | `MANIFEST` | This environment variable configures AWS AppConfig Agent to take advantage of additional per-configuration features like multi-account retrievals and save configuration to disk. For more information about these features, see [Using a manifest to enable additional retrieval features](appconfig-agent-how-to-use-additional-features.md). | None | When using AWS AppConfig configuration as manifest: `MyApp:MyEnv:MyManifestConfig`.When loading manifest from disk: `file:/path/to/manifest.json` | | `MAX_CONNECTIONS` | This environment variable configures the maximum number of connections that the agent uses to retrieve configurations from AWS AppConfig. | 3 | 3 | | `POLL_INTERVAL` | 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 | 4545s5m1h | | `PREFETCH_LIST` | This environment variable specifies the configuration data the agent requests from AWS AppConfig as soon as it starts. Multiple configuration identifiers may be provided in a comma-separated list. | None | MyApp:MyEnv:MyConfigabcd123:efgh456:ijkl789MyApp:MyEnv:Config1,MyApp:MyEnv:Config2 | | `PRELOAD_BACKUPS` | If set to `true`, AWS AppConfig Agent loads configuration backups found in the `BACKUP_DIRECTORY` into memory and immediately checks to see if a newer version exists from the service. If set to `false`, AWS AppConfig Agent only loads the contents from a configuration backup if it cannot retrieve configuration data from the service, for example if there is a problem with your network. | true | true false | | PROXY\$1HEADERS | This environment variable specifies headers that are required by the proxy referenced in the PROXY\$1URL environment variable. The value is a comma-separated list of headers. | None | header: value h1: v1, h2: v2 | | PROXY\$1URL | 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 | http://localhost:7474https://my-proxy.example.com | | `REQUEST_TIMEOUT` | 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. | 3000ms | 30003000ms5s | | ROLE\$1ARN | This environment variable specifies the Amazon Resource Name (ARN) of an IAM role. AWS AppConfig Agent assumes this role to retrieve configuration data. | None | arn:aws:iam::123456789012:role/MyRole | | ROLE\$1EXTERNAL\$1ID | This environment variable specifies the external ID to use with the assumed role ARN. | None | MyExternalId | | ROLE\$1SESSION\$1NAME | This environment variable specifies the session name to be associated with the credentials for the assumed IAM role. | None | AWSAppConfigAgentSession | | SERVICE\$1REGION | 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 | us-east-1eu-west-1 | | `WAIT_ON_MANIFEST` | This environment variable configures AWS AppConfig Agent to wait until the manifest is processed before completing startup. | true | truefalse | # Retrieving configuration data for applications running in Amazon ECS and Amazon EKS You can retrieve configuration data from AWS AppConfig Agent for applications running in Amazon ECS and Amazon EKS 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" ``` The call returns configuration metadata in HTTP headers, including the configuration version, content type, and configuration version label (if applicable). The body of the agent response contains the configuration content. Here is an example: ``` HTTP/1.1 200 OK Configuration-Version: 1 Content-Type: application/json Date: Tue, 18 Feb 2025 20:20:16 GMT Content-Length: 31 My test config ```