Amazon Web Services

Connect an AWS account to CostGraph for FOCUS-based cost, allocation, and cross-provider recommendations

CostGraph reads your AWS spend from a FOCUS Data Export delivered to S3. Unlike Google Cloud, AWS exposes a full API for this, so the entire setup is automated: one CloudFormation stack, a CloudShell command, or a short Terraform module creates the export and the read role. Terraform covers the export and, optionally, the recommendations policy, but not the rest of the read role.

What you enable

A single FOCUS 1.2 Data Export (FOCUS_1_2_AWS) written as Parquet to an S3 bucket. It carries billed and effective cost, usage, credits, and commitment (Savings Plans / Reserved Instances) columns in the normalized FOCUS schema.

AWS savings recommendations are on by default. They are free and you can turn them off by clearing Show AWS savings recommendations in the connect dialog. See Savings recommendations.

Network access is on by default. To turn it off, clear Show how your resources connect in the connect dialog. See Network access.

By default, the setup also adds a separate automation role, so Workflows can make the changes you approve, including cleanup. Clear Let Workflows make approved changes, or only Also allow cleanup, in the connect dialog to leave it out.

Setup with CloudFormation (recommended)

Launch in AWS appears in the connect dialog once CostGraph has the stack template available. Until then, use CloudShell below.

1. Open Settings > Integrations, pick Amazon Web Services, and select Launch in AWS.
2. Sign in to the management (payer) account. The console opens with the CostGraph stack filled in.
3. Review the stack, acknowledge that it creates an IAM role, and select Create stack.
4. When the stack finishes, copy its outputs into the connect form.

The stack creates the same read role, export bucket, and FOCUS data export as the CloudShell script. A stack can’t adopt resources that already exist. If you set up the account with the script, keep using the script.

The stack also has an EnableRecommendations parameter, on by default. When on, it turns on AWS’s free Cost Optimization Hub and Compute Optimizer and adds a CostGraph-RecommendationsRead policy to the CostGraph-Reader role. The paid 93-day lookback stays off. The stack output RecommendationsStatus reports the result. Set the parameter to false to skip it.

The EnableNetworkInventory parameter is on by default. It grants network access, which connects your resources in Context without an agent. The stack output NetworkInventoryStatus reports enabled or disabled. Set it to false to skip it.

The EnableAutomation and EnableAutomationCleanup parameters are on by default. They create the automation role Workflows uses, with cleanup allowed. Set EnableAutomationCleanup to false to leave out cleanup, or EnableAutomation to false to skip the role.

Setup in CloudShell

If Launch in AWS isn’t shown, or you’d rather not launch a stack, the connect dialog shows a one-line command. Open AWS CloudShell in the management (payer) account and run it:

curl -sSL https://setup.costgraph.ai/integrations/aws.sh \
  | COSTGRAPH_EXTERNAL_ID="org_..." sh

CloudShell already carries your console credentials, so nothing is stored or pasted anywhere else. The script creates the read role (trusting CostGraph’s identity, locked to your external ID), the export bucket with public access blocked and encryption on, and the FOCUS 1.2 Data Export. It is idempotent, so rerun it safely.

It prints four values. Paste them into the connect form:

ROLE_ARN=arn:aws:iam::123456789012:role/CostGraph-Reader
BUCKET=costgraph-focus-123456789012
REGION=us-east-1
PREFIX=focus-1-2

The external ID is issued by CostGraph and ties the role to your organization. It stops anyone else who learns your role ARN from assuming it. Never edit it out of the command.

The script also turns on AWS’s free Cost Optimization Hub and Compute Optimizer and adds the CostGraph-RecommendationsRead policy to the read role. Set COSTGRAPH_ENABLE_RECOMMENDATIONS=0 to skip it. It prints a RECOMMENDATIONS_STATUS line with one of enabled, member_account, or not_enrolled.

The script grants network access unless COSTGRAPH_ENABLE_NETWORK_INVENTORY=0, which removes it. It prints a NETWORK_INVENTORY_STATUS line with enabled or disabled.

It also creates the automation role Workflows uses, with cleanup allowed. Set COSTGRAPH_ENABLE_AUTOMATION_CLEANUP=0 to leave out cleanup, or COSTGRAPH_ENABLE_AUTOMATION=0 to skip the role.

Set COSTGRAPH_BUCKET to use an existing bucket, or COSTGRAPH_EXPORT_REGION if you are in a different partition (GovCloud, China).

