AWS Guide

Connect CloudOpt to your AWS account and collect data for analysis.

CloudOpt reads AWS through the standard SDK credential chain. It does not call write APIs.

Prerequisites

• AWS credentials on the host running CloudOpt
• Read-only IAM for the services you plan to scan (policies below)
• For cross-account work: a role ARN CloudOpt can assume

Credential sources: env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), ~/.aws/credentials, or an instance/container IAM role.

Full workflow

cloudopt init

cloudopt collect aws inventory --regions us-east-1,eu-west-1

cloudopt collect aws cost --lookback-days 30

cloudopt collect aws metrics --lookback-days 14

cloudopt analyze
cloudopt report --format html

What each collect step pulls

Inventory

• EC2 instances and instance types
• EBS volumes and snapshots
• VPCs, subnets, NAT gateways, route tables, Elastic IPs
• RDS instances

Limit scope with --regions, --regions-allow, or --regions-deny. Run with --dry-run first to confirm permissions.

Costs

Cost Explorer data (default lookback: 30 days):

• Amortized and unblended metrics
• Credits, refunds, taxes, support lines
• Resource attribution where Cost Explorer allows it

Check totals after collection:

cloudopt cost-reconcile

Metrics

CloudWatch data for EC2, EBS, RDS, and NAT gateways (default lookback: 14 days):

• CPU, network, storage raw metrics
• Derived signals: mean, max, p95, idle periods, trend

Rightsizing and idle-instance checks need this step.

IAM permissions

Attach read-only policies to the IAM user or role CloudOpt runs as. One policy per collection type.

Inventory

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity",
        "ec2:DescribeRegions",
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeVolumes",
        "ec2:DescribeSnapshots",
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeRouteTables",
        "ec2:DescribeNatGateways",
        "ec2:DescribeAddresses",
        "rds:DescribeDBInstances"
      ],
      "Resource": "*"
    }
  ]
}

Cost Explorer

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetDimensionValues",
        "ce:GetCostForecast",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

CloudWatch metrics

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

Copy-paste JSON also lives in the CloudOpt repository under each adapter directory.

Cross-account access

Assume a member-account role from a management account or CI runner:

cloudopt collect aws inventory \
  --role-arn arn:aws:iam::123456789012:role/CloudOptReadOnly \
  --external-id your-external-id \
  --regions us-east-1

The role must trust your caller and carry the read-only actions above.

Partial snapshots

When a region or service fails (often a permission gap), CloudOpt saves a partial snapshot with per-unit coverage notes. Analysis skips partial snapshots by default. Fix IAM, re-run collect.

Multiple regions

cloudopt collect aws inventory --regions us-east-1,eu-west-1,ap-southeast-1

Regions collect concurrently (default: 3 at a time) with retries.

Offline testing

Use --offline with recorded fixtures. See Try without cloud access.