Amazon Web Services

How OptCloud connects with AWS

OptCloud uses the AWS-recommended Cross-Account IAM Role pattern with a unique External ID. In Cloud Accounts choose Connect via AWS Console or Connect via CLI: we generate an External ID for this connection, you deploy our CloudFormation stack (OptCloudReadOnly) in your AWS account (Download + Upload template in the Console, or aws cloudformation deploy), then paste the Role ARN back into OptCloud. Before saving, OptCloud calls AWS STS AssumeRole from our hub account using that External ID — if the Account ID, Role ARN, or External ID is wrong, the account is not connected and nothing is stored. We never ask for or store long-lived AWS access keys. The role grants read-only Cost Explorer, CUR, and inventory APIs; we only collect billing and inventory metadata — never application data from EC2, S3 objects, or databases. After a successful verification the account shows Connected and Awaiting first sync until cost ingestion is enabled.

Required permissions (read-only)

• ce:Get* / ce:Describe* / ce:List* (Cost Explorer) — high-level historical spend
• cur:Describe* and related report APIs / S3 read on CUR buckets — detailed line items
• ec2:Describe*, rds:Describe*, s3:List*, eks:Describe*/List*, lambda:List*/GetFunctionConfiguration — inventory metadata for recommendations
• organizations:ListAccounts (optional) — multi-account rollups under AWS Organizations
• compute-optimizer:Get* / Describe* (optional) — additional rightsizing signals when Compute Optimizer is enabled

The CloudFormation template creates role OptCloudReadOnly (name must start with OptCloud). Trust is limited to OptCloud's hub account and requires your unique External ID on every sts:AssumeRole. No long-lived access keys are stored; OptCloud never requests mutation APIs such as iam:Create* or ec2:TerminateInstances.

Saving a connection only means STS AssumeRole succeeded — the account is registered and ready for sync. Dashboard KPIs and Cost Explorer stay empty until OptCloud's cost sync (Cost Explorer API and/or CUR) runs. When CUR is enabled, AWS can take up to 24 hours to deliver the first report; the first CUR typically covers the current month only. Until the first sync lands, Overview, Rightsizing, and Idle Resources show honest empty states rather than invented numbers.

Repeat Connect via AWS Console or CLI for each account you want OptCloud to see (each gets its own External ID and CloudFormation stack). If you use AWS Organizations, connect the management (payer) account first when you want consolidated costs. Connecting only a member account limits visibility to that account's spend. Organization-wide discovery of linked accounts will expand as cost sync matures.

Create a connection via Console

1. 1

   Open Connect AWS in OptCloud

   Sign in → Cloud Accounts → Connect account → Amazon Web Services. Click Connect via AWS Console. Enter an account name, the 12-digit AWS Account ID, and a team (defaults to Platform). OptCloud generates a unique External ID for this connection — copy it; you will paste it into the CloudFormation ExternalId parameter.

2. 2

   Deploy the OptCloudReadOnly CloudFormation stack

   Click Download template first, then Open CloudFormation (opens Create stack → Template in us-east-1). Choose Upload a template file, select the downloaded YAML, set stack name OptCloudReadOnly, paste the dialog External ID into ExternalId, keep RoleName OptCloudReadOnly. Acknowledge that CloudFormation may create IAM resources, then create the stack. (AWS rejects non-S3 TemplateURLs such as optcloud.tech — upload is required unless an S3 template URL is configured.)

3. 3

   Copy the Role ARN from stack Outputs

   Wait until the stack status is CREATE_COMPLETE. Open the Outputs tab and copy RoleArn (it looks like arn:aws:iam::YOUR_ACCOUNT_ID:role/OptCloudReadOnly). Do not invent or edit this value.

4. 4

   Paste the Role ARN and save in OptCloud

   Back in the OptCloud dialog, choose I created the stack — continue, paste the Role ARN, then Save connection. The button shows Verifying with AWS… while OptCloud calls STS AssumeRole with your External ID.

5. 5

   Confirm Connected — only after verification succeeds

   If Account ID, Role ARN, or External ID do not match what AWS expects, the connection is rejected and nothing is saved. On success you land on Cloud Accounts with status Connected and Awaiting first sync. Cost Explorer numbers appear after the cost sync step — not at connect time.

Create a connection via AWS CLI

Same IAM role and STS verification as Console — deploy with aws cloudformation deploy instead of the browser quick-create wizard.

1. 1

   Open Connect via CLI in OptCloud

   Sign in → Cloud Accounts → Connect account → Amazon Web Services → Connect via CLI (or More Connection Options → Connect via CLI). Enter an account name, the 12-digit AWS Account ID, and a team (defaults to Platform). OptCloud shows a unique External ID and a ready-to-run script — do not change the External ID in the commands.

2. 2

   Run the AWS CLI script in the target account

   In a terminal where the AWS CLI is authenticated to that Account ID: download optcloud-readonly-role.yaml (Copy commands includes curl when the app URL is public; on localhost use Download template and save the file next to your shell). Then run aws cloudformation deploy with stack name OptCloudReadOnly, ExternalId and RoleName from the dialog, --capabilities CAPABILITY_NAMED_IAM, region us-east-1.

3. 3

   Print and copy the Role ARN

   Run the describe-stacks command from the dialog (or copy it from the script). It prints RoleArn only — paste that exact value. Do not invent an ARN.

4. 4

   Paste Role ARN and save — STS verification required

   In OptCloud choose I deployed the stack — continue, paste RoleArn, then Save connection. OptCloud calls the same STS AssumeRole verifier as Console. Wrong Account ID, Role ARN, or External ID will not connect and nothing is stored.

5. 5

   Confirm Connected

   On success the account appears under Cloud Accounts as Connected / Awaiting first sync. Cost data arrives after the cost sync step — not at connect time.

Historical cost data (after sync is enabled)

Once Cost Explorer / CUR ingestion is live, high-level totals can come from Cost Explorer quickly; full resource- and tag-level filtering typically needs CUR delivery (often up to 24 hours for the first report). The first CUR usually covers the current month — for older months, request a CUR backfill from AWS for the export OptCloud uses, then ask us to re-ingest. Until then, dashboards stay empty rather than showing placeholder spend.

Once connected, you can filter and group cost data in Cost Explorer and Reports by:

• Account — AWS account name and ID
• Category — compute, storage, network, database, other (OptCloud's normalized category)
• Service — e.g. EC2, RDS, S3, EKS
• Region — e.g. us-east-1, eu-west-1
• Resource — specific resource ID (instance, volume, load balancer, etc.)
• Tag / Not tagged — any AWS cost allocation tag key and value
• Usage type and operation — the underlying CUR usage type driving the charge
• Charge type — usage, tax, credit, refund, Savings Plan/RI amortization

To rotate the External ID or refresh the role policy, remove the account in Cloud Accounts (optional), delete or update the OptCloudReadOnly stack in AWS, then run Connect via AWS Console or CLI again with a new External ID from OptCloud. Do not reuse an old External ID with a new OptCloud dialog — verification will fail. In-place Update Connection UI ships later.

Troubleshooting

Related integrations

Kubernetes

Cluster agent / metrics + cloud bill allocation

Datadog

Datadog Usage API (read)