> For the complete documentation index, see [llms.txt](https://docs.north.cloud/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.north.cloud/docs/getting-started/permissions-required/aws-permissions.md).

# AWS permissions

Permissions North.cloud requires from your AWS account.

***

## IAM Permission & Deployment

North requires carefully scoped IAM permissions so our application can access cost and usage data required by our ML engine to provide automated FinOps recommendations. We purposefully limit all permissions to the minimum necessary for your financial analysis and do not request access to your workloads or sensitive application data.

{% hint style="info" %}
During onboarding, you have the **option** to add an **external ID** to the IAM roles assigned to your unique North root user. Using an external ID is an AWS security best practice. This externally supplied secret string helps ensure that only North’s authorized systems can assume the roles you configure. It is optional, but we encourage its use for additional protection. North will provide the required external ID value (if you choose to use it) securely during onboarding as part of our recommended implementation.

If you add an external ID, it must match the value North holds for your account. If the two values differ, North's daily verification check fails, and your cost data pauses until they match. To get an external ID, ask your North Customer Success contact.
{% endhint %}

#### What North <mark style="color:red;">CAN NOT</mark> do:

* Read sensitive data from your workloads or databases
* View or edit network rules and security groups
* Create, modify, stop, or terminate any compute instances or other machines
* Change, copy, or export any development, test, or production data

The following sections explain the IAM permissions required, why each group is needed.

{% hint style="info" %}
**Groups 1 to 3 are not a menu.** They describe what is inside a single CloudFormation stack. Whichever method you use to onboard, console, CLI, or Terraform, you deploy the same `north-all-features.yaml` template, and it carries all three groups together. The grouping below explains what that one stack grants and why, so you can review it before you deploy it. Group 4, Auto-Purchasing, is the exception. It is a separate role you deploy separately, and only if you want it.
{% endhint %}

***

### Permission Groups Explained

#### **1. Baseline (Default) – Read-Only Cost & Usage Data**

**Purpose:**\
These permissions are required for North to read AWS billing, usage, and cost details, which underpin all FinOps analysis and recommendations.

**Key Actions Explained:**

* `ce:*`, `cur:*` – Read cost and usage reports from AWS (Cost Explorer, CUR).
* `billing:*`, `account:GetAccountInformation` – Read account and billing details.
* `ec2:DescribeCapacity*`, `rds:DescribeReserved*` – Read reserved/reserved instance fleet details for savings recommendations.
* **Explicitly read-only:** No permission to change or stop resources.

**Policy Example:**

{% code overflow="wrap" %}

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ce:Get*",
        "ce:Describe*",
        "ce:List*",
        "ce:Start*",
        "account:GetAccountInformation",
        "billing:Get*",
        "payments:List*",
        "payments:Get*",
        "tax:List*",
        "tax:Get*",
        "consolidatedbilling:Get*",
        "consolidatedbilling:List*",
        "invoicing:List*",
        "invoicing:Get*",
        "cur:Get*",
        "cur:Validate*",
        "freetier:Get*",
        "ec2:DescribeCapacity*",
        "ec2:DescribeReservedInstances*",
        "ec2:DescribeSpot*",
        "rds:DescribeReserved*",
        "rds:DescribeDBRecommendations",
        "rds:DescribeAccountAttributes",
        "ecs:DescribeCapacityProviders",
        "es:DescribeReserved*"
      ],
      "Resource": "*",
      "Effect": "Allow",
      "Sid": "NorthCostAndUsageReadOnlyPolicyID"
    }
  ]
}
```

{% endcode %}

***

#### **2. Premier Baseline – Compute Optimizer, CloudWatch & Service-Linked Roles**

**Purpose:**\
These permissions let North read Compute Optimizer recommendations and CloudWatch metrics. North uses the Compute Optimizer recommendations for the savings figures in its alerts. Rightsize generates its own recommendations from your billing data, CloudWatch metrics, and AWS pricing. Rightsize reads CloudWatch metrics through `NorthCloudWatchCrossAccountAccessRole` and `NorthCloudWatchCrossAccountSharingRole`, described in [Advanced Permissions](#id-3.-advanced-permissions-cross-account-cross-region-cur-read-access-and-enhanced-real-time-metrics), below.

**Why are IAM permissions (like `iam:CreateServiceLinkedRole`) included?**

A common source of confusion is the need for IAM service-linked role permissions (such as `iam:CreateServiceLinkedRole`) for Compute Optimizer. Here's what you need to know:

* **Compute Optimizer requires a service-linked role to function** (an AWS requirement).
* The permission to create this role is used **only by AWS, internally within your account**, to allow Compute Optimizer to gather data.
* **North does not use, access, or assume this role directly.** We only access Compute Optimizer's *readable* outputs, which stay within your AWS account.
* Granting these permissions allows AWS to configure Compute Optimizer if not already done; many customers may already have this set up.

**Key Actions Explained:**

* `iam:CreateServiceLinkedRole`, `iam:PutRolePolicy`: Enable AWS to create and configure the required service-linked role for Compute Optimizer to report findings within your account only.
* `compute-optimizer:*`: Read Compute Optimizer recommendations. North also calls `UpdateEnrollmentStatus` to enroll your organization in Compute Optimizer. That is the only Compute Optimizer action North calls that changes your account.
* `cloudwatch:GetMetricStatistics`, `ecs:List*`, `lambda:ListFunctions`: Access aggregated metric and inventory data for analysis.

**Policy Example:**

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Sid": "NorthPremiumPolicy1",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/compute-optimizer.amazonaws.com/AWSServiceRoleForComputeOptimizer*",
      "Condition": {
        "StringLike": {
          "iam:AWSServiceName": "compute-optimizer.amazonaws.com"
        }
      }
    },
    {
      "Effect": "Allow",
      "Sid": "NorthPremiumPolicy2",
      "Action": "iam:PutRolePolicy",
      "Resource": "arn:aws:iam::*:role/aws-service-role/compute-optimizer.amazonaws.com/AWSServiceRoleForComputeOptimizer"
    },
    {
      "Effect": "Allow",
      "Sid": "NorthPremiumPolicy3",
      "Action": [
        "compute-optimizer:*",
        "ec2:DescribeInstances",
        "ec2:DescribeVolumes",
        "ecs:List*",
        "autoscaling:DescribeAutoScalingGroups",
        "lambda:ListFunctions",
        "lambda:ListProvisionedConcurrencyConfigs",
        "organizations:ListAccounts",
        "cloudwatch:GetMetricStatistics",
        "rds:DescribeDBRecommendations",
        "rds:DescribeReservedDBInstances*"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Sid": "NorthPremiumPolicy4",
      "Action": "organizations:EnableAWSServiceAccess",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "organizations:ServicePrincipal": "compute-optimizer.amazonaws.com"
        }
      }
    }
  ]
}
```

