AWS Integration

Connect your AWS account to enable the AI agent to query CloudWatch logs and metrics, inspect EC2 instances, review ECS/EKS workloads, and monitor ElastiCache clusters during investigations. This integration uses OIDC federation — no AWS credentials are stored in Autoheal.

How It Works

Autoheal uses OpenID Connect (OIDC) federation to securely access your AWS account:

1. You create an IAM OIDC Identity Provider that trusts Autoheal
2. You create an IAM Role with a trust policy for Autoheal
3. At runtime, Autoheal exchanges a short-lived OIDC token for temporary AWS credentials via STS
4. Temporary credentials expire automatically — no long-lived keys are stored

Capabilities

Once connected, the AI agent can:

Capability	Description
CloudWatch Logs	Search and retrieve log events across log groups
CloudWatch Metrics	Query metric data points and view alarm states
EC2 Instances	List instances, view details and status checks
ECS Services	Inspect clusters, services, tasks, and deployments
EKS Clusters	Review cluster configuration and node groups
ElastiCache	Inspect Redis/Memcached cluster infrastructure — topology, replication groups, events, and CloudWatch metrics. Infrastructure-level only; does not read or write cached data (keys, values).

Prerequisites

• An AWS account with IAM administrative access
• Permission to create IAM OIDC Identity Providers and IAM Roles
• Your 12-digit AWS Account ID
• Your Autoheal tenant slug (used as part of the OIDC audience value)

info

Your tenant slug is a short identifier for your organization in Autoheal (e.g., acme-corp). You can find it in Settings → Organization in Autoheal. The OIDC audience value used throughout this guide follows the pattern {tenant-slug}-oidc-service — for example, acme-corp-oidc-service.

Setup

You can set up the AWS resources using the AWS Console (UI) or the AWS CLI (copy-paste commands). Both methods produce the same result.

AWS CLI (Recommended)

Set up everything from your terminal in under 2 minutes. You need to set two variables — your AWS Account ID and your Autoheal tenant slug.

1

Set Your Account ID and Tenant Slug

Replace 123456789012 with your actual 12-digit AWS Account ID and your-tenant-slug with your Autoheal tenant slug:

export AWS_ACCOUNT_ID="123456789012"
export AUTOHEAL_TENANT_SLUG="your-tenant-slug"

info

You can find your Account ID in the AWS Console (top-right dropdown) or by running aws sts get-caller-identity --query Account --output text. Your tenant slug is available in Autoheal under Settings → Organization (e.g., acme-corp).

2

Create OIDC Identity Provider

This tells AWS to trust tokens issued by Autoheal:

aws iam create-open-id-connect-provider \
  --url "https://app.autoheal.ai" \
  --client-id-list "${AUTOHEAL_TENANT_SLUG}-oidc-service" \
  --thumbprint-list "0000000000000000000000000000000000000000"

info

The audience value is your tenant-specific OIDC identifier, following the pattern {tenant-slug}-oidc-service (e.g., acme-corp-oidc-service). The --thumbprint-list parameter is required by the API but AWS no longer uses it for validation — any valid 40-character hex string works.

3

Create IAM Policy

Create an IAM policy and attach it to the role. The example below is a good starting point — feel free to grant more or fewer permissions depending on what you'd like Autoheal to access:

