Docs / Cloud Accounts / Connect AWS Account

Connect AWS Account

Published · Last updated: June 2026 · 10 min read

Overview

CloudAIPilot connects to your AWS account using IAM Cross-Account Role Assumption — not static access keys. You create an IAM Role in your AWS account, grant CloudAIPilot permission to assume it, and paste the Role ARN. CloudAIPilot never stores your root credentials or long-lived access keys.

You retain full control: to revoke access at any time, delete or disable the IAM Role from your own AWS console.

Security & PQC Note

Your AWS role ARN and all cloud credentials are encrypted at rest using Post-Quantum Cryptography (PQC) standards (ML-KEM-768). CloudAIPilot is among the first SaaS platforms to offer quantum-safe protection for cloud provider credentials.

Before You Begin

You will need:

  • An AWS account with IAM administrator access
  • The CloudAIPilot AWS Account ID and your organisation's unique External ID — both shown in the connection dialog inside your CloudAIPilot dashboard

Step-by-Step Guide

Step 1: Open the AWS IAM Console

  1. Log in to your AWS Management Console.
  2. Navigate to IAM → Roles and click Create role.

Step 2: Select Trusted Entity

  1. Under Trusted entity type, choose AWS account.
  2. Select Another AWS account.
  3. Enter the CloudAIPilot AWS Account ID shown in the connection panel on the left.
  4. Check Require external ID and paste your organisation's External ID from the same panel.

The External ID prevents the "confused deputy" attack — it ensures only CloudAIPilot's platform, acting on behalf of your specific organisation, can assume this role.

Step 3: Attach Managed Policies

Search for and attach the following AWS-managed policies:

Server management:

  • AmazonEC2FullAccess — provision and manage EC2 instances
  • AmazonVPCFullAccess — networking and security groups (firewalls)
  • AmazonSSMReadOnlyAccess — read SSM parameter store and instance inventory
  • CloudWatchReadOnlyAccess — read CloudWatch metrics for monitoring

Managed Databases:

  • AmazonRDSFullAccess — provision and manage RDS databases (PostgreSQL, MySQL, MariaDB)
  • AmazonElastiCacheFullAccess — provision and manage ElastiCache clusters (Redis, Memcached)

Storage:

  • AmazonS3FullAccess — backup vault and file storage (attach if you plan to use the offsite backup feature)

FinOps & billing:

  • AWSBillingReadOnlyAccess — read billing and cost data for the FinOps dashboard

Prefer least-privilege? See KB-01-05: Verify Permissions and Fix IAM Issues for a minimal custom policy alternative.

Step 4: Name the Role

Give the role a descriptive name — e.g., CloudAIPilotRole. Click Create role.

Step 5: Add the SSH Access Inline Policy

CloudAIPilot uses EC2 Instance Connect to inject temporary, short-lived SSH keys for server access. Open the newly created role → Permissions tab → Add permissions → Create inline policy → click the JSON tab and paste:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "ec2-instance-connect:SendSSHPublicKey",
    "Resource": "*"
  }]
}

Name this policy CloudAIPilot-SSH-Access and click Create policy.

For fully automatic SSH recovery (e.g., re-importing previously removed servers), also add a second inline policy that grants SSM command permissions:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ssm:SendCommand",
      "ssm:GetCommandInvocation",
      "ssm:DescribeInstanceInformation",
      "ec2:AssociateIamInstanceProfile",
      "ec2:DescribeIamInstanceProfileAssociations",
      "iam:GetRole",
      "iam:CreateRole",
      "iam:AttachRolePolicy",
      "iam:GetInstanceProfile",
      "iam:CreateInstanceProfile",
      "iam:AddRoleToInstanceProfile",
      "iam:PassRole"
    ],
    "Resource": "*"
  }]
}

This lets CloudAIPilot recover SSH access via SSM even if the instance does not have the ec2-instance-connect package installed.

Step 6: Enable Cost Explorer (Required for FinOps Dashboard)