> **In summary:** North uses these permissions to enroll your organization in Compute Optimizer and to read its recommendations. The enrollment is the only Compute Optimizer write that North calls. To keep this role read-only, see [Removing Write Permissions from the Premium Role](/docs/getting-started/permissions-required/aws-permissions.md#removing-write-permissions-from-the-premium-role).

***

#### **3. Advanced Permissions – Cross-Account, Cross-Region, CUR Read Access & Enhanced Real-Time Metrics**

**Purpose:**\
These permissions are **required** (not optional) for customers who want access to North’s advanced FinOps and optimization features. They enable North to retrieve detailed Cost & Usage Report (CUR) data, which unlocks hour and resource-level cloud visibility, as well as, to ingest highly granular metrics from CloudWatch. This deeper and more real-time data access powers advanced analytics, fine-grained savings opportunities, and our most precise rightsizing and recommendation features.

Without these advanced permissions, North cannot provide resource-level breakdowns, high-frequency cost analysis, or evaluate metrics on specific resource behaviors necessary for state-of-the-art optimization.

**Why are these permissions necessary?**

* **CUR (Cost & Usage Report) bucket read access** (`s3:GetObject`, `s3:ListBucket`): This is essential for North to ingest detailed, hourly, and resource-level usage data from your AWS-generated reports. These permissions give you the granularity you expect from modern cloud cost tooling and inform North's advanced dashboards and recommendation engine.
* **CloudWatch cross-account metric and real-time data access** (`cloudwatch:GetMetricData`, `sts:AssumeRole`): These permissions allow North to access metrics across multiple AWS accounts and regions, but only for the specific metrics required for precise analysis and rightsizing. This supports real-time analytics and enables more accurate, actionable optimization suggestions—without granting unfettered access.
* **S3 write-like actions (`s3:PutObject`)**: North will never write or configure anything unless programmatically authorized by your team (e.g., during setup of CUR, if needed), and always in accordance with the principle of least privilege.

**Key Actions Explained:**

* `sts:AssumeRole`: Enables North to securely access metric and cost data from linked accounts, supporting organizations with multi-account structures. When configuring cross-account access, you have the option to specify an external ID that North will supply during onboarding, further protecting your account from unauthorized role assumptions.
* `cloudwatch:GetMetricData`: Enables retrieval of highly specific CloudWatch metrics for North’s analytics—strictly read-only and always scoped to the required metrics for insight and rightsizing.
* `s3:GetObject`, `s3:ListBucket`: Required for North to read your AWS Cost & Usage Reports directly from S3, delivering granular, highly detailed usage data to your reporting dashboards.

**Policy Examples:**

These permissions sit on two roles and one bucket. Each role has a trust policy, which states who can use the role, and a permission policy, which states what the role can do. The Cost and Usage Report bucket has its own bucket policy. In each example, `<your-account-id>` is the ID of the management account where you deploy the stack.

**`NorthCloudWatchCrossAccountAccessRole` trust policy.**

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudwatch-crossaccount.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::480850768557:role/NorthCURReadOnly"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

**`NorthCloudWatchCrossAccountAccessRole` permission policy.**

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/NorthCloudWatchCrossAccountSharingRole"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::north-cur-bucket-<your-account-id>",
        "arn:aws:s3:::north-cur-bucket-<your-account-id>/*"
      ]
    }
  ]
}
```

**`NorthCloudWatchCrossAccountSharingRole` trust policy.** The stack creates this role in your management account, and a StackSet creates it in each account in the organizational unit you select.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::<your-account-id>:root",
          "arn:aws:iam::<your-account-id>:role/NorthCloudWatchCrossAccountAccessRole"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

**`NorthCloudWatchCrossAccountSharingRole` permission policy.**

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}
```

