> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pelanor.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Amazon Web Services (AWS)
> Understand how to connect Pelanor to your AWS accounts in order to pull billing data automatically.
# AWS Integration Overview
To integrate AWS billing data with Pelanor, open **Integrations → Add Integration → AWS** inside the platform and follow the step-by-step wizard.
## Prerequisites
* Access to your AWS organisation’s **management account**
* Two CloudFormation templates:
* `pelanor-integration-management.json`
* `pelanor-integration-subaccounts.json`
Note: Both templates will be available for download in the Integration Wizard, once you start the integration process.
## Installation Steps
Both the Management Account CloudFormation and the subaccount StackSets need to be executed in the us-east-1 region, regardless of where your resources are deployed.
Run the Management Account CloudFormation template once for the management account.\
If your organization has a shared billing account managed by your MSP which is already connected to Pelanor, you may skip this step.
1. Log in to the AWS **management account**.
2. Open **CloudFormation** in `us-east-1`.
3. Click **Create stack (with new resources)**.
4. Upload `pelanor-integration-management.json`.
5. Name the stack (e.g., `pelanor-management-integration`).
6. Click through the wizard, keeping defaults.
7. Wait until the stack reaches **CREATE\_COMPLETE**.
Run the StackSet on every AWS subaccount you wish to integrate into Pelanor.
1. In CloudFormation, open the **StackSet** tab.
2. Upload `pelanor-integration-subaccounts.json`.
3. Name the StackSet (e.g., `pelanor-subaccount-integration`).
4. In **Deployment options**, choose region `us-east-1` only.
5. Create the StackSet and wait until all targets show **SUCCEEDED**.
Although the integration is deployed only in `us-east-1`, it grants visibility over all AWS regions.
***
## Architecture & Permissions
This section provides a deep-dive into the IAM roles requested by the Pelanor AWS integration.
Pelanor requests the minimum practical AWS IAM permissions to collect cost data and surface optimisation insights.
You can adjust these permissions according to your preferences and security requirements.\
Note that this means that certain cloud costs or platform functionalities might not be available.
### Directly-Attached Permissions
| Permission | Why It’s Needed |
| --------------------------------------------------------- | --------------------------------------------- |
| `athena:BatchGet*`, `athena:List*` | Athena Cost Insights |
| `autoscaling:Describe*` | (Reserved) future EC2 scaling recommendations |
| `ce:Get*`, `ce:List*` | Cost Explorer cross-validation |
| `cloudfront:Get*`, `cloudfront:List*` | CloudFront Cost Insights |
| `cloudtrail:*` (Describe, Get, List, LookupEvents) | Map Athena queries → users |
| `cloudwatch:*` (Describe, Get, List) | Collect resource metrics |
| `compute-optimizer:*` | Opportunities (Cost Optimization) |
| `cur:*` | Manage CUR export |
| `dynamodb:*` (Describe, List) | Planned DynamoDB insights |
| `ebs:Describe*` | EBS Cost Insights |
| `ec2:*` (Describe, Get) | EC2 & network insights |
| `ecs:*` (Describe, Get, List) | ECS Cost Insights |
| `eks:*` (Describe, List) | EKS Cost Insights |
| `elasticache:Describe*`, `elasticloadbalancing:Describe*` | Planned ElastiCache insights |
| `elasticmapreduce:*` (Describe, Get…, List) | EMR Cost Insights |
| `emr-serverless:*` (Get, List) | EMR Serverless insights |
| `es:*` (Describe, List) | Network identifier resolution |
| `glue:*` (Get, List) | Glue Cost Insights |
| `kinesis:*` (Describe, Get, List) | (Reserved) future Kinesis insights |
| `lambda:List*` | Lambda Cost Insights |
| `organizations:*` (Describe, List) | Fetch sub-account metadata |
| `rds:*` (Describe, ListTagsForResource) | RDS Cost Insights |
| `redshift:Describe*` | Redshift Cost Insights |
| `resource-groups:*` (Get, List, Search) | Show tags for all resources |
| `s3:List*` | S3 Cost Insights |
| `savingsplans:Describe*` | Savings Plan coverage/utilisation |
Some permissions are requested ahead of roadmap features to minimise future IAM configuration.\
You may revoke any you don’t wish to authorise; affected insights will simply be disabled.
***
### CUR Permissions
The CloudFormation template includes standard IAM actions required to retrieve Cost & Usage Reports (CUR).\
Further information on these permissions is available upon request.
***
### Bucket Permissions
To access the S3 bucket that stores integration artefacts, the CloudFormation template also grants:
```
s3:GetBucketAcl
s3:GetBucketPolicy
s3:GetBucketVersioning
s3:GetLifecycleConfiguration
s3:GetObject
s3:GetObjectAttributes
s3:GetObjectVersionAttributes
s3:ListBucket
```
### Customized IAM Policy
In case your organization's security policies prevent certain permissions from being granted to third-party tools such as Pelanor, we can create a customized CloudFormation file with a limited set of permissions. Contact Pelanor Support for more information.
## Comparing Costs with AWS Cost Explorer
Follow the steps below to ensure a sufficient comparison of costs between Pelanor and AWS Cost Explorer.
Cost validation should be performed at least 5 days after the billing period ends, as AWS sometimes posts late adjustments.
### In AWS Cost Explorer
Log in to the AWS Console and open Cost Explorer.
Choose a full calendar month that ended at least 5 days ago.
Set Group by → Service.
- Charge Type – exclude Credits, Refunds, Tax.
- If you have special-priced services, exclude them under Service.
Set Cost aggregation = Net Unblended.
Uncheck Show forecasted values.
Note the total cost and each service cost for later comparison.
### In Pelanor
Launch **Cost Explorer** inside Pelanor.
Use the same date range selected in AWS Cost Explorer.
- Amortization → select Unblended.
- Payment Types → exclude Credits, Tax, Refunds.
If you excluded special-priced services in AWS, apply the same filters here.
Set Group by → AWS Product Name.
Note the total cost and each service cost.
## Comparing Results
* **Total Cost** – Pelanor vs. AWS (expected variance \< 1 %).
* **Per-Service Cost** – identify any services with higher discrepancies.
* Record services that exceed the threshold for further investigation.
If you run into any discreptancies, please reach out to the Pelanor Support team - we'll investigate and resolve any incosistencies. With your inquiry, include the date ranges you analyzed, as well as screenshots from both Pelanor and AWS Cost Explorer.
## Understanding AWS Tag Normalization
## Understanding AWS Tag Normalization in Pelanor
When AWS delivers Cost & Usage Report (CUR) data in Parquet format, it rewrites tag keys in a predictable way.\
Pelanor mirrors these transformations for every AWS data source—CUR files, APIs, or resource logs—so you see a single, consistent tag name.
### How Tag Normalization Works
AWS’s Parquet exporter alters tag keys automatically. Pelanor applies the same rules, ensuring tags from all AWS sources line up.
#### Transformation Rules
1. Insert an underscore (`_`) before every uppercase letter.
2. Convert all uppercase letters to lowercase.
3. Replace non-alphanumeric characters with an underscore.
4. Collapse duplicate underscores into a single underscore.
5. Trim leading or trailing underscores.
6. If the key still exceeds the column-length limit, drop underscores from left to right until it fits.
#### Examples
| Original Tag Key | Normalized Tag Key |
| ---------------- | ------------------ |
| ExampleTagName | example\_tag\_name |
| Example-Tag Name | example\_tag\_name |
| Environment | environment |
| CostCenter | cost\_center |
| AWS:Project | aws\_project |
### Why We Normalize Tags
* **Consistent experience** – tags look identical whether they come from CUR Parquet or direct API calls.
* **Simpler filtering** – no need to remember multiple spellings of the same tag.
* **Accurate cost allocation** – every source converges under one normalized key.
* **Comprehensive reports** – filtering by the tag captures all matching resources.
### Finding Your Original Tag Names
1. In AWS, open **Cost Explorer** or **Resource Groups & Tag Editor**.
2. Locate the tag keys in their original format.
3. Apply the transformation rules above to see how each key will appear in Pelanor.