Setup with Terraform

Prefer infrastructure as code? The Terraform below creates the export bucket and FOCUS data export, but not the read role. Create the role with the trust policy and external ID shown in the connect flow, then use its ARN as ROLE_ARN. The export is created in us-east-1 (where AWS billing data lives), so aws_bcmdataexports_export must be managed by an AWS provider configured for that region. If your root provider targets another region, add an aliased one and point the export at it.

provider "aws" {
  alias  = "billing"
  region = "us-east-1"
}

data "aws_caller_identity" "current" {}

resource "aws_s3_bucket" "focus" {
  bucket = "costgraph-focus-export-${data.aws_caller_identity.current.account_id}"
}

resource "aws_s3_bucket_policy" "focus" {
  bucket = aws_s3_bucket.focus.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Sid       = "EnableAWSDataExportsWrite"
      Effect    = "Allow"
      Principal = { Service = "bcm-data-exports.amazonaws.com" }
      Action    = ["s3:PutObject"]
      Resource  = ["${aws_s3_bucket.focus.arn}/*"]
      Condition = {
        StringLike   = { "aws:SourceArn" = "arn:aws:bcm-data-exports:us-east-1:${data.aws_caller_identity.current.account_id}:export/*" }
        StringEquals = { "aws:SourceAccount" = data.aws_caller_identity.current.account_id }
      }
    }]
  })
}

resource "aws_bcmdataexports_export" "focus" {
  provider = aws.billing

  export {
    name = "costgraph-focus-1-2"
    data_query { query_statement = "SELECT * FROM FOCUS_1_2_AWS" }
    destination_configurations {
      s3_destination {
        s3_bucket = aws_s3_bucket.focus.id
        s3_prefix = "focus-1-2"
        s3_region = "us-east-1"
        s3_output_configurations {
          output_type = "CUSTOM"
          format      = "PARQUET"
          compression = "PARQUET"
          overwrite   = "OVERWRITE_REPORT"
        }
      }
    }
    refresh_cadence { frequency = "SYNCHRONOUS" }
  }
}

First Parquet files land within about 24 hours.

To also show AWS savings recommendations, add an inline policy named CostGraph-RecommendationsRead to the read role. Use your role’s name if it differs from CostGraph-Reader:

resource "aws_iam_role_policy" "recommendations" {
  name = "CostGraph-RecommendationsRead"
  role = "CostGraph-Reader"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "cost-optimization-hub:ListRecommendations",
        "cost-optimization-hub:GetRecommendation",
        "cost-optimization-hub:ListRecommendationSummaries",
        "cost-optimization-hub:ListEnrollmentStatuses",
        "cost-optimization-hub:GetPreferences",
      ]
      Resource = "*"
    }]
  })
}

Then turn the AWS services on once, from the management account:

aws cost-optimization-hub update-enrollment-status --region us-east-1 \
  --status Active --include-member-accounts
aws compute-optimizer update-enrollment-status --region us-east-1 \
  --status Active --include-member-accounts

Read access

CostGraph reads the export bucket with a cross-account role granting s3:GetObject and s3:ListBucket on the export prefix, plus the cost allocation tag permission described below. The connect flow provides the exact trust policy and external ID.

With savings recommendations on, the role also gets read-only access to AWS’s recommendations:

• cost-optimization-hub:ListRecommendations
• cost-optimization-hub:GetRecommendation
• cost-optimization-hub:ListRecommendationSummaries
• cost-optimization-hub:ListEnrollmentStatuses
• cost-optimization-hub:GetPreferences

With network access on, the role also gets a read-only CostGraph-NetworkRead policy. It reads your network layout, and the managed databases, caches, and shared file systems your workloads talk to, so Context can name them:

• ec2:DescribeNatGateways
• ec2:DescribeNetworkInterfaces
• ec2:DescribeRegions
• ec2:DescribeRouteTables
• ec2:DescribeSubnets
• ec2:DescribeVolumes
• ec2:DescribeVpcEndpoints
• eks:DescribeCluster
• eks:ListClusters
• elasticache:DescribeCacheClusters
• elasticache:DescribeReplicationGroups
• elasticfilesystem:DescribeFileSystems
• elasticfilesystem:DescribeMountTargets
• elasticloadbalancing:DescribeLoadBalancers
• elasticloadbalancing:DescribeTargetGroups
• elasticloadbalancing:DescribeTargetHealth
• rds:DescribeDBInstances