**Cost and Usage Report bucket policy.** The first statement lets AWS deliver your reports to the bucket. The second lets `NorthCloudWatchCrossAccountAccessRole` read them.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AWSBillingDeliveryPermissions",
      "Effect": "Allow",
      "Principal": {
        "Service": "billingreports.amazonaws.com"
      },
      "Action": [
        "s3:PutObject",
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::north-cur-bucket-<your-account-id>",
        "arn:aws:s3:::north-cur-bucket-<your-account-id>/*"
      ]
    },
    {
      "Sid": "AllowCrossAccountAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<your-account-id>:role/NorthCloudWatchCrossAccountAccessRole"
      },
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::north-cur-bucket-<your-account-id>",
        "arn:aws:s3:::north-cur-bucket-<your-account-id>/*"
      ]
    }
  ]
}
```

> **In summary:** These advanced permissions are *required* to unlock North’s most powerful optimization algorithms, including resource-level and real-time recommendations. They are always used in a secure, read-only, and compliance-focused manner, never for broad resource access or uncontrolled data export.

***

#### **4. Auto-Purchasing (Optional) – Buying Commitments in Your Own Account**

**Purpose:**\
Everything above is read-only. It lets North recommend commitments. It does not let North buy them. Autobot needs a separate role, `NorthAutoPurchasingRole`, before it can purchase commitments directly in your own AWS account.

This role is optional and separate from the onboarding stack. Grant it only if you want Autobot to purchase on your behalf. North verifies it separately, and a missing purchasing permission does not affect your account's overall verification status.

**Trust policy.** The role trusts one named role inside North's account, not North's account root.

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

{% hint style="info" %}
**This role does not take an external ID**, and it does not need one. An external ID exists to remove ambiguity when a trust policy names a whole account as the principal. This trust policy names a single role, `NorthAutoOrchestratorRole`, so there is no ambiguity to remove. Do not add an `sts:ExternalId` condition to it. The external ID described at the top of this page applies to the cost and usage roles only.
{% endhint %}

**Permission policy.** Each statement pairs the read-only `Describe` actions North uses to price an offering with the single purchase action for that commitment type.

{% code overflow="wrap" %}

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SavingsPlans",
      "Effect": "Allow",
      "Action": [
        "savingsplans:DescribeSavingsPlansOfferings",
        "savingsplans:DescribeSavingsPlansOfferingRates",
        "savingsplans:CreateSavingsPlan",
        "savingsplans:DeleteQueuedSavingsPlan",
        "savingsplans:DescribeSavingsPlans"
      ],
      "Resource": "*"
    },
    {
      "Sid": "RDSReservedInstances",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeReservedDBInstancesOfferings",
        "rds:DescribeReservedDBInstances",
        "rds:PurchaseReservedDBInstancesOffering"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ElastiCacheReservedInstances",
      "Effect": "Allow",
      "Action": [
        "elasticache:DescribeReservedCacheNodesOfferings",
        "elasticache:DescribeReservedCacheNodes",
        "elasticache:PurchaseReservedCacheNodesOffering"
      ],
      "Resource": "*"
    },
    {
      "Sid": "MemoryDBReservedNodes",
      "Effect": "Allow",
      "Action": [
        "memorydb:DescribeReservedNodesOfferings",
        "memorydb:PurchaseReservedNodesOffering"
      ],
      "Resource": "*"
    },
    {
      "Sid": "RedshiftReservedNodes",
      "Effect": "Allow",
      "Action": [
        "redshift:DescribeReservedNodeOfferings",
        "redshift:DescribeReservedNodes",
        "redshift:PurchaseReservedNodeOffering"
      ],
      "Resource": "*"
    },
    {
      "Sid": "OpenSearchReservedInstances",
      "Effect": "Allow",
      "Action": [
        "es:DescribeReservedInstanceOfferings",
        "es:DescribeReservedInstances",
        "es:PurchaseReservedInstanceOffering"
      ],
      "Resource": "*"
    },
    {
      "Sid": "DynamoDBReservedCapacity",
      "Effect": "Allow",
      "Action": [
        "dynamodb:DescribeReservedCapacityOfferings",
        "dynamodb:DescribeReservedCapacity",
        "dynamodb:PurchaseReservedCapacityOfferings"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EC2CapacityBlocksForML.OPTIONAL",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeCapacityBlockOfferings",
        "ec2:PurchaseCapacityBlock"
      ],
      "Resource": "*"
    }
  ]
}
```