aws iam create-policy \
  --policy-name AutohealReadOnlyPolicy \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "CloudWatchLogs",
        "Effect": "Allow",
        "Action": [
          "logs:DescribeLogGroups",
          "logs:DescribeLogStreams",
          "logs:FilterLogEvents",
          "logs:GetLogEvents",
          "logs:StartQuery",
          "logs:GetQueryResults"
        ],
        "Resource": "*"
      },
      {
        "Sid": "CloudWatchMetrics",
        "Effect": "Allow",
        "Action": [
          "cloudwatch:ListMetrics",
          "cloudwatch:GetMetricData",
          "cloudwatch:DescribeAlarms"
        ],
        "Resource": "*"
      },
      {
        "Sid": "EC2ReadOnly",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeInstances",
          "ec2:DescribeInstanceStatus",
          "ec2:DescribeSecurityGroups",
          "ec2:DescribeSubnets",
          "ec2:DescribeVpcs"
        ],
        "Resource": "*"
      },
      {
        "Sid": "ECSReadOnly",
        "Effect": "Allow",
        "Action": [
          "ecs:ListClusters",
          "ecs:DescribeClusters",
          "ecs:ListServices",
          "ecs:DescribeServices",
          "ecs:ListTasks",
          "ecs:DescribeTasks"
        ],
        "Resource": "*"
      },
      {
        "Sid": "EKSReadOnly",
        "Effect": "Allow",
        "Action": [
          "eks:ListClusters",
          "eks:DescribeCluster",
          "eks:ListNodegroups",
          "eks:DescribeNodegroup"
        ],
        "Resource": "*"
      },
      {
        "Sid": "ElastiCacheReadOnly",
        "Effect": "Allow",
        "Action": [
          "elasticache:DescribeCacheClusters",
          "elasticache:DescribeReplicationGroups",
          "elasticache:DescribeServerlessCaches",
          "elasticache:DescribeEvents"
        ],
        "Resource": "*"
      },
      {
        "Sid": "STSIdentity",
        "Effect": "Allow",
        "Action": [
          "sts:GetCallerIdentity"
        ],
        "Resource": "*"
      }
    ]
  }'

tip

You can also attach the AWS managed policy arn:aws:iam::aws:policy/ReadOnlyAccess if you prefer broad read-only access without creating a custom policy. You can further scope Resource to specific ARNs (e.g., particular log groups or clusters) if you want tighter control.

4

Create IAM Role with Trust Policy

Create the role that Autoheal will assume via OIDC federation:

aws iam create-role \
  --role-name AutohealReadOnlyRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Federated": "arn:aws:iam::'$AWS_ACCOUNT_ID':oidc-provider/app.autoheal.ai"
        },
        "Action": "sts:AssumeRoleWithWebIdentity",
        "Condition": {
          "StringEquals": {
            "app.autoheal.ai:aud": "'$AUTOHEAL_TENANT_SLUG'-oidc-service"
          }
        }
      }
    ]
  }'

5

Attach Policy to Role

aws iam attach-role-policy \
  --role-name AutohealReadOnlyRole \
  --policy-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:policy/AutohealReadOnlyPolicy"

6

Copy the Role ARN

aws iam get-role \
  --role-name AutohealReadOnlyRole \
  --query 'Role.Arn' --output text

Copy the output — you'll paste it into Autoheal in the next step.

7

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click Amazon Web Services
3. Enter a name (e.g., "Production AWS")
4. Fill in:
   • AWS Account ID: Your 12-digit account ID
   • IAM Role ARN: The role ARN from the previous step
   • AWS Region (optional): The default region for tool calls (e.g., us-east-1). Defaults to us-east-1 if left blank.
5. Click Test Connection to verify, then Save

AWS Console (UI)

1

Create IAM OIDC Identity Provider

This tells AWS to trust tokens issued by Autoheal.

1. Open the IAM Console → Identity providers → Add provider
2. Select OpenID Connect
3. Enter the following:
   • Provider URL: https://app.autoheal.ai
   • Audience: {your-tenant-slug}-oidc-service (e.g., acme-corp-oidc-service)
4. Click Get thumbprint, then Add provider

info

The audience value is your tenant-specific OIDC identifier. Replace {your-tenant-slug} with your Autoheal tenant slug, which you can find in Settings → Organization. This ensures only your Autoheal tenant can assume the role.

2

Create IAM Role

This role defines what Autoheal can do in your account.

