AWS Integration

Connect your AWS account to enable the AI agent to query CloudWatch logs and metrics, inspect EC2 instances, and review ECS/EKS workloads 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

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://auth.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 a custom policy with the minimum permissions Autoheal needs:

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": "STSIdentity",
        "Effect": "Allow",
        "Action": [
          "sts:GetCallerIdentity"
        ],
        "Resource": "*"
      }
    ]
  }'

tip

You can restrict Resource to specific ARNs (e.g., specific log groups or ECS clusters) for tighter access control. Alternatively, attach the AWS managed policy arn:aws:iam::aws:policy/ReadOnlyAccess for broad read-only access instead of creating a custom policy.

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/auth.autoheal.ai"
        },
        "Action": "sts:AssumeRoleWithWebIdentity",
        "Condition": {
          "StringEquals": {
            "auth.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: The primary region for your resources (e.g., us-east-1)
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://auth.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 (auth.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 a policy that grants read-only access to the AWS services Autoheal needs. You can use the managed policy ReadOnlyAccess or create a custom policy with minimum permissions.

Option A: AWS Managed Policy (Quick Start)

Attach arn:aws:iam::aws:policy/ReadOnlyAccess for broad read-only access.

Option B: Custom Minimum Policy (Recommended)

Create a custom policy with only the permissions Autoheal needs:

{
  "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": "STSIdentity",
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

tip

You can restrict Resource to specific ARNs (e.g., specific log groups or ECS clusters) for tighter access 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: The primary region for your resources (e.g., us-east-1)

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/auth.autoheal.ai"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "auth.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 integration connects to one AWS region at a time. 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?

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 auth.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://auth.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/auth.autoheal.ai"