AWS Operator Setup

The AWS APIs Operator runs in your VPC and calls services such as Redshift, Athena and Power BI with IAM roles through EKS Pod Identity. No AWS credentials leave your cluster.

How the operator works

The Agent Controller’s skill relay (agent-controller) assumes an IAM role through Pod Identity and hands the call to the AWS Operator, which calls the AWS API in your VPC. The Agent Controller runs as the agent-controller ServiceAccount and everything else as default: associate the role with both, not with one pod. The role needs three trust principals:

Principal	Purpose
`pods.eks.amazonaws.com`	EKS Pod Identity. Lets xpander pods assume the role.
`arn:aws:iam::<ACCOUNT_ID>:root`	Cross-account assume with External ID (`organizationId`) for xpander
The role’s own ARN	Self-assume. The Agent Controller re-assumes its own role internally to get service-specific credentials.

The self-assume statement must not have an ExternalId condition. The Agent Controller calls sts:AssumeRole on its own role without passing an external ID. If this statement has a condition, you’ll get AccessDenied errors.

Air-gapped installs

The air-gapped chart (xpander-airgap) ships no AWS Operator pod, and the operator leg stays off unless agent-controller.awsOperator.url is set. Instead, AWS skill calls (Redshift, S3, Athena, EKS) run from the functions service: the agent-controller assumes the skill connection’s role and passes it temporary credentials. Redshift Data API calls carry a database user such as IAMR:<role-name>. The steps below still apply. A missing permission fails with not authorized to perform: <action>, for example s3:ListAllMyBuckets or athena:ListWorkGroups. Grant these per skill (taken from the calls each skill makes, not yet verified on a live air-gapped install):

