# Connect AWS

# Connect AWS

Costfluent reads AWS cost through a read-only IAM role in your account. The role trusts one
Costfluent principal, and only with the external ID Costfluent issues to your organization. No
access keys are exchanged.

Cost comes from an AWS Data Export in the **FOCUS 1.2** format, delivered daily to a private S3
bucket in your own account. It carries amortized cost, list cost, charge categories, regions,
resource IDs and tags. Until the first delivery arrives, and for any month the export does not
cover, Costfluent reads Cost Explorer instead.

## Management and member accounts

Connect the **management account** of your AWS Organization once. Its export covers every member
account, and Costfluent lists the members on the connection. Connecting a member account as well
would count its cost twice, so Costfluent refuses a connection whose accounts another AWS
connection already covers.

A **member account** connected on its own gets the role only, and is read from Cost Explorer. A
standalone account is treated like a management account.

## Connect with the AWS Console

This is the default route. Open **Settings**, then **Integrations**, select **AWS**, and choose
**Connect Costfluent via AWS Console**.

1. Leave **This is a management or standalone account** on to create the export; turn it off for a
   member account.
2. AWS opens a CloudFormation quick-create page in **us-east-1**, with every parameter filled in.
   Acknowledge that the stack creates IAM resources, and create it.
3. When the stack finishes, it reports back to Costfluent, and the connection appears on the page
   without anything to paste. If the stack fails, the page and CloudFormation both show the reason,
   and the stack rolls back.

The link is valid for 24 hours and connects only to the organization that created it.

## Connect with the AWS CLI

Under **More connection options**, choose **AWS CLI**. Costfluent shows an
`aws cloudformation create-stack` command with the same template and parameters. Run it with
credentials for the account you are connecting:

```bash
aws cloudformation create-stack \
  --stack-name Costfluent-1a2b3c4d \
  --template-url <the template URL Costfluent shows> \
  --capabilities CAPABILITY_IAM \
  --region us-east-1 \
  --parameters ParameterKey=CostfluentPrincipalArn,ParameterValue=... # and the rest
```

The stack reports back exactly as the console route does.

## Connect with Terraform

The `costfluent/cost-access/aws` module creates the role and, when you name a bucket, the bucket
and the export. The `costfluent_aws_provider_info` data source reads the principal and external ID
for you:

```hcl
provider "aws" {
  region = "us-east-1"
}

data "costfluent_aws_provider_info" "this" {}

module "costfluent_aws" {
  source  = "costfluent/cost-access/aws"
  version = "~> 0.2"

  costfluent_principal_arn = data.costfluent_aws_provider_info.this.principal_arn
  external_id              = data.costfluent_aws_provider_info.this.external_id
  cost_export_bucket_name  = "acme-costfluent-export" # omit in a member account
}

resource "costfluent_provider" "aws" {
  key         = "aws"
  name        = "AWS"
  credentials = module.costfluent_aws.credentials
  settings    = module.costfluent_aws.settings
}
```

`costfluent_provider` retries for up to three minutes while the new role propagates through IAM.
To keep the delivered files in the EU, set `cost_export_bucket_region`; the export itself always
runs in us-east-1.

## Connect with the IAM console

Under **More connection options**, choose **AWS IAM Console**. Costfluent shows your external ID,
the trust policy and the permissions policy. Create a role with both, then enter its ARN, and the
export bucket if you created one.

If you create the export yourself, it must be a **FOCUS 1.2 with AWS columns** export
(`FOCUS_1_2_AWS`) with every column selected, daily granularity, CSV with GZIP compression, and
**Overwrite existing data export file**, delivered to a bucket the role can read, under the prefix
`costfluent` with the export name `costfluent-focus`.

## What Costfluent is granted

| Action | Resource | Why |
|---|---|---|
| `ce:GetCostAndUsage` | `*` | History before the export's first delivery, accounts without an export, and the monthly control total. |
| `organizations:ListAccounts` | `*` | Which member accounts a management account's cost covers. |
| `s3:ListBucket` | the export bucket | Finds each month's delivery. |
| `s3:GetObject` | the export bucket's objects | Reads that delivery. |

Cost Explorer and Organizations have no resource-level permissions, so their resource is `*`; it
grants no access to anything else in the account. The S3 grant exists only when there is an export.

## History and first delivery

AWS delivers the first export within **24 to 72 hours** of creating it. Until then, the connection
shows cost from Cost Explorer, and Costfluent replaces it with the export's rows once the delivery
arrives. Costfluent re-reads the current month on every sync, and the previous month for the first
fifteen days, because AWS updates the previous month for up to two weeks after it closes.

A new export starts with the current month. To bring up to 14 months of history into it, open a
case with AWS Support (**Billing**, **Data Exports**) asking to backfill the export, then ask
Costfluent support to re-collect those months once AWS confirms.

## What it costs you

Costfluent reads the export from outside AWS, so reading it is S3 data transfer out on your bill. A
daily export is typically a few megabytes a month. Each Cost Explorer request Costfluent makes costs
USD 0.01, and Costfluent makes them only for months the export does not cover, for connection
checks, and for the monthly control total.

## After connecting

The **Manage** tab lists the connection by its account ID, with its role and export bucket. Open
the gear icon beside it to see whether the role can still be assumed and the bucket read, which
workspaces the connection feeds, and which billing months have been imported. **Run checks** runs
those checks again and reports each one separately.

## Removing access

Delete the CloudFormation stack, or run `terraform destroy`, to remove the role; Costfluent's access
ends with it. The export bucket is kept, so your history stays in your account. Remove the
connection in Costfluent as well.