# Configure IAM Role
### Overview
This page describes how to create a IAM role and enable access for **Usage Measurement and Collection**. There are two alternative ways described below to create the IAM role and enable access for Paigo to query your account in order to determine usage.
### Requirements
The CLI method requires you have the latest [AWS CLI](https://aws.amazon.com/cli/) installed. Both ways require you have access to create and manage IAM policies within the AWS account that Paigo will interact with.
### Create IAM role with AWS CLI
#### Prepare for the Configurations
Below are two JSON files that you need in order to enable Paigo to measurement usage. Save the below file on the file system, and name it `trust-relationships.json`. This JSON document defines an AWS IAM policy that allows Paigo to assume a role with access to the AWS account owned by SaaS business. Line 8 is the AWS account owned by Paigo. There is an optional field called external ID for assuming role. Change the line 12 to some other External ID for enhanced security. It is a strongly recommended practice to use External ID. However, if you want to opt out using External ID, use the JSON document of the **Without External ID** tab.
{% tabs %}
{% tab title="With External ID (Change Line 12)" %}
{% code title="trust-relationships.json" lineNumbers="true" %}
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"AWS": "647662420899"
},
"Condition": {
"StringEquals": {
"sts:ExternalId": "TODO"
}
}
}
]
}
```
{% endcode %}
{% endtab %}
{% tab title="Without External ID" %}
{% code title="trust-relationships.json" lineNumbers="true" %}
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"AWS": "647662420899"
}
}
]
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
Save the below file in the same directory as above, and name this file `permissions.json`. This file defines the minimal list of permission granted to Paigo for measurement, billing and analytics functionalities.
{% code title="permissions.json" lineNumbers="true" %}
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"eks:DescribeFargateProfile",
"eks:ListTagsForResource",
"cloudtrail:ListServiceLinkedChannels",
"cloudtrail:GetTrailStatus",
"cloudtrail:DescribeQuery",
"eks:ListAddons",
"cloudtrail:GetEventSelectors",
"aws-portal:ViewUsage",
"cloudwatch:Describe*",
"cloudtrail:CancelQuery",
"ebs:ListChangedBlocks",
"eks:DescribeAddon",
"billing:ListBillingViews",
"eks:DescribeNodegroup",
"aws-portal:ViewPaymentMethods",
"eks:ListUpdates",
"cloudtrail:GetServiceLinkedChannel",
"cloudtrail:ListTags",
"aws-portal:ViewBilling",
"eks:DescribeAddonVersions",
"cloudwatch:Get*",
"cloudtrail:ListQueries",
"cloudtrail:GetInsightSelectors",
"eks:ListIdentityProviderConfigs",
"ebs:GetSnapshotBlock",
"ec2:Get*",
"cloudtrail:LookupEvents",
"cloudtrail:GetTrail",
"eks:ListNodegroups",
"cloudtrail:ListTrails",
"cloudtrail:GetEventDataStore",
"aws-portal:ViewAccount",
"ebs:ListSnapshotBlocks",
"cloudwatch:List*",
"cloudtrail:GetQueryResults",
"cloudtrail:DescribeTrails",
"cloudtrail:ListEventDataStores",
"eks:ListFargateProfiles",
"ec2:Describe*",
"eks:DescribeIdentityProviderConfig",
"cloudtrail:ListPublicKeys",
"eks:DescribeUpdate",
"eks:AccessKubernetesApi",
"eks:DescribeCluster",
"cloudtrail:StartQuery",
"eks:ListClusters"
],
"Resource": "*"
}
]
}
```
{% endcode %}
#### Create a role with the configurations
Run the following command to grant Paigo read-only access from the directory where the configuration files prepared above are saved.
{% code overflow="wrap" lineNumbers="true" %}
```bash
aws iam create-role --role-name paigo-assumed-role \
--assume-role-policy-document file://trust-relationships.json && \
aws iam put-role-policy --role-name paigo-assumed-role \
--policy-name read-cw-read-ec2 --policy-document file://permissions.json
```
{% endcode %}
In the above script, a role named `paigo-assumed-role` will created with the policy specified above.
### Create IAM role with AWS Console
Alternatively, an IAM role can be created from AWS Console.
1. Navigate to the [IAM Role Policy](https://us-east-1.console.aws.amazon.com/iamv2/home#/policies) after logging in to AWS Console
2. On the next page for permissions choose the **Create a Policy** option and then chose the **JSON** tab. You should be presented with a page that looks like the following:
3. Paste the following JSON document into the JSON editor. This file defines the minimal list of permission granted to Paigo for measurement, billing and analytics functionalities.
{% code title="" overflow="wrap" lineNumbers="true" %}
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"eks:DescribeFargateProfile",
"eks:ListTagsForResource",
"cloudtrail:ListServiceLinkedChannels",
"cloudtrail:GetTrailStatus",
"cloudtrail:DescribeQuery",
"eks:ListAddons",
"cloudtrail:GetEventSelectors",
"aws-portal:ViewUsage",
"cloudwatch:Describe*",
"cloudtrail:CancelQuery",
"ebs:ListChangedBlocks",
"eks:DescribeAddon",
"billing:ListBillingViews",
"eks:DescribeNodegroup",
"aws-portal:ViewPaymentMethods",
"eks:ListUpdates",
"cloudtrail:GetServiceLinkedChannel",
"cloudtrail:ListTags",
"aws-portal:ViewBilling",
"eks:DescribeAddonVersions",
"cloudwatch:Get*",
"cloudtrail:ListQueries",
"cloudtrail:GetInsightSelectors",
"eks:ListIdentityProviderConfigs",
"ebs:GetSnapshotBlock",
"ec2:Get*",
"cloudtrail:LookupEvents",
"cloudtrail:GetTrail",
"eks:ListNodegroups",
"cloudtrail:ListTrails",
"cloudtrail:GetEventDataStore",
"aws-portal:ViewAccount",
"ebs:ListSnapshotBlocks",
"cloudwatch:List*",
"cloudtrail:GetQueryResults",
"cloudtrail:DescribeTrails",
"cloudtrail:ListEventDataStores",
"eks:ListFargateProfiles",
"ec2:Describe*",
"eks:DescribeIdentityProviderConfig",
"cloudtrail:ListPublicKeys",
"eks:DescribeUpdate",
"eks:AccessKubernetesApi",
"eks:DescribeCluster",
"cloudtrail:StartQuery",
"eks:ListClusters"
],
"Resource": "*"
}
]
}
```
{% endcode %}
4\. Click **Next Tags** , no fields are required on this page.
5\. Click through to the finalize page, and enter a name you can remember, such as `paigo-policy`.
6\. Navigate to [IAM Role Page](https://us-east-1.console.aws.amazon.com/iamv2/home#/roles/create?step=selectEntities). You should see the following layout:
To configure the External ID select the **Require external ID (Best practice when a third party will assume this role)** near the bottom and fill in an custom string. Take note of this for entering into Paigo later.
7\. Select the **AWS Account** option and choose the **External Account** choice on the next page:
8\. Enter the Paigo AWS account ID: `647662420899`
9\. Click **Next** and on the following page select the `paigo-policy` you just created:
10\. Click **Next**, then give it a role name you want to call it on the following page:
11\. Click **Create Role** to save the role just created.
12\. Copy the role ARN by search for the role name in the list, and click on the **Copy** icon below **ARN.** See below screenshot for an example. The role ARN and externalID will be needed by Paigo.
