Using Amazon AppConfig Agent with Amazon EC2 and on-premises machines

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:

*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.

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.

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.

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

GET /applications/my_app/...
                  Host: localhost:2772
                  Authorization: Bearer <token value>

"header: value"

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