# Using a manifest to enable additional retrieval features


AWS AppConfig Agent offers the following additional features to help you retrieve configurations for your applications. 
+ [Configuring AWS AppConfig Agent to retrieve configurations from multiple accounts](appconfig-agent-how-to-use-additional-features-multi-account.md): Use AWS AppConfig Agent from a primary or *retrieval* AWS account to retrieve configuration data from multiple vendor accounts. 
+ [Configuring AWS AppConfig Agent to write configuration copies to disk](appconfig-agent-how-to-use-additional-features-write-to-disk.md): 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.

## Understanding 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:aws: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:
+ [Configuring the AWS AppConfig Agent Lambda extension](appconfig-integration-lambda-extensions-config.md)
+ [Using AWS AppConfig Agent with Amazon EC2](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-ec2.html#appconfig-integration-ec2-configuring)
+ [Using AWS AppConfig Agent with Amazon ECS and Amazon EKS](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-containers-agent.html#appconfig-integration-containers-agent-configuring)

# Configuring AWS AppConfig Agent to retrieve configurations from multiple accounts


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:aws: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](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_appconfigdata_GetLatestConfiguration.html) API operation to retrieve configuration data from AWS AppConfig running in those accounts:

![\[How AWS AppConfig Agent works with IAM roles across separate AWS accounts.\]](http://docs.aws.amazon.com/appconfig/latest/userguide/images/agent multi-account.png)


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

1. Sign in to the AWS Management Console in a vendor account.

1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **Policies**, and then choose **Create policy**.

1. Choose the **JSON** option.

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

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "appconfig:StartConfigurationSession",
                   "appconfig:GetLatestConfiguration"
               ],
               "Resource": "arn:aws:appconfig:us-east-1:111122223333:application/vendor_application_ID/environment/vendor_environment_ID/configuration/vendor_configuration_ID"
           }
       ]
   }
   ```

------

   Here's an example:

------
#### [ JSON ]

****  

   ```
   {
       "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"
       }
      ]
   }
   ```

------

1. Choose **Next**.

1. In the **Policy name** field, enter a name.

1. (Optional) For **Add tags**, add one or more tag-key value pairs to organize, track, or control access for this policy.

1. Choose **Create policy**. The system returns you to the **Policies** page.

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

1. Sign in to the AWS Management Console in a vendor account.

1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **Roles**, and then choose **Create policy**.

1. For **Trusted entity type**, choose **AWS account**.

1. In the **AWS account** section, choose **Another AWS account**.

1. In the **Account ID** field, enter the retrieval account ID.

1. (Optional) As a security best practice for this assume role, choose **Require external ID** and enter a string.

1. Choose **Next**.

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

1. Choose **Next**.

1. For **Role name**, enter a name.

1. (Optional) For **Description**, enter a description.

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

------
#### [ JSON ]

****  

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

------

1. (Optional) For **Tags**, add one or more tag-key value pairs to organize, track, or control access for this role.

1. Choose **Create role**. The system returns you to the **Roles** page.

1. 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:aws: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
```

# Configuring AWS AppConfig Agent to write configuration copies 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](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-ec2.html#appconfig-integration-ec2-configuring) or [Using AWS AppConfig Agent with Amazon ECS and Amazon EKS](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-containers-agent.html#appconfig-integration-containers-agent-configuring).

**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](appconfig-security.md#appconfig-security-least-privilege-access).

**To enable write configuration copy to disk**

1. Edit the manifest.

1. 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"
           }
       }
   }
   ```

1. 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\$1path*" 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
```