Docs / Clouds

AWS

Connect an AWS account so Pangea agents can work in it with short-lived, least-privilege credentials.

Pangea never stores long-lived AWS keys. You let Pangea assume an IAM role in your account through OIDC web-identity federation, pinned to your team. Each agent gets temporary credentials that expire after about an hour. The agent can then inspect and operate your AWS resources: EKS, EC2, ECS, Lambda, S3, CloudWatch, IAM and more.

Connect

In your AWS account you create:

1. An OpenID Connect identity provider that trusts Pangea.
2. An IAM role whose trust policy lets only your Pangea team assume it.
3. A permissions policy on that role. Start read-only.

Then you paste the role ARN into Pangea. There are two ways to do this.

Option A: guided setup with the agent

If the AWS CLI is installed and signed in on your Mac, open Connectors → Connect → AWS and choose the guided path. Pangea opens an agent that runs the aws CLI on your computer. It creates the OIDC provider, the role and its policies, then binds the role for you. Review the proposed access before you authorize it.

Option B: manual setup in the AWS console

The dialog in Connectors → Connect → AWS walks you through these steps and shows the values for your team.

1. Create the OIDC identity provider

In the IAM console, go to Identity providers → Add provider and choose OpenID Connect:

Click Add provider. If this AWS account already has the api.pangea.build provider, skip this step.

2. Create the IAM role

Go to IAM → Create role and pick Web identity as the trusted entity type. Choose the api.pangea.build provider and the sts.amazonaws.com audience. Then click Add condition:

The finished trust policy looks like this. Replace <your-account-id> with your 12-digit AWS account ID and <team-subject> with the value from the dialog:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<your-account-id>:oidc-provider/api.pangea.build"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "api.pangea.build:aud": "sts.amazonaws.com",
          "api.pangea.build:sub": "<team-subject>"
        }
      }
    }
  ]
}

3. Attach a permissions policy

Start least-privilege and widen only as needed. A read-only baseline:

• AmazonEC2ReadOnlyAccess
• AmazonS3ReadOnlyAccess
• other …ReadOnlyAccess policies for the services you use

AdministratorAccess is simpler for a fresh or dedicated account, but it lets the agent change anything. Broader roles permit broader changes, even in Full Access. For a later IAM denial, see Cloud permission errors.

4. Name and create the role

Give the role any name, for example PangeaRole. Check that the trust policy shows both the aud and sub conditions, then click Create role.

5. Paste the role ARN into Pangea

Open the new role and copy its ARN from the Summary card. It looks like arn:aws:iam::123456789012:role/PangeaRole. Paste it into the dialog. Pangea reads your account ID from the ARN.

Verification

When you submit the role ARN, Pangea assumes the role before it saves the connection. If the trust policy is wrong, you get a role_not_assumable error right away. IAM changes take a few seconds to propagate, so Pangea retries briefly.

In the Pangea app

Once the account is connected, Pangea discovers what is in it:

• Kubernetes clusters: your EKS clusters, with workloads, networking, config, storage and RBAC. Open a pod terminal, stream logs and act on resources in bulk, with no kubeconfig to manage.
• Compute and access: EC2 and Lightsail instances with status and metrics, Lambda functions you can inspect and invoke, an SSH terminal to any VM, and port forwarding into private networks.
• Cloud resources: S3 buckets and objects, VPCs, firewall rules, network ACLs and CloudFormation stacks.

What the agent can do for you

The agent uses the same access to investigate and operate for you. Ask it things like:

• "Why is the checkout deployment crash-looping?" It reads events, logs and config across the EKS cluster and finds the cause.
• "What's exposing api-prod to the internet?" It traces ingress, services, security groups and DNS together.
• "Roll the staging ASG to the new AMI." It proposes a plan with steps, risk and cost for you to approve, then runs it.

If a cloud operation returns an IAM denial, ask an authorized administrator for the narrowest change. See Cloud permission errors.

Permissions and authorization

Two boundaries govern this connector:

• Hard boundary: who can use it. Only team Administrators can bind or remove the account. They can restrict it to specific members with a member allow-list. Each agent only holds credentials for accounts you selected, and the allow-list is checked again on every credential request.
• Soft boundary: what the agent may do with it. The role limits reads and writes. Significant cloud work uses plans. At the command level the permission mode applies: in Auto Mode, risky commands pause for your approval; in Full Access, they run without asking.

The IAM role is the outer limit. The agent can never exceed the permissions policy you attached.

How credentials work

Good to know

You can connect multiple AWS accounts, for example staging and production, and give each its own allow-list. A common pattern: production restricted to a small group with a read-only role, staging open to the whole team.