> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS

> Connect AWS to CloudThinker for cost analysis, security auditing, and infrastructure management via IAM role or access keys

Connect your AWS accounts to enable CloudThinker agents to analyze costs, audit security, optimize resources, and manage infrastructure at scale.

AWS authenticates with an **IAM role (AssumeRole)** or **IAM user access keys**; role-based authentication is strongly recommended because it uses short-lived credentials via AWS STS and avoids storing long-term secrets.

***

## Prerequisites

* An AWS account with IAM administrator access.
* Permission to create IAM roles or IAM users in the target account.
* Access to [AWS CloudShell](https://console.aws.amazon.com/) or the [IAM console](https://console.aws.amazon.com/iam/) for setup.

<Info>
  Role-based authentication (AssumeRole) is strongly preferred. Use access keys only when AssumeRole is not feasible in your environment.
</Info>

***

## Setup

<Tabs>
  <Tab title="Role-Based (Recommended)">
    ### IAM role with AssumeRole

    This method creates an IAM role that CloudThinker assumes to access your resources. Benefits:

    * No long-term credentials shared or stored
    * Uses AWS STS for temporary, auto-rotated credentials
    * External ID protects against confused deputy attacks
    * Easy to audit and revoke access

    #### Quick setup via CloudShell

    <Steps>
      <Step title="Open AWS CloudShell">
        Log in to [AWS Console](https://console.aws.amazon.com/) and open **CloudShell** from the top nav.
      </Step>

      <Step title="Run setup script">
        In CloudThinker's connection dialog, click **Copy Script** and paste into CloudShell. The script:

        * Validates `CloudThinkerAccessRole` doesn't exist
        * Creates the IAM role with read-only permissions
        * Attaches the trust policy with your External ID
      </Step>

      <Step title="Copy Role ARN">
        Copy the Role ARN from the output:

        ```
        arn:aws:iam::123456789012:role/CloudThinkerAccessRole
        ```
      </Step>

      <Step title="Complete the connection">
        Paste the Role ARN into CloudThinker, select your region, and click **Connect**. CloudThinker verifies the role and shows a **Connected** status.
      </Step>
    </Steps>

    #### Expected output

    ```
    Starting CloudThinker IAM Role setup...
    ✅ Role does not exist, proceeding...
    ✅ Role created successfully
    ✅ Policy attached successfully
    ==========================================
    ✅ Setup Complete!
    ==========================================
    Copy this Role ARN:
    arn:aws:iam::123456789012:role/CloudThinkerAccessRole
    ```

    #### Manual role creation

    If you prefer manual setup:

    **Trust policy:**

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::CLOUDTHINKER_ACCOUNT_ID:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "YOUR_EXTERNAL_ID"
            }
          }
        }
      ]
    }
    ```

    **Permission policy:**

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "ec2:Describe*",
            "rds:Describe*",
            "s3:GetBucket*",
            "s3:List*",
            "cloudwatch:GetMetric*",
            "cloudwatch:List*",
            "ce:GetCost*",
            "ce:GetReservation*",
            "iam:GetRole",
            "iam:ListRoles"
          ],
          "Resource": "*"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Access Keys (Alternative)">
    ### IAM user with access keys

    Use this method only when AssumeRole is not feasible in your environment.

    <Warning>
      AWS recommends IAM roles over long-term access keys. Rotate keys regularly if using this method.
    </Warning>

    <Steps>
      <Step title="Create an IAM user">
        Go to [IAM Console](https://console.aws.amazon.com/iam/) → **Users → Create user** and name it `cloudthinker-readonly`.
      </Step>

      <Step title="Attach policies">
        Choose **Attach policies directly** and add:

        * `ReadOnlyAccess` (comprehensive), or
        * Specific policies like `AmazonEC2ReadOnlyAccess`, `AmazonS3ReadOnlyAccess`
      </Step>

      <Step title="Create an access key">
        Select the user → **Security credentials → Create access key**. Choose **Third-party service** as the use case.
      </Step>

      <Step title="Save credentials">
        Copy and securely store the Access Key ID and Secret Access Key. Enter them in **Connections → AWS** and click **Connect**. CloudThinker shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Multi-account setup

For organizations with multiple AWS accounts:

<Steps>
  <Step title="Create the role in each account">
    Deploy the IAM role using CloudFormation StackSets across all target accounts.
  </Step>

  <Step title="Use AWS Organizations">
    Connect the management account for organization-wide visibility.
  </Step>

  <Step title="Add each account">
    Add account connections individually in CloudThinker.
  </Step>
</Steps>

***

## Connection details

| Field                 | Description                                                  | Example                                                 |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| **Role ARN**          | ARN of the IAM role CloudThinker assumes (role-based method) | `arn:aws:iam::123456789012:role/CloudThinkerAccessRole` |
| **External ID**       | Secret ID in the trust policy, provided by CloudThinker      | —                                                       |
| **Region**            | Primary AWS region for this connection                       | `us-east-1`                                             |
| **Access Key ID**     | IAM user key ID (access-keys method only)                    | —                                                       |
| **Secret Access Key** | IAM user secret key (access-keys method only)                | —                                                       |

***

## Required permissions

### Minimum (read-only analysis)

```
ec2:Describe*
rds:Describe*
s3:GetBucket*, s3:List*
cloudwatch:GetMetric*, cloudwatch:List*
ce:GetCost*, ce:GetReservation*
iam:GetRole, iam:ListRoles
```

### Recommended (full analysis)

```
# All minimum permissions, plus:
elasticloadbalancing:Describe*
autoscaling:Describe*
lambda:List*, lambda:GetFunction*
ecs:Describe*, ecs:List*
eks:Describe*, eks:List*
securityhub:Get*, securityhub:List*
guardduty:Get*, guardduty:List*
config:Describe*, config:Get*
cloudtrail:Describe*, cloudtrail:Get*
```

<Tip>
  Start with minimum permissions and expand as needed. Enable Cost Explorer in the AWS Console before connecting — it can take up to 24 hours to activate on new accounts.
</Tip>

***

## Agent capabilities

Once connected, agents can analyze and optimize your AWS resources.

| Agent                              | AWS capabilities                                                                          |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| **[Alex](/guide/agents/alex)**     | Cost analysis, EC2 right-sizing, Reserved Instance recommendations, resource optimization |
| **[Oliver](/guide/agents/oliver)** | Security Hub findings, IAM audits, compliance checks, vulnerability assessment            |
| **[Tony](/guide/agents/tony)**     | RDS performance analysis, Aurora optimization, DynamoDB tuning                            |
| **[Kai](/guide/agents/kai)**       | EKS cluster management, Fargate optimization, container analysis                          |

### Verify the connection

```text theme={null}
@alex run an AWS account check and list the connected account ID and active regions
```

### Example prompts

```text theme={null}
@alex analyze EC2 costs over the last 30 days and #recommend right-sizing opportunities
@oliver audit IAM roles and flag any with excessive permissions or missing MFA requirements
@kai check EKS cluster health across all connected regions and #report any failing pods
```

***

## Troubleshooting

<Accordion title="Access Denied errors">
  Verify the IAM role has the required permissions. Check that the trust policy includes CloudThinker's account ID, confirm the External ID matches exactly, and ensure the role ARN is correct.
</Accordion>

<Accordion title="Missing cost data">
  Enable Cost Explorer in the AWS Console (takes up to 24 hours to activate). Verify `ce:GetCost*` permissions are granted and check that billing preferences allow programmatic access.
</Accordion>

<Accordion title="Missing metrics">
  Verify CloudWatch metrics are being collected. Check that the region selection includes all relevant regions and confirm services are running and generating data.
</Accordion>

<Accordion title="Connection timeout">
  Check network connectivity to AWS APIs. Verify no VPC endpoints are blocking access and try connecting from a different region.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Use IAM roles** — prefer AssumeRole over long-term access keys; IAM roles use short-lived STS credentials that auto-rotate and require no secret storage.
- **Enable CloudTrail** — audit all API calls made through the CloudThinker connection to maintain a complete activity log.

***

## Related

<CardGroup cols={2}>
  <Card title="Alex Agent" icon="cloud" href="/guide/agents/alex">
    AWS-focused cloud optimization agent
  </Card>

  <Card title="Bring Your Own Key (BYOK)" icon="key" href="/guide/byok">
    Use your own AWS Bedrock credentials for unlimited LLM usage
  </Card>
</CardGroup>