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

# AWS

## Getting Started

Connect AWS to Blocks to enable agents to interact with your cloud infrastructure. Agents can inspect resources, query services, assist with deployments, and help troubleshoot issues across your AWS environment.

<Note>
  Blocks operates with the full privileges of the connected IAM role or user. We strongly recommend granting only read-only access (e.g. the `ReadOnlyAccess` managed policy) to operate safely.
</Note>

## What Blocks Can Do

Blocks can help you with a variety of AWS tasks:

* **Inspect Resources**: Query EC2 instances, S3 buckets, RDS databases, Lambda functions, and more
* **Monitor Logs**: Retrieve and analyze CloudWatch logs to diagnose issues
* **Deployment Assistance**: Help plan and execute deployments via ECS, Lambda, or CloudFormation
* **Cost Analysis**: Review resource usage and suggest cost optimizations
* **Security Review**: Audit IAM roles, security groups, and access policies
* **Infrastructure Troubleshooting**: Diagnose connectivity, configuration, and performance issues

## Setting Up AWS Integration

AWS accounts are connected to a workspace as **cloud connections**. Go to **Settings > Workspace Integrations > AWS** and click **Add connection**. A workspace can hold up to 5 connections, and each one authenticates via **OIDC (recommended)** or **AWS credentials**.

### Option 1: OIDC (Recommended)

With OIDC, Blocks assumes an IAM role in your account via OpenID Connect — there are no long-lived secrets to store or rotate.

<Steps>
  <Step title="Start an OIDC Connection">
    In **Settings > Workspace Integrations > AWS**, click **Add connection**, give the connection a name, and select **OIDC (Recommended)**. Blocks will display the **Provider URL (issuer)** and **Audience** you need for the next steps.
  </Step>

  <Step title="Add Blocks as an Identity Provider">
    In the [AWS IAM Console](https://console.aws.amazon.com/iam/), go to **IAM > Identity providers > Add provider**. Select **OpenID Connect** and enter the **Provider URL** and **Audience** shown in Blocks.
  </Step>

  <Step title="Create a Role for Blocks">
    Go to **IAM > Roles > Create role** and select the trusted entity type **Web identity**. Choose the newly created Blocks provider and the audience above, then attach the permissions you want Blocks to have.

    <Warning>
      We strongly recommend attaching **minimal read-only permissions** (e.g. the `ReadOnlyAccess` managed policy).
    </Warning>
  </Step>

  <Step title="Connect the Role">
    Back in Blocks, paste the **role ARN** and set the **Region**. Blocks will then show a trust policy for the role — open the role's **Trust relationships > Edit trust policy** in AWS and replace it with the provided policy. Click **Connect & verify**.

    <Note>
      If verification fails, make sure the role's trust policy matches the snippet shown in Blocks, even if the role was previously created for another connection. Trust policy changes can take 1-2 minutes to propagate before re-verifying.
    </Note>
  </Step>
</Steps>

### Option 2: AWS Credentials

If you can't use OIDC, you can connect with a long-lived access key instead.

<Steps>
  <Step title="Create a Dedicated IAM User">
    In the [AWS IAM Console](https://console.aws.amazon.com/iam/), create a new IAM user dedicated to Blocks.

    <Warning>
      We strongly recommend creating this user with **minimal read-only permissions** (e.g. the `ReadOnlyAccess` managed policy). Never use root account credentials or credentials with unrestricted access.
    </Warning>
  </Step>

  <Step title="Generate Access Credentials">
    Create an access key for the IAM user and copy the **Access Key ID** and **Secret Access Key**.
  </Step>

  <Step title="Enter Credentials in Blocks">
    In **Settings > Workspace Integrations > AWS**, click **Add connection**, give the connection a name, select **AWS Credentials**, and enter:

    * **Access Key ID**
    * **Secret Access Key**
    * **Region**
  </Step>
</Steps>

### Managing Connections

From **Settings > Workspace Integrations > AWS** you can set a connection as the workspace **default**, **re-verify** or **edit** an OIDC connection, **rotate keys** on a credentials connection, or **delete** a connection.

### Using AWS in Requests

Once connected, you can reference your AWS environment in any request:

```
@blocks list all running EC2 instances in us-east-1
```

```
@blocks check CloudWatch logs for the payment-service Lambda in the last hour
```

```
@blocks review the security groups attached to our production RDS instance
```

```
@blocks what's causing high memory usage on the web-server ECS task?
```

<Note>
  **Session Context**: Responding in the same thread continues the session, preserving context from previous queries. Starting a new comment or issue creates a fresh session.
</Note>

## Security Best Practices

* **Prefer OIDC**: Use an OIDC connection so Blocks assumes a role on demand and no long-lived secrets are stored
* **Follow Least Privilege**: Grant only the permissions Blocks needs for your specific use cases
* **Rotate Credentials**: If you use access keys, rotate them regularly via **Rotate keys** in Settings > Workspace Integrations > AWS
* **Restrict by Region**: Scope IAM policies to specific regions where possible
* **Monitor Activity**: Enable CloudTrail to audit all API calls made by Blocks in your account
* **Use Separate Accounts**: Consider using a dedicated AWS account for staging vs. production

## Common Use Cases

### Infrastructure Debugging

Ask Blocks to investigate issues in your environment:

```
@blocks the checkout service is returning 502 errors, check the ECS task logs and load balancer health
```

### Deployment Review

Get help reviewing before applying changes:

```
@blocks review this CloudFormation template for any security or cost concerns before we deploy
```

### Cost Optimization

Identify opportunities to reduce spend:

```
@blocks find underutilized EC2 instances and RDS databases in our staging environment
```

## Best Practices

* **Be Specific**: Reference service names, regions, and resource IDs where possible
* **Provide Context**: Describe the expected behavior alongside what you're observing
* **Check Progress**: Use the dashboard link to monitor Blocks' work on your request
* **Follow Up**: Continue the conversation by mentioning `@blocks` with additional questions or clarifications

## Next Steps

New to Blocks? Check out the [Getting Started guide](/using-blocks/getting-started) to learn the basics.

Learn more about:

* [Plan Mode](/using-blocks/features/plan-mode) for collaborative planning before making infrastructure changes
* [Skills](/using-blocks/features/skills) for reusable AWS queries and workflows


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.