IAM Best Practices

Split AWS skill access into a base role and one least-privilege role per skill.

This page covers skill access to AWS (Redshift, Athena, S3, EKS), not model access. xpander calls Amazon Bedrock with the pods’ own credentials, so bedrock:InvokeModel* and bedrock:Converse* go on the role bound to the pods, not on a skill role. See Amazon Bedrock without a key and, for Hybrid, Amazon Bedrock: keyless IAM or API key.

Architecture overview

┌─────────────────────────────────────────────────────┐
│  EKS Pod (xpander service account)                  │
│                                                     │
│  Pod Identity ──► Base Role (no permissions)        │
│                       │                             │
│                       ├──► Redshift Skill Role      │
│                       ├──► EKS Skill Role           │
│                       ├──► S3 Skill Role            │
│                       └──► [Any Future Skill]       │
└─────────────────────────────────────────────────────┘

Role	Purpose	Permissions
Base Role	Attached to pods through EKS Pod Identity. It has no direct permissions and only assumes skill-specific roles.	sts:AssumeRole + sts:TagSession on each skill role
Skill Roles	One per data source or service. Each holds only the permissions that skill needs.	Service-specific (for example redshift-data:*, eks:*), plus self-assume
Cross-Account Trust	Each skill role can optionally trust xpander for cloud-managed operations.	Trust with ExternalId condition

Why three tiers

Reason	What it gives you
Least privilege	Each skill reaches only its own service
Auditability	CloudTrail shows which skill role touched which resource
Independent lifecycle	Add or revoke one skill without touching the others
Role chaining	The skill relay (agent-controller) assumes the right skill role per request, with standard AWS role chaining

Using one role for all skills, as in AWS Operator Setup? This page splits it per skill.

---

Step 1: Base role

The only role on the pods. No service permissions, only assume.

aws iam create-role \
  --role-name xpander-base-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "pods.eks.amazonaws.com" },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }]
  }'

Add an inline policy AssumeConnectorRoles to xpander-base-role, and extend Resource as you add skills:

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

Associate it with the xpander service accounts:

# 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-base-role \
    --region <REGION>
done

---

Step 2: Skill roles

Each skill role needs a trust policy with four statements:

Statement	Purpose	ExternalId Required?
PodIdentity	Direct pod access (fallback)	No
CrossAccountWithExternalId	xpander cloud operations	Yes
SelfAssume	Skill relay internal re-assume for credential refresh	No
AllowFromBaseRole	Role chaining from the Pod Identity base role	No

Trust Policy Template

{
  "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/<THIS_ROLE_NAME>"
      },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    },
    {
      "Sid": "AllowFromBaseRole",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<ACCOUNT_ID>:role/xpander-base-role"
      },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }
  ]
}

SelfAssume and AllowFromBaseRole must not have an ExternalId condition. The skill relay passes none, so the skill would fail with AccessDenied.

Permission policies per skill

Self-Assume + Session Tagging (required for all skill roles)

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

Redshift Skill

aws iam put-role-policy \
  --role-name xpander-redshift-access \
  --policy-name RedshiftCredentials \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "redshift:GetClusterCredentials",
        "redshift:GetClusterCredentialsWithIAM",
        "redshift:DescribeClusters"
      ],
      "Resource": [
        "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:cluster:<CLUSTER_ID>",
        "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:dbname:<CLUSTER_ID>/<DB_NAME>",
        "arn:aws:redshift:<REGION>:<ACCOUNT_ID>:dbuser:<CLUSTER_ID>/*"
      ]
    }]
  }'

aws iam put-role-policy \
  --role-name xpander-redshift-access \
  --policy-name RedshiftDataAPI \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "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": "*"
    }]
  }'

EKS Skill

aws iam put-role-policy \
  --role-name xpander-eks-connector \
  --policy-name EKSAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "eks:DescribeCluster",
          "eks:ListClusters",
          "eks:ListNodegroups",
          "eks:DescribeNodegroup",
          "eks:ListInsights",
          "eks:DescribeInsight",
          "eks:AccessKubernetesApi"
        ],
        "Resource": "*"
      },
      {
        "Effect": "Allow",
        "Action": [
          "logs:GetLogEvents",
          "logs:FilterLogEvents",
          "logs:DescribeLogGroups",
          "logs:DescribeLogStreams"
        ],
        "Resource": "*"
      }
    ]
  }'

The EKS skill also needs Kubernetes RBAC:

aws eks create-access-entry \
  --cluster-name <CLUSTER_NAME> \
  --principal-arn arn:aws:iam::<ACCOUNT_ID>:role/xpander-eks-connector \
  --type STANDARD \
  --region <REGION>

aws eks associate-access-policy \
  --cluster-name <CLUSTER_NAME> \
  --principal-arn arn:aws:iam::<ACCOUNT_ID>:role/xpander-eks-connector \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster \
  --region <REGION>

---

Step 3: Configure in xpander UI

Set each skill connection’s IAM Role ARN to its skill role, not the base role:

Skill	Role ARN
Redshift	arn:aws:iam::<ACCOUNT_ID>:role/xpander-redshift-access
EKS	arn:aws:iam::<ACCOUNT_ID>:role/xpander-eks-connector

---

Adding a new skill

For S3, DynamoDB, Athena or any other AWS skill:

1. Create the skill role

   Use the trust policy template above.

2. Attach service-specific permissions

   Add the service permissions and the self-assume policy.

3. Update the base role

   Add the new role ARN to the AssumeConnectorRoles policy on the base role.

4. Configure in xpander UI

   Set the skill’s IAM Role ARN.

5. Restart the skill relay

   kubectl rollout restart deployment xpander-agent-controller -n xpander
   

No Pod Identity change is needed.

---

Role creation order

A role can’t reference itself at creation:

1. Create the role with only the PodIdentity and CrossAccountWithExternalId trust statements.
2. Wait 10 seconds for IAM propagation.
3. Update the trust policy to add the SelfAssume and AllowFromBaseRole statements.

# Step 1: Create without self-reference
aws iam create-role --role-name <ROLE> --assume-role-policy-document file://initial-trust.json

# Step 2: Wait for propagation
sleep 10

# Step 3: Update with self-assume
aws iam update-assume-role-policy --role-name <ROLE> --policy-document file://full-trust.json

---

Troubleshooting

AccessDenied: sts:TagSession

Allow sts:TagSession in both the trust policy (from the caller) and the permission policy (on the role’s own ARN).

AccessDenied: sts:AssumeRole (self-assume)

Remove any ExternalId condition from SelfAssume and AllowFromBaseRole, and add the self-assume permission policy.

AccessDenied: sts:AssumeRole (from base role)

The base role’s policy must list the skill role ARN, and the skill role’s trust policy must have AllowFromBaseRole.

Skill works in cloud but not self-hosted

Self-hosted chains through the base role without an ExternalId. Add the AllowFromBaseRole trust statement.

---

Security recommendations

Recommendation	How
Scope resources	Specific ARNs, not "Resource": "*", where possible
Separate roles per data source	Never combine Redshift and EKS permissions
Rotate ExternalId	The ExternalId is the organization ID. If it leaks, ask xpander to rotate it
Monitor with CloudTrail	Each skill role shows up separately
Tag roles	Environment, Project and ManagedBy
Restrict base role	ONLY sts:AssumeRole and sts:TagSession, never service permissions

Next steps

Set up the AWS Operator

The single-role setup.

Give Bedrock access to the pods

Model access on the pod role.