Setting up an AWS Cost and Usage Integration

Automated setup

Automated setup creates all required AWS resources through a CloudFormation stack.

1. Click Open AWS Console. This opens the AWS CloudFormation console with a pre-configured stack that creates:

   • An S3 bucket for CUR data
   • A CUR 2.0 Parquet export configuration
   • A scoped read-only IAM role that grants CloudQuery access to the bucket

2. In the AWS CloudFormation console, review the stack parameters and click Create stack.

3. Return to CloudQuery Platform. The setup screen polls for progress and shows the current status:

   • Setting up — Waiting for the CloudFormation stack to be applied.
   • Finalizing setup — Stack applied. CloudQuery is validating access and finalizing configuration.
   • Setup complete — CloudQuery populates the Role ARN and report name automatically.

4. Click Test Connection to verify access.

Manual setup

Use manual setup if you already have a CUR 2.0 Parquet export configured in your AWS account.

Prerequisites for manual setup

• A CUR 2.0 data export with Parquet file format, delivering to an S3 bucket. If you don’t have one, create it in the AWS Billing > Data Exports console.
• Your Tenant ID, visible in the setup guide panel when configuring the integration.
• An External ID — any alphanumeric string between 2 and 1224 characters. Generating a UUID (e.g. uuidgen) is recommended per AWS best practices.

IAM role and permissions

1. Create an IAM policy granting read access to your CUR S3 bucket.

Replace <YOUR_BUCKET> with the name of the S3 bucket where your CUR data is stored.

cat >bucket-policy.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::<YOUR_BUCKET>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::<YOUR_BUCKET>/*"
        }
    ]
}
EOF

2. Create the trust relationship for the cross-account role.

Replace <CLOUDQUERY_AWS_ACCOUNT_ID> with the CloudQuery AWS Account ID found in the side panel documentation on the plugin UI page in CloudQuery Platform. Replace <TENANT_ID> with your tenant ID from the “Setup guide” section when configuring the integration. Replace <EXTERNAL_ID> with your generated external ID.

cat >third-party-trust.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<CLOUDQUERY_AWS_ACCOUNT_ID>:role/syncs-<TENANT_ID>-role"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<EXTERNAL_ID>"
                }
            }
        }
    ]
}
EOF

3. Create the cross-account role and attach the S3 read policy:

aws iam create-role --role-name cross-account-readonly-role-cost-usage \
    --assume-role-policy-document file://third-party-trust.json
 
aws iam put-role-policy --role-name cross-account-readonly-role-cost-usage \
   --policy-name ReadS3Policy --policy-document file://bucket-policy.json

Configure the integration

Back in CloudQuery Platform:

1. Enter the Role ARN of the IAM role you created (e.g. arn:aws:iam::<YOUR_ACCOUNT_ID>:role/cross-account-readonly-role-cost-usage).
2. Enter the External ID you used in the trust relationship.
3. Under Reports, enter the report name for your CUR export. You can find this in the AWS Billing > Data Exports console under your export’s settings. Add additional reports with the Add report button if needed.
4. Click Test Connection to verify access.