About agent manifests Multi-account retrieval Write configuration copy to disk

Additional retrieval features

AWS AppConfig Agent offers the following additional features to help you retrieve configurations for your applications.

Multi-account retrieval: Use AWS AppConfig Agent from a primary or retrieval AWS account to retrieve configuration data from multiple vendor accounts.
Write configuration copy to disk: Use AWS AppConfig Agent to write configuration data to disk. This feature enables customers with applications that read configuration data from disk to integrate with AWS AppConfig.

About agent manifests

To enable these AWS AppConfig Agent features, you create a manifest. A manifest is a set of configuration data that you provide to control actions the agent can perform. A manifest is written in JSON. It contains a set of top-level keys that correspond to different configurations you’ve deployed using AWS AppConfig.

A manifest can include multiple configurations. Furthermore, each configuration in the manifest can identify one or more agent features to use for the specified configuration. The content of the manifest uses the following format:


{
    "application_name:environment_name:configuration_name": {
        "agent_feature_to_enable_1": {
            "feature-setting-key": "feature-setting-value"
        },
        "agent_feature_to_enable_2": {
            "feature-setting-key": "feature-setting-value"
        }
    }
}

Here is example JSON for a manifest with two configurations. The first configuration (MyApp) doesn't use any AWS AppConfig Agent features. The second configuration (My2ndApp) uses the write configuration copy to disk and the multi-account retrieval features:


{
        "MyApp:Test:MyAllowListConfiguration": {},
        
        "My2ndApp:Beta:MyEnableMobilePaymentsFeatureFlagConfiguration": {
            "credentials": {
                "roleArn": "arn:us-west-1:iam::123456789012:role/MyTestRole",
                "roleExternalId": "00b148e2-4ea4-46a1-ab0f-c422b54d0aac",
                "roleSessionName": "AwsAppConfigAgent",
                "credentialsDuration": "2h"
            },
            "writeTo": {
                "path": "/tmp/aws-appconfig/my-2nd-app/beta/my-enable-payments-feature-flag-configuration.json"
            }
        }
    }

How to supply an agent manifest

You can store the manifest as a file in a location where AWS AppConfig Agent can read it. Or, you can store the manifest as an AWS AppConfig configuration and point the agent to it. To supply an agent manifest, you must set a MANIFEST environment variable with one of the following values:

Manifest location	Environment variable value	Use case
File	file:/path/to/agent-manifest.json	Use this method if your manifest won't change often.
AWS AppConfig configuration	`application-name`:`environment-name`:`configuration-name`	Use this method for dynamic updates. You can update and deploy a manifest stored in AWS AppConfig as a configuration in the same ways you store other AWS AppConfig configurations.
Environment variable	Manifest content (JSON)	Use this method if your manifest won't change often. This method is useful in container environments where it's easier to set an environment variable than it is to expose a file.

For more information about setting variables for AWS AppConfig Agent, see the relevant topic for your use case:

Multi-account retrieval

You can configure AWS AppConfig Agent to retrieve configurations from multiple AWS accounts by entering credential overrides in the AWS AppConfig Agent manifest. Credential overrides include the Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role, a role ID, a session name, and a duration for how long the agent can assume the role.

You enter these details in a "credentials" section in the manifest. The "credentials" section uses the following format:


{
    "application_name:environment_name:configuration_name": {
        "credentials": {
            "roleArn": "arn:partition:iam::account_ID:role/roleName",
            "roleExternalId": "string",
            "roleSessionName": "string",
            "credentialsDuration": "time_in_hours" 
        }
    }
}

Here is an example:


{
    "My2ndApp:Beta:MyEnableMobilePaymentsFeatureFlagConfiguration": {
        "credentials": {
            "roleArn": "arn:us-west-1:iam::123456789012:role/MyTestRole",
            "roleExternalId": "00b148e2-4ea4-46a1-ab0f-c422b54d0aac",
            "roleSessionName": "AWSAppConfigAgent",
            "credentialsDuration": "2h" 
        }
    }
}

Before retrieving a configuration, the agent reads the credential details for the configuration from the manifest and then assumes the IAM role specified for that configuration. You can specify a different set of credential overrides for different configurations in a single manifest. The following diagram shows how AWS AppConfig Agent, while running in Account A (the retrieval account), assumes separate roles specified for Accounts B and C (the vendor accounts) and then calls the GetLatestConfiguration API operation to retrieve configuration data from AWS AppConfig running in those accounts:

A diagram showing how AWS AppConfig Agent works with AWS Identity and Access Management (IAM) roles across separate AWS accounts.

Configure permissions to retrieve configuration data from vendor accounts

AWS AppConfig Agent running in the retrieval account needs permission to retrieve configuration data from the vendor accounts. You give the agent permission by creating an AWS Identity and Access Management (IAM) role in each of the vendor accounts. AWS AppConfig Agent in the retrieval account assumes this role to get data from vendor accounts. Complete the procedures in this section to create an IAM permissions policy, an IAM role, and add agent overrides to the manifest.

Before you begin

Collect the following information before you create a permission policy and a role in IAM.

The IDs for each AWS account. The retrieval account is the account that will call other accounts for configuration data. The vendor accounts are the accounts that will vend configuration data to the retrieval account.
The name of the IAM role used by AWS AppConfig in the retrieval account. Here's a list of the roles used by AWS AppConfig, by default:
- For Amazon Elastic Compute Cloud (Amazon EC2), AWS AppConfig uses the instance role.
- For AWS Lambda, AWS AppConfig uses the Lambda execution role.
- For Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS), AWS AppConfig uses the container role.
If you configured AWS AppConfig Agent to use a different IAM role by specifying the ROLE_ARN environment variable, make a note of that name.

Create the permissions policy

Use the following procedure to create a permissions policy using the IAM console. Complete the procedure in each AWS account that will vend configuration data for the retrieval account.

To create an IAM policy

Sign in to the AWS Management Console in a vendor account.
Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Policies, and then choose Create policy.
Choose the JSON option.

In the Policy editor, replace the default JSON with the following policy statement. Update each example resource placeholder with vendor account details.


{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "appconfig:StartConfigurationSession",
            "appconfig:GetLatestConfiguration"
        ],
        "Resource": "arn:partition:appconfig:region:vendor_account_ID:application/vendor_application_ID/environment/vendor_environment_ID/configuration/vendor_configuration_ID"
    }
   ]
}

Here's an example:


{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "appconfig:StartConfigurationSession",
            "appconfig:GetLatestConfiguration"
        ],
        "Resource": "arn:aws:appconfig:us-east-2:111122223333:application/abc123/environment/def456/configuration/hij789"
    }
   ]
}

Choose Next.
In the Policy name field, enter a name.
(Optional) For Add tags, add one or more tag-key value pairs to organize, track, or control access for this policy.
Choose Create policy. The system returns you to the Policies page.
Repeat this procedure in each AWS account that will vend configuration data for the retrieval account.

Create the IAM role

Use the following procedure to create an IAM role using the IAM console. Complete the procedure in each AWS account that will vend configuration data for the retrieval account.

To create an IAM role

Sign in to the AWS Management Console in a vendor account.
Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles, and then choose Create policy.
For Trusted entity type, choose AWS account.
In the AWS account section, choose Another AWS account.
In the Account ID field, enter the retrieval account ID.
(Optional) As a security best practice for this assume role, choose Require external ID and enter a string.
Choose Next.
On the Add permissions page, use the Search field to locate the policy you created in the previous procedure. Select the check box next to its name.
Choose Next.
For Role name, enter a name.
(Optional) For Description, enter a description.

For Step 1: Select trusted entities, choose Edit. Replace the default JSON trust policy with the following policy. Update each example resource placeholder with information from your retrieval account.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::retrieval_account_ID:role/appconfig_role_in_retrieval_account"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

(Optional) For Tags, add one or more tag-key value pairs to organize, track, or control access for this role.
Choose Create role. The system returns you to the Roles page.
Search for the role you just created. Choose it. In the ARN section, copy the ARN. You'll specify this information in the next procedure.

Add credential overrides to the manifest

After you create the IAM role in your vendor account, update the manifest in the retrieval account. Specifically, add the credentials block and the IAM role ARN for retrieving configuration data from the vendor account. Here is the JSON format:


{
    "vendor_application_name:vendor_environment_name:vendor_configuration_name": {
        "credentials": {
            "roleArn": "arn:partition:iam::vendor_account_ID:role/name_of_role_created_in_vendor_account",
            "roleExternalId": "string",
            "roleSessionName": "string",
            "credentialsDuration": "time_in_hours" 
        }
    }
}

Here is an example:


{
    "My2ndApp:Beta:MyEnableMobilePaymentsFeatureFlagConfiguration": {
        "credentials": {
            "roleArn": "arn:us-west-1:iam::123456789012:role/MyTestRole",
            "roleExternalId": "00b148e2-4ea4-46a1-ab0f-c422b54d0aac",
            "roleSessionName": "AwsAppConfigAgent",
            "credentialsDuration": "2h" 
        }
    }
}

Validate that multi-account retrieval is working

You can validate that that agent is able to retrieve configuration data from multiple accounts by reviewing the AWS AppConfig agent logs. The INFO level log for retrieved initial data for 'YourApplicationName:YourEnvironmentName:YourConfigurationName' is the best indicator for successful retrievals. If retrievals are failing, you should see an ERROR level log indicating the failure reason. Here is an example for a successful retrieval from a vendor account:


[appconfig agent] 2023/11/13 11:33:27 INFO AppConfig Agent 2.0.x
[appconfig agent] 2023/11/13 11:33:28 INFO serving on localhost:2772
[appconfig agent] 2023/11/13 11:33:28 INFO retrieved initial data for 'MyTestApplication:MyTestEnvironment:MyDenyListConfiguration' in XX.Xms

Write configuration copy to disk

You can configure AWS AppConfig Agent to automatically store a copy of a configuration to disk in plain text. This feature enables customers with applications that read configuration data from disk to integrate with AWS AppConfig.

This feature is not designed to be used as a configuration backup feature. AWS AppConfig Agent doesn't read from the configuration files copied to disk. If you want to back up configurations to disk, see the BACKUP_DIRECTORY and PRELOAD_BACKUP environment variables for Using AWS AppConfig Agent with Amazon EC2 or Using AWS AppConfig Agent with Amazon ECS and Amazon EKS.

Warning

Note the following important information about this feature:

Configurations saved to disk are stored in plain text and are human readable. Don't enable this feature for configurations that include sensitive data.
This feature writes to the local disk. Use the principle of least privilege for filesystem permissions. For more information, see Implement least privilege access.

To enable write configuration copy to disk

Edit the manifest.

Choose the configuration that you want AWS AppConfig to write to disk and add a writeTo element. Here is an example:


{
    "application_name:environment_name:configuration_name": {
        "writeTo": {
            "path": "path_to_configuration_file"
        }
    }
}

Here is an example:


{
    "MyTestApp:MyTestEnvironment:MyNewConfiguration": {
        "writeTo": {
            "path": "/tmp/aws-appconfig/mobile-app/beta/enable-mobile-payments"
        }
    }
}

Save your changes. The configuration.json file will be updated each time new configuration data is deployed.

Validate that write configuration copy to disk is working

You can validate that copies of a configuration are being written to disk by looking by reviewing the AWS AppConfig agent logs. The INFO log entry with the phrasing "INFO wrote configuration 'application:environment:configuration' to file_path" indicates that AWS AppConfig Agent writes configuration copies to disk.

Here is an example:


[appconfig agent] 2023/11/13 11:33:27 INFO AppConfig Agent 2.0.x
[appconfig agent] 2023/11/13 11:33:28 INFO serving on localhost:2772
[appconfig agent] 2023/11/13 11:33:28 INFO retrieved initial data for 'MobileApp:Beta:EnableMobilePayments' in XX.Xms
[appconfig agent] 2023/11/13 17:05:49 INFO wrote configuration 'MobileApp:Beta:EnableMobilePayments' to /tmp/configs/your-app/your-env/your-config.json

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Retrieving configuration data from Amazon ECS and Amazon EKS

AWS AppConfig Agent local development