1. Go to IAM → Roles → Create role
2. Select Web identity as the trusted entity type
3. Choose the identity provider you just created (app.autoheal.ai)
4. Select audience: {your-tenant-slug}-oidc-service (the value you entered when creating the provider)
5. Click Next and attach the permissions policy (see next step)
6. Name the role (e.g., AutohealReadOnlyRole) and create it

After creation, copy the Role ARN (e.g., arn:aws:iam::123456789012:role/AutohealReadOnlyRole).

warning

The trust policy is automatically created by the wizard. See the "Trust Policy Reference" section below to verify it.

3

Attach Permissions Policy

Attach an IAM policy to the role. You decide how much access to grant — the example below is a reasonable starting point for the services Autoheal works with.

Option A: AWS Managed Policy (Quickest)

Attach arn:aws:iam::aws:policy/ReadOnlyAccess for broad read-only access across all AWS services.

Option B: Custom Policy (Example)

Create a custom policy scoped to the services Autoheal uses. Feel free to add or remove permissions based on what you want Autoheal to access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:FilterLogEvents",
        "logs:GetLogEvents",
        "logs:StartQuery",
        "logs:GetQueryResults"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchMetrics",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:ListMetrics",
        "cloudwatch:GetMetricData",
        "cloudwatch:DescribeAlarms"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EC2ReadOnly",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSubnets",
        "ec2:DescribeVpcs"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ECSReadOnly",
      "Effect": "Allow",
      "Action": [
        "ecs:ListClusters",
        "ecs:DescribeClusters",
        "ecs:ListServices",
        "ecs:DescribeServices",
        "ecs:ListTasks",
        "ecs:DescribeTasks"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EKSReadOnly",
      "Effect": "Allow",
      "Action": [
        "eks:ListClusters",
        "eks:DescribeCluster",
        "eks:ListNodegroups",
        "eks:DescribeNodegroup"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ElastiCacheReadOnly",
      "Effect": "Allow",
      "Action": [
        "elasticache:DescribeCacheClusters",
        "elasticache:DescribeReplicationGroups",
        "elasticache:DescribeServerlessCaches",
        "elasticache:DescribeEvents"
      ],
      "Resource": "*"
    },
    {
      "Sid": "STSIdentity",
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

tip

You can also scope Resource to specific ARNs (e.g., particular log groups or clusters) if you want finer-grained control.

4

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click Amazon Web Services
3. Enter a name (e.g., "Production AWS")

5

Configure Connection

Enter the following:

• AWS Account ID: Your 12-digit account ID (e.g., 123456789012)
• IAM Role ARN: The role ARN from Step 2 (e.g., arn:aws:iam::123456789012:role/AutohealReadOnlyRole)
• AWS Region (optional): The default region for tool calls (e.g., us-east-1). Defaults to us-east-1 if left blank.

6

Test and Save

Click Test Connection to verify OIDC federation works, then Save.

The test calls sts:GetCallerIdentity to confirm Autoheal can assume the role.

Trust Policy Reference

The IAM Role's trust policy should look like this (created automatically by the IAM wizard):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/app.autoheal.ai"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "app.autoheal.ai:aud": "YOUR_TENANT_SLUG-oidc-service"
        }
      }
    }
  ]
}

Replace YOUR_ACCOUNT_ID with your 12-digit AWS account ID and YOUR_TENANT_SLUG with your Autoheal tenant slug (e.g., acme-corp-oidc-service).

Multi-Region Access

The AWS Region field sets the default region for tool calls (CloudWatch, EC2, ECS, EKS, ElastiCache queries). It is optional — if left blank, us-east-1 is used.

To monitor resources in multiple regions, create separate integrations for each region:

• "AWS US East" → us-east-1
• "AWS EU West" → eu-west-1

All integrations can use the same IAM Role — the role is not region-specific.

Example Queries

Once connected, you can ask the AI agent:

Show me error logs from the payment-service log group in the last hour