Cost allocation tags

AWS only includes a tag in billing data once the tag is active for cost allocation. After you connect, and on each sync, CostGraph activates tags that are still inactive.

The read role carries one write permission for this: changing the status of cost allocation tags. It can’t change anything else in your account.

Activation isn’t retroactive. Spend from before a tag was activated doesn’t carry it. To fill in that history, an owner of the account can request an AWS backfill.

The connect form has an Activate cost allocation tags checkbox, on by default. Clear it to opt out, and CostGraph then only reads the tags you’ve already activated. Connections created before this option existed aren’t activated until you reconnect them.

Connect in CostGraph

1. Open Settings > Integrations and pick Amazon Web Services.
2. Launch the stack, run the CloudShell command shown there, or apply the Terraform above.
3. Paste the ROLE_ARN, BUCKET, REGION, and PREFIX the stack or script produced, then connect.
4. CostGraph assumes the role, validates it can read the export, and starts the first sync.

Push it yourself

If you would rather not grant a cross-account role, run the exporter in your own account instead. It reads the same Data Export from S3 and pushes the records, so nothing but the FOCUS rows leaves your account:

provider: objectstore
sink: costgraph
OBJECTSTORE_BUCKET: my-focus-export
OBJECTSTORE_PREFIX: focus-1-2/
OBJECTSTORE_LAYOUT: manifest

No keys: give the exporter’s role s3:ListBucket and s3:GetObject on the export bucket and it uses the role it runs as. manifest reads exactly the files the export names, which is what AWS writes beside the data.

What CostGraph does with it

• Cost: FOCUS line items normalized to the same canonical model as every other provider, keeping billed and effective cost, credits, and commitment attribution.
• Reconciliation: allocated plus unallocated cost is checked to equal the invoice per billing account per month.
• Allocation: spend attributed by resource, tag, and account, with an explicit unallocated bucket for tax, shared, and commitment costs.

Network access

Network access is the quickest way to fill in Context when only your bill is connected. With it, CostGraph reads your AWS inventory and connects what you run. Context shows each VPC and subnet with its instances and EKS clusters, and the volumes, file systems, NAT gateways, and load balancers they use. When network flow tracing also runs, Context names the private traffic between them.

Network access is read-only and on by default. It covers the account where you create the stack or run the script. It doesn’t read data, logs, or secrets. To also see workloads, usage, and live traffic, install the CostGraph Agent or the CostGraph Operator.

Turn it on for an existing connection

If you set up the account with the stack, select Grant network access in Context. It opens the update for your CostGraph stack in us-east-1, with the current template and EnableNetworkInventory set to true. The update replaces the template, because a stack created before network access existed has no EnableNetworkInventory parameter. Review it, acknowledge that the stack changes IAM resources, and select Submit. When the update finishes, the NetworkInventoryStatus output reads enabled.

If you set up the account with CloudShell, rerun the command from the connect dialog with COSTGRAPH_ENABLE_NETWORK_INVENTORY=1:

curl -sSL https://setup.costgraph.ai/integrations/aws.sh \
  | COSTGRAPH_EXTERNAL_ID="org_..." COSTGRAPH_ENABLE_NETWORK_INVENTORY=1 sh

If you manage the role yourself, add an inline policy named CostGraph-NetworkRead with the actions listed in Read access.

You don’t need to reconnect. CostGraph picks up the new access within the hour.

Savings recommendations

With recommendations on, AWS’s own savings recommendations appear in Insights next to CostGraph’s. Each one shows two numbers: AWS’s estimate, and CostGraph’s price calculated from your bill.

• Purchase recommendations (Savings Plans and Reserved Instances) and recommendations CostGraph can’t price yet show the monthly spend they affect, not a saving. They don’t add to the savings total.
• When CostGraph already flags the same resource, you see one item that says whether AWS agrees.

The connection card in Settings > Integrations tells you what to do if access or enrollment is missing.

Turn them on for an existing connection

Re-run the CloudShell command, or update the stack with EnableRecommendations set to true. Both turn on the AWS services and add the read policy for you.

If you cleared Show AWS savings recommendations when you connected, also connect the account again with the box checked.

If you manage the role yourself, run the two commands from Setup with Terraform from the management account, one time. Also add the CostGraph-RecommendationsRead policy to the read role, as shown there.

Recommendations appear up to 24 hours after you turn them on. A connection to a member account only shows recommendations if the management account turned them on for member accounts.