Retrieving configuration data from Amazon ECS and Amazon EKS - Amazon AppConfig
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Retrieving configuration data from Amazon ECS and Amazon EKS

You can integrate Amazon AppConfig with Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS) by using Amazon 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 Amazon AppConfig on your behalf by using an Amazon 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 Amazon 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 Amazon 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.

  • Amazon AppConfig Agent updates configuration data in your containers without having to restart or recycle those containers.

*Amazon 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 Amazon AppConfig with your container applications, you must create Amazon 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 Amazon AppConfig.

To retrieve configuration data hosted by Amazon AppConfig, your container applications must be configured with access to the Amazon 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 Amazon 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.

Starting the Amazon AppConfig agent for Amazon ECS integration

The Amazon AppConfig Agent sidecar container is automatically available in your Amazon ECS environment. To use the Amazon AppConfig Agent sidecar container, you must start it.

To start Amazon ECS (console)
  1. Open the console at https://console.amazonaws.cn/ecs/v2.

  2. In the navigation pane, choose Task definitions.

  3. Choose the task definition for your application, and then select the latest revision.

  4. Choose Create new revision, Create new revision.

  5. Choose Add more containers.

  6. For Name, enter a unique name for the Amazon AppConfig Agent container.

  7. For Image URI, enter: public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x

  8. For Essential container, choose Yes.

  9. In the Port mappings section, choose Add port mapping.

  10. For Container port, enter 2772.

    Note

    Amazon AppConfig Agent runs on port 2772, by default. You can specify a different port.

  11. Choose Create. Amazon ECS creates a new container revision and displays the details.

  12. In the navigation pane, choose Clusters, and then choose your application cluster in the list.

  13. On the Services tab, select the service for your application.

  14. Choose Update.

  15. Under Deployment configuration, for Revision, choose the latest revision.

  16. Choose Update. Amazon ECS deploys the latest task definition.

  17. After the deployment finishes, you can verify that Amazon AppConfig Agent is running on the Configuration and tasks tab. On the Tasks tab, choose the running task.

  18. In the Containers section, verify that the Amazon AppConfig Agent container is listed.

  19. To verify that Amazon AppConfig Agent started, choose the Logs tab. Locate a statement like the following for the Amazon AppConfig Agent container: [appconfig agent] 1970/01/01 00:00:00 INFO serving on localhost:2772

Note

You can adjust the default behavior of Amazon AppConfig Agent by entering or changing environment variables. For information about the available environment variables, see Using environment variables to configure Amazon 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 Amazon AppConfig agent for Amazon EKS integration

The Amazon AppConfig Agent sidecar container is automatically available in your Amazon EKS environment. To use the Amazon AppConfig Agent sidecar container, you must start it. The following procedure describes how to use the Amazon EKS kubectl command line tool to make changes in the kubeconfig file for your container application. 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 Amazon AppConfig Agent (kubectl command line tool)
  1. Open your kubeconfig file and verify that your Amazon EKS application is running as a single-container deployment. The 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
  2. Add the Amazon AppConfig Agent container definition details to your YAML deployment file.

    - 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: IfNotPresent
    Note

    Note the following information.

  3. Run the following command in the kubectl tool to apply the changes to your cluster.

    kubectl apply -f my-deployment.yml
  4. After the deployment finishes, verify that Amazon 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 Amazon AppConfig Agent container: [appconfig agent] 1970/01/01 00:00:00 INFO serving on localhost:2772

Note

You can adjust the default behavior of Amazon AppConfig Agent by entering or changing environment variables. For information about the available environment variables, see Using environment variables to configure Amazon AppConfig Agent for Amazon ECS and Amazon EKS.

Using environment variables to configure Amazon AppConfig Agent for Amazon ECS and Amazon EKS

You can configure Amazon AppConfig Agent by changing the following environment variables for your agent container.

Environment variable Details Default value

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 <token value>
None

BACKUP_DIRECTORY

This environment variable enables Amazon AppConfig Agent to save a backup of each configuration it retrieves to the specified directory.

Important

Configurations backed up to disk are not encrypted. If your configuration contains sensitive data, Amazon AppConfig recommends that you practice the principle of least privilege with your filesystem permissions. For more information, see Security in Amazon AppConfig.

None

HTTP_PORT

This environment variable specifies the port on which the HTTP server for the agent runs.

2772

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 variables are case sensitive. From most to least detailed, the log levels are: debug, info, warn, error, and none. Debug includes detailed information, including timing information, about the agent.

info

MANIFEST

This environment variable configures Amazon 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:

  • "app:env:manifest-config"

  • "file:/fully/qualified/path/to/manifest.json"

For more information about these features, see Additional retrieval features.

true

MAX_CONNECTIONS

This environment variable configures the maximum number of connections that the agent uses to retrieve configurations from Amazon AppConfig.

3

POLL_INTERVAL

This environment variable controls how often the agent polls Amazon 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

PREFETCH_LIST

This environment variable specifies the configuration data the agent requests from Amazon AppConfig as soon as it starts.

None

PRELOAD_BACKUPS

If set to true, Amazon 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, Amazon 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
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.
"header: value"
None
PROXY_URL This environment variable specifies the proxy URL to use for connections from the agent to Amazon Web Services, including Amazon AppConfig. HTTPS and HTTP URLs are supported. None

REQUEST_TIMEOUT

This environment variable controls the amount of time the agent waits for a response from Amazon 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. Amazon 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 Amazon Web Services Region that Amazon AppConfig Agent uses to call the Amazon AppConfig service. If left undefined, the agent attempts to determine the current Region. If it can't, the agent fails to start. None

WAIT_ON_MANIFEST

This environment variable configures Amazon AppConfig Agent to wait until the manifest is processed before completing startup.

true

Retrieving configuration data

You can retrieve configuration data from Amazon 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.

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 Amazon 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 Amazon 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"