What CloudWatch alarms are currently in ALARM state?

List all EC2 instances tagged with Environment=production

Show me the ECS services in the main cluster and their deployment status

What EKS node groups are running and what's their scaling configuration?

List all ElastiCache clusters and their status

Describe the replication group cell-a-redis, including its failover and topology

What is the CPU utilization of my ElastiCache cluster over the last hour?

Network Requirements

This integration communicates entirely over public HTTPS endpoints. No VPC peering, firewall rules, or private connectivity is required. Ensure the following traffic is allowed:

Direction	From	To	Purpose
AWS → Autoheal	AWS STS	https://app.autoheal.ai/.well-known/openid-configuration and JWKS endpoint	AWS validates the OIDC token by fetching Autoheal's signing keys during AssumeRoleWithWebIdentity. Note: AWS STS makes these requests over HTTP/1.1 — any intermediary (load balancer, reverse proxy) in front of Autoheal must support HTTP/1.1 on these paths.
Autoheal → AWS	Autoheal platform	sts.amazonaws.com (or regional STS endpoints)	Exchanges OIDC token for temporary AWS credentials
Autoheal → AWS	Autoheal platform	Regional AWS service endpoints (e.g., logs.{region}.amazonaws.com, ec2.{region}.amazonaws.com)	Executes read-only API calls using temporary credentials

info

If your AWS account uses Service Control Policies (SCPs) or VPC endpoint policies, ensure they do not block sts:AssumeRoleWithWebIdentity or the read-only actions granted to the Autoheal role.

Security

• No stored credentials: Autoheal never stores AWS access keys. OIDC federation provides temporary credentials that expire automatically (typically within 1 hour).
• Least privilege: The custom IAM policy above grants only read-only access to the specific services Autoheal needs.
• Audit trail: All API calls made by Autoheal appear in AWS CloudTrail under the assumed role identity.
• Revocable: Remove or disable the IAM Role at any time to immediately revoke Autoheal access.

Troubleshooting

Test Connection fails with 'AccessDenied'

• Verify the IAM Role ARN is correct
• Check the trust policy has app.autoheal.ai as the federated principal
• Ensure the audience condition matches your tenant-specific value ({your-tenant-slug}-oidc-service)

'InvalidIdentityToken' error

• The OIDC token may have expired — retry the connection
• Verify the IAM OIDC Identity Provider URL is exactly https://app.autoheal.ai (no trailing slash)

Can query some services but not others

• Review the IAM policy attached to the role
• Ensure all required permissions are granted (see Custom Minimum Policy above)
• Check for Service Control Policies (SCPs) that might restrict access

No data returned for a region

• Verify you selected the correct region when creating the integration
• Check that resources exist in that region
• For CloudWatch Logs, ensure log groups are in the selected region

How to revoke Autoheal access

To immediately revoke access, delete the IAM Role and OIDC provider.

Via AWS Console:

1. Go to IAM → Roles → Select the Autoheal role → Delete
2. Go to IAM → Identity providers → Select the Autoheal provider → Delete

Via AWS CLI:

export AWS_ACCOUNT_ID="123456789012"  # Replace with your account ID

# Detach policy and delete role
aws iam detach-role-policy \
  --role-name AutohealReadOnlyRole \
  --policy-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:policy/AutohealReadOnlyPolicy"
aws iam delete-role --role-name AutohealReadOnlyRole

# Delete policy
aws iam delete-policy \
  --policy-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:policy/AutohealReadOnlyPolicy"

# Delete OIDC provider
aws iam delete-open-id-connect-provider \
  --open-id-connect-provider-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/app.autoheal.ai"

Next Steps

Once your AWS integration is configured, connect the AWS-powered integrations you need. Each one links to this AWS integration for authentication and has its own setup guide covering the additional permissions required:

• PostgreSQL (RDS IAM Auth) — Query Amazon RDS or Aurora PostgreSQL databases using IAM authentication