{% endcode %}

The OpenSearch statement uses the `es:` prefix. OpenSearch kept that IAM namespace after AWS introduced the newer API name, so `es:` is correct here.

***

### Supported Customizations

Some organizations change the roles in `north-all-features.yaml` to meet their own security policies. The table lists the changes North supports for the cost and usage roles. For any other change, ask your North Customer Success contact before you deploy it.

| Change                                                                                                                                      | Supported | What to know                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remove the `cloudwatch-crossaccount.amazonaws.com` trust statement from `NorthCloudWatchCrossAccountAccessRole`                             | Yes       | Keep the statement that trusts `NorthCURReadOnly`. North uses that statement to read your Cost and Usage Reports.                                                                                          |
| Add an `aws:ResourceOrgID` condition so that `NorthCloudWatchCrossAccountAccessRole` can assume sharing roles only in your organization     | Yes       | -                                                                                                                                                                                                          |
| Remove the `:root` principal from the `NorthCloudWatchCrossAccountSharingRole` trust policy, in your management account and in the StackSet | Yes       | Keep `NorthCloudWatchCrossAccountAccessRole` as the trusted principal. North assumes the sharing roles only through that role.                                                                             |
| Remove the write permissions from `NorthCostAndUsageRolePremium`                                                                            | Yes       | Enroll in Compute Optimizer first. See [Removing Write Permissions from the Premium Role](/docs/getting-started/permissions-required/aws-permissions.md#removing-write-permissions-from-the-premium-role). |
| Use a different name for the CUR bucket                                                                                                     | Yes       | Send the bucket name to your North Customer Success contact, and North configures your account with it. The default name, `north-cur-bucket-<account-id>`, is preferred.                                   |
| Encrypt the CUR bucket with your own KMS key                                                                                                | No        | Keep the default SSE-S3 encryption (`AES256`). If North cannot decrypt your reports, your cost data stops arriving.                                                                                        |
| Trust named North roles in `NorthCostAndUsageRole` and `NorthCostAndUsageRolePremium`                                                       | No        | Keep North's account root as the principal, with an external ID if you use one. The North roles that assume these roles change as North releases new features.                                             |
| Deploy `NorthCostAndUsageRolePremium` in a member account, such as a Compute Optimizer delegated administrator                              | No        | Deploy it in your management account, with the rest of the stack.                                                                                                                                          |

#### Removing Write Permissions from the Premium Role

`NorthCostAndUsageRolePremium` includes permissions that enroll your organization in Compute Optimizer. After your organization is enrolled, you can remove them and keep a read-only role. Do these steps in this order. If you remove the permissions before you enroll, the enrollment does not happen, and North reports Compute Optimizer data for your management account only.

1. Enroll your organization in Compute Optimizer, with member accounts included.
2. Turn on trusted access for Compute Optimizer in AWS Organizations.
3. Remove `iam:CreateServiceLinkedRole`, `iam:PutRolePolicy`, and `organizations:EnableAWSServiceAccess` from the role.
4. Replace `compute-optimizer:*` with `compute-optimizer:Get*`.

Keep the read-only `Describe` and `List` actions and `organizations:ListAccounts` in the role. AWS enrolls member accounts that you add to your organization later.

***

### Important Security Best Practices

* **Always review permissions and restrict to least-privilege required for your use case and feature set.**
* Avoid granting broad, unnecessary permissions such as `"ec2:Describe*"` to any third party—including North.
* If you have questions on what each permission is used for, please contact our support team for a granular explanation.
* If you want additional protection, you may use an external ID in your trust relationship when granting North cross-account role access.

By adhering to these permission designs, you retain control and visibility into what North can access, and ensure your AWS environment stays secure and optimized.

***

{% hint style="info" %}
**Note:** Any required North account ID, role ARNs, and (optionally) external IDs can and will be provided securely to you by North during onboarding.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.north.cloud/docs/getting-started/permissions-required/aws-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.