For the FinOps dashboard to display your real AWS spend:

  1. AWSBillingReadOnlyAccess is already attached from Step 3.
  2. Enable AWS Cost Explorer once at: Billing & Cost Management → Cost Explorer → Enable Cost Explorer.

Cost data appears in CloudAIPilot within 24 hours of enabling.

If you prefer a least-privilege inline policy instead of the managed billing policy:

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

Without this step, server provisioning still works — only the FinOps dashboard will show no data for this AWS account.

Step 7: (Recommended) Enable Cost & Usage Reports for Per-Resource Cost Breakdown

Cost Explorer returns spend rolled up by service and region. To see per-server, per-database, and per-snapshot cost attribution in the FinOps drill-down, enable a Cost & Usage Report (CUR):

  1. Go to Billing & Cost Management → Cost & Usage Reports → Create report.
  2. Report name: cloudaipilot-cur (any name works).
  3. Tick Include resource IDs (required) and Include split cost allocation data (recommended).
  4. Time granularity: Daily · Format: Parquet · Compression: GZIP.
  5. Pick or create an S3 bucket in the same AWS account; prefix cur/ is fine.
  6. Refresh automatically: ON. AWS publishes the first export within ~24 hours.

Then add a CUR reader inline policy to the same CloudAIPilot role (replace YOUR-CUR-BUCKET with the bucket name you chose above):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cur:DescribeReportDefinitions",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket", "s3:GetObject"],
      "Resource": [
        "arn:aws:s3:::YOUR-CUR-BUCKET",
        "arn:aws:s3:::YOUR-CUR-BUCKET/*"
      ]
    }
  ]
}

Without CUR, the FinOps dashboard shows total AWS spend by service. With CUR, every cost row carries its resourceId and tags — unlocking per-resource cost attribution, anomaly detection, and waste findings.

Step 8: Copy the Role ARN and Connect

  1. From the role's summary page, copy the ARN (starts with arn:aws:iam::).
  2. Back in CloudAIPilot, go to Cloud Accounts → Add Account → AWS.
  3. Paste the Role ARN into the IAM Role ARN field and click Test & Connect.
  4. CloudAIPilot performs a background pre-flight check to verify the trust policy and permissions before saving.

Common Connection Errors

"An error occurred (AccessDenied) when calling the AssumeRole operation"
The trust policy on the IAM Role does not match. Check two things: (1) the CloudAIPilot AWS Account ID is exactly as shown in the connection panel, and (2) the External ID in the trust policy matches your organisation's External ID. Even a single character difference causes this error.
"Role ARN format is invalid"
The ARN must start with arn:aws:iam::. Make sure you copied it from the IAM Role summary page and not from a policy document (which uses different ARN formats).
Pre-flight check passes but no regions appear when provisioning servers
The AmazonEC2FullAccess or AmazonVPCFullAccess policy is missing or was attached to the wrong entity. Open the IAM Role → Permissions tab and confirm both policies are listed there.
FinOps dashboard shows no data after connecting
Two separate steps are required: (1) Cost Explorer must be enabled once in the AWS Billing console (it is not on by default), and (2) the AWSBillingReadOnlyAccess policy (or the inline Cost Explorer policy from Step 6) must be attached to the role. Check both.
SSH to a newly provisioned server fails via CloudAIPilot
The ec2-instance-connect:SendSSHPublicKey inline policy from Step 5 is missing or the ec2-instance-connect package is not installed on the instance. For the latter case, add the SSM recovery inline policy from Step 5 to allow CloudAIPilot to install it automatically.

Human-in-the-Loop Safety

Once connected, CloudAIPilot reads your infrastructure and can propose optimisations. It will never provision a new EC2 instance, resize a volume, or remove a resource without generating an Approval Card for you to review and confirm first.

Revoking Access

To disconnect CloudAIPilot from your AWS account:

  • In CloudAIPilot: Cloud Accounts → [your account] → Remove
  • In AWS: Delete or disable the IAM Role — this immediately revokes all access regardless of the state in CloudAIPilot

Related Articles