Skill	Actions the role needs
Redshift	The `redshift-data:*` statement and catalog actions in the Redshift policy below. For a provisioned cluster, add `redshift:GetClusterCredentials`. For Redshift Serverless (a workgroup), add `redshift-serverless:GetCredentials`
S3	`s3:ListAllMyBuckets`, `s3:ListBucket`, `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, `s3:GetObjectAcl`, `s3:GetObjectTagging`, `s3:PutObjectTagging`. Bucket inspection actions also need `s3:GetBucketAcl`, `s3:GetBucketPolicy`, `s3:GetBucketPublicAccessBlock`, `s3:GetEncryptionConfiguration`, `s3:GetBucketVersioning`, `s3:GetBucketCORS`, `s3:GetBucketTagging` and `s3:GetLifecycleConfiguration`. Bucket create, delete and configure actions need the matching `s3:CreateBucket`, `s3:DeleteBucket`, `s3:Put*` and `s3:ListBucketVersions` actions
Athena	`athena:ListWorkGroups`, `athena:GetWorkGroup`, `athena:ListDatabases`, `athena:ListTableMetadata`, `athena:GetTableMetadata`, `athena:StartQueryExecution`, `athena:GetQueryExecution`, `athena:GetQueryResults`, `athena:ListQueryExecutions`, `athena:StopQueryExecution`, the Glue read actions, and S3 access to the query results bucket (the Athena policy below)
EKS	`eks:ListClusters`, `eks:DescribeCluster`, `eks:ListInsights`, `eks:DescribeInsight`, and `logs:FilterLogEvents` on the cluster’s log group. The skill also calls the Kubernetes API with an IAM token. Map the role on each cluster with an EKS access entry or the `aws-auth` ConfigMap. Give it read access to pods, `pods/log`, nodes, services, events and deployments, for example with `AmazonEKSViewPolicy`

1. Create the IAM role

cat <<TRUST > /tmp/aws-operator-trust.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PodIdentity",
      "Effect": "Allow",
      "Principal": { "Service": "pods.eks.amazonaws.com" },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    },
    {
      "Sid": "CrossAccountWithExternalId",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<ACCOUNT_ID>:root"
      },
      "Action": ["sts:AssumeRole", "sts:TagSession"],
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<ORGANIZATION_ID>"
        }
      }
    },
    {
      "Sid": "SelfAssume",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<ACCOUNT_ID>:role/xpander-aws-access"
      },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }
  ]
}
TRUST

aws iam create-role \
  --role-name xpander-aws-access \
  --assume-role-policy-document file:///tmp/aws-operator-trust.json \
  --profile <PROFILE>

Add the self-assume permission policy:

aws iam put-role-policy \
  --role-name xpander-aws-access \
  --policy-name SelfAssumeAndTagSession \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["sts:AssumeRole", "sts:TagSession"],
      "Resource": "arn:aws:iam::<ACCOUNT_ID>:role/xpander-aws-access"
    }]
  }' \
  --profile <PROFILE>

2. Attach service permissions

Grant only what your skills need.

Redshift

aws iam put-role-policy \
  --role-name xpander-aws-access \
  --policy-name RedshiftAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "redshift:GetClusterCredentials",
          "redshift:GetClusterCredentialsWithIAM",
          "redshift:DescribeClusters"
        ],
        "Resource": [
          "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:cluster:*",
          "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:dbname:*/*",
          "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:dbuser:*/*"
        ]
      },
      {
        "Effect": "Allow",
        "Action": [
          "redshift-data:ExecuteStatement",
          "redshift-data:GetStatementResult",
          "redshift-data:DescribeStatement",
          "redshift-data:ListStatements",
          "redshift-data:CancelStatement",
          "redshift-data:BatchExecuteStatement",
          "redshift-data:ListDatabases",
          "redshift-data:ListSchemas",
          "redshift-data:ListTables",
          "redshift-data:DescribeTable"
        ],
        "Resource": "*"
      }
    ]
  }' \
  --profile <PROFILE>

Full walkthrough: Amazon Redshift (Self-Hosted).

Athena

aws iam put-role-policy \
  --role-name xpander-aws-access \
  --policy-name AthenaAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "athena:StartQueryExecution",
          "athena:GetQueryExecution",
          "athena:GetQueryResults",
          "athena:ListWorkGroups"
        ],
        "Resource": "*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "s3:GetObject",
          "s3:ListBucket",
          "s3:PutObject"
        ],
        "Resource": [
          "arn:aws:s3:::<RESULTS_BUCKET>",
          "arn:aws:s3:::<RESULTS_BUCKET>/*"
        ]
      },
      {
        "Effect": "Allow",
        "Action": [
          "glue:GetTable",
          "glue:GetTables",
          "glue:GetDatabase",
          "glue:GetDatabases"
        ],
        "Resource": "*"
      }
    ]
  }' \
  --profile <PROFILE>

3. Associate the role with Pod Identity

# one association per ServiceAccount the chart runs pods as: agent-controller and default
for sa in agent-controller default; do
  aws eks create-pod-identity-association \
    --cluster-name <CLUSTER_NAME> \
    --namespace xpander \
    --service-account "$sa" \
    --role-arn arn:aws:iam::<ACCOUNT_ID>:role/xpander-aws-access \
    --region <REGION> --profile <PROFILE>
done

4. Network access

For a service inside your VPC, such as a private Redshift cluster, allow the EKS cluster security group:

# Get the EKS cluster security group
EKS_SG=$(aws eks describe-cluster --name <CLUSTER_NAME> \
  --region <REGION> --profile <PROFILE> \
  --query 'cluster.resourcesVpcConfig.clusterSecurityGroupId' --output text)

# Allow from EKS to the service (e.g., Redshift port 5439)
aws ec2 authorize-security-group-ingress \
  --group-id <SERVICE_SG_ID> \
  --protocol tcp --port <SERVICE_PORT> \
  --source-group $EKS_SG \
  --region <REGION> --profile <PROFILE>

Services outside your VPC, such as S3 and Athena, need no change: the NAT Gateway handles outbound access.

5. Configure in xpander

Each AWS skill connection in xpander Chat takes:

Field	Value
IAM Role ARN	The role created above
Region	Your AWS region
Auth Method	IAM
Service-specific parameters	For example, the cluster ID, database name or bucket name

Supported AWS skills

Any AWS service IAM can reach works. Common ones:

Redshift

Query private Redshift clusters

Athena

Run Athena queries

Power BI

Connect to Power BI datasets

Credential Management with AWS Secrets Manager

A skill can read its keys from AWS Secrets Manager at runtime, so they never enter xpander’s database.

How Secrets Manager works

Turn it on

Enable “Use AWS Secrets Manager” in the skill’s connection settings in xpander.

Point to the secret

Provide the secret ARN, for example arn:aws:secretsmanager:us-east-1:123456789012:secret:my-api-key-AbCdEf.

xpander reads it at runtime

The pod reads it with its IAM role. Nothing is persisted.

Required permissions

Add to the IAM role:

aws iam put-role-policy \
  --role-name xpander-aws-access \
  --policy-name SecretsManagerAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": [
        "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:xpander/*"
      ]
    }]
  }' \
  --profile <PROFILE>

Use specific secret ARNs instead of wildcards. Organize secrets by environment (xpander/prod/, xpander/staging/) and enable CloudTrail for audit logging.

Troubleshooting

sts:TagSession AccessDenied

Add sts:TagSession to both the trust policy AND as a permission policy on the role.

sts:AssumeRole AccessDenied (self-assume)

The Agent Controller re-assumes its own role internally. The trust policy needs a SelfAssume statement for the role’s own ARN without an ExternalId condition. Also add sts:AssumeRole as a permission policy.

Service connection timeout

Check that the service’s security group allows the relevant port from the EKS cluster security group. A VPC-internal service must be in the same VPC, or reachable through VPC peering or a transit gateway.

Govern

LLM Gateway

Deploy

Integrations

Licensing and identity

Security and compliance

How the operator works

Air-gapped installs

1. Create the IAM role

2. Attach service permissions

3. Associate the role with Pod Identity

4. Network access

5. Configure in xpander

Supported AWS skills

Redshift

Athena

Power BI

Credential Management with AWS Secrets Manager

How Secrets Manager works

Required permissions

Troubleshooting

Next steps

Connect a private Redshift cluster

Browse the skills catalog

​How the operator works

​Air-gapped installs

​1. Create the IAM role

​2. Attach service permissions

​3. Associate the role with Pod Identity

​4. Network access

​5. Configure in xpander

​Supported AWS skills

Redshift

Athena

Power BI

​Credential Management with AWS Secrets Manager

​How Secrets Manager works

​Required permissions

​Troubleshooting

​Next steps

Connect a private Redshift cluster

Browse the skills catalog

How the operator works

Air-gapped installs

1. Create the IAM role

2. Attach service permissions

3. Associate the role with Pod Identity

4. Network access

5. Configure in xpander

Supported AWS skills

Credential Management with AWS Secrets Manager

How Secrets Manager works

Required permissions

Troubleshooting

Next steps