Retrieving configuration data from Amazon EC2 instances - 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 EC2 instances

You can integrate Amazon AppConfig with applications running on your Amazon Elastic Compute Cloud (Amazon EC2) Linux instances by using Amazon AppConfig Agent. The agent enhances 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 availability of local configuration data 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 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 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.

Step 1: (Required) Creating resources and configuring permissions

To integrate Amazon AppConfig with applications running on your Amazon EC2 instances, 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 applications must be configured with access to the Amazon AppConfig data plane. To give your applications access, update the IAM permissions policy that is assigned to the Amazon EC2 instance role. Specifically, you must add the appconfig:StartConfigurationSession and appconfig:GetLatestConfiguration actions to the policy. Here is an example:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "appconfig:StartConfigurationSession", "appconfig:GetLatestConfiguration" ], "Resource": "*" } ] }

For more information about adding permissions to a policy, see Adding and removing IAM identity permissions in the IAM User Guide.

Step 2: (Required) Installing and starting Amazon AppConfig Agent on Amazon EC2 instances

Amazon AppConfig Agent is hosted in an Amazon Simple Storage Service (Amazon S3) bucket that is managed by Amazon. Use the following procedure to install the latest version of the agent on your Linux instance. If your application is distributed across multiple instances, then you must perform this procedure on each instance that hosts the application.

Note

Note the following information:

  • Amazon AppConfig Agent is available for Linux operating systems running kernel version 4.15 or greater. Debian-based systems, such as Ubuntu, are not supported.

  • The agent supports x86_64 and ARM64 architectures.

  • For distributed applications, we recommend adding the install and startup commands to the Amazon EC2 user data of your Auto Scaling group. If you do, each instance runs the commands automatically. For more information, see Run commands on your Linux instance at launch in the Amazon EC2 User Guide for Linux Instances. Additionally, see Tutorial: Configure user data to retrieve the target lifecycle state through instance metadata in the Amazon EC2 Auto Scaling User Guide.

  • The procedures throughout this topic describe how to perform actions like installing the agent by logging into the instance to run the command. You can run the commands from a local client machine and target one or more instances by using Run Command, which is a capability of Amazon Systems Manager. For more information, see Amazon Systems Manager Run Command in the Amazon Systems Manager User Guide.

  • Amazon AppConfig Agent on Amazon EC2 Linux instances is a systemd service.

To install and start Amazon AppConfig Agent on an instance
  1. Log into your Linux instance.

  2. Open a terminal and run the following command with Administrator permissions for x86_64 architectures:

    sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/latest/aws-appconfig-agent.rpm

    For ARM64 architectures, run the following command:

    sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/arm64/latest/aws-appconfig-agent.rpm

    If you want to install a specific version of Amazon AppConfig Agent, replace latest in the URL with a specific version number. Here's an example for x86_64:

    sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/2.0.2/aws-appconfig-agent.rpm
  3. Run the following command to start the agent:

    sudo systemctl start aws-appconfig-agent
  4. Run the following command to verify the agent is running:

    sudo systemctl status aws-appconfig-agent

    If successful, the command returns information like the following:

    aws-appconfig-agent.service - aws-appconfig-agent ... Active: active (running) since Mon 2023-07-26 00:00:00 UTC; 0s ago ...
Note

To stop the agent, run the following command:

sudo systemctl stop aws-appconfig-agent

Step 3: (Optional, but recommended) Sending log files to CloudWatch Logs

By default, Amazon AppConfig Agent publishes logs to STDERR. Systemd redirects STDOUT and STDERR for all services running on the Linux instance to the systemd journal. You can view and manage log data in the systemd journal if you're running Amazon AppConfig Agent on only one or two instances. A better solution, a solution we highly recommend for distributed applications, is to write log files to disk and then use Amazon CloudWatch agent to upload the log data to the Amazon cloud. Additionally, you can configure the CloudWatch agent to delete old log files from your instance, which prevents your instance from running out of disk space.

To enable logging to disk, you must set the LOG_PATH environment variable, as described in Step 4: (Optional) Using environment variables to configure Amazon AppConfig Agent for Amazon EC2.

To get started with the CloudWatch agent, see Collect metrics and logs from Amazon EC2 instances and on-premises servers with the CloudWatch agent in the Amazon CloudWatch User Guide. You can use Quick Setup, a capability of Systems Manager to quickly install the CloudWatch agent. For more information, see Quick Setup Host Management in the Amazon Systems Manager User Guide.

Warning

If you choose to write log files to disk without using the CloudWatch agent, you must delete old log files. Amazon AppConfig Agent automatically rotates log files every hour. If you don't delete old log files, your instance can run out of disk space.

After you install the CloudWatch agent on your instance, create a CloudWatch agent configuration file. The configuration file instructs CloudWatch agent on how to work with Amazon AppConfig Agent log files. For more information about creating a CloudWatch agent configuration file, see Create the CloudWatch agent configuration file.

Add the following logs section to the CloudWatch agent configuration file on the instance and save your changes:

"logs": { "logs_collected": { "files": { "collect_list": [ { "file_path": "/path_you_specified_for_logging", "log_group_name": "${YOUR_LOG_GROUP_NAME}/aws-appconfig-agent.log", "auto_removal": true }, ... ] }, ... }, ... }

If the value of auto_removal is true, the CloudWatch agent automatically deletes rotated Amazon AppConfig Agent log files.

Step 4: (Optional) Using environment variables to configure Amazon AppConfig Agent for Amazon EC2

You can configure Amazon AppConfig Agent for Amazon EC2 by using environment variables. To set environment variables for a systemd service, you create a drop-in unit file. The following example shows how to create drop-in unit file to set the Amazon AppConfig Agent logging level to DEBUG.

Example of how to create a drop-in unit file for environment variables
  1. Log into your Linux instance.

  2. Open a terminal and run the following command with Administrator permissions. The command creates a configuration directory:

    sudo mkdir /etc/systemd/system/aws-appconfig-agent.service.d
  3. Run the following command to create the drop-in unit file. Replace file_name with a name for the file. The extension must be .conf:

    sudo touch /etc/systemd/system/aws-appconfig-agent.service.d/file_name.conf
  4. Enter information in the drop-in unit file. The following example adds a Service section that defines an environment variable. The example sets Amazon AppConfig Agent log level to DEBUG.

    [Service] Environment=LOG_LEVEL=DEBUG
  5. Run the following command to reload the systemd configuration:

    sudo systemctl daemon-reload
  6. Run the following command to restart Amazon AppConfig Agent:

    sudo systemctl restart aws-appconfig-agent

You can configure Amazon AppConfig Agent for Amazon EC2 by specifying the following environment variables in a drop-in unit file.

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

LOG_PATH

The disk location where logs are written. If not specified, logs are written to stderr.

None

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

Step 5: (Required) 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, including an Amazon SDK.

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"

Step 6 (Optional, but recommended): Automating updates to Amazon AppConfig Agent

Amazon AppConfig Agent is updated periodically. To ensure you are running the latest version of Amazon AppConfig Agent on your instances, we recommend that you add the following commands to your Amazon EC2 user data. You can add the commands to the user data on either the instance or the EC2 Auto Scaling group. The script installs and starts the latest version of the agent each time an instance starts or reboots.

#!/bin/bash # install the latest version of the agent yum install -y https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/latest/aws-appconfig-agent.rpm # optional: configure the agent mkdir /etc/systemd/system/aws-appconfig-agent.service.d echo "${MY_AGENT_CONFIG}" > /etc/systemd/system/aws-appconfig-agent.service.d/overrides.conf systemctl daemon-reload # start the agent systemctl start aws-appconfig-agent