Skip to main content
Poolside on Amazon EKS uses IAM Roles for Service Accounts (IRSA) so each pod assumes a least-privilege role through the cluster’s OIDC provider. You provision the roles in your AWS account; the Helm chart consumes them through service account annotations. The reference architecture provisions all required IAM roles automatically. If you assemble the AWS foundation by hand, use this page to understand which roles to create and which workloads consume them.
This page describes the IAM model. The reference architecture’s iam module is the source of truth for policy JSON and trust relationships.

​
Roles

RoleK8s ServiceAccount / workloadPurpose
EKS cluster rolen/aLets the EKS control plane manage AWS resources for the cluster.
CPU node-group instance rolen/aWorker-node permissions for the platform node group.
GPU node-group instance rolen/aWorker-node permissions for the inference node group (full profile).
core-api IRSA rolepoolside/core-api-saApplication access to S3 (user data), KMS, and AWS Marketplace metering.
inference IRSA rolepoolside-models/inferenceRead access to the model checkpoints S3 bucket.
External Secrets Operator IRSA roleexternal-secrets/external-secretsReference-architecture-only. Reads the RDS master password from AWS Secrets Manager. See External Secrets Operator below.
AWS Load Balancer Controller IRSA rolekube-system/aws-load-balancer-controllerProvisions ALBs and target groups from Kubernetes Ingress resources.
EBS CSI driver IRSA rolekube-system/ebs-csi-controller-saProvisions EBS volumes for gp3 PersistentVolumeClaims.
VPC CNI IRSA rolekube-system/aws-nodeLets the vpc-cni add-on manage network interfaces and IP addresses for pods.
For per-role policy documents and trust relationships, see the iam module in the reference architecture repository.

​
Notes on specific roles

​
core-api

The core application uses three distinct AWS services, so its IRSA role bundles three policies:
  • S3 (bucket-scoped): the application stores user data and platform assets in your Poolside S3 bucket.
  • KMS (key-scoped): the application encrypts sensitive fields using a customer-managed KMS key.
  • AWS Marketplace metering: deployments that subscribe through AWS Marketplace report metering records using aws-marketplace:MeterUsage. This action does not support resource-level scoping, so the policy is granted on *.

​
AWS Load Balancer Controller

The controller’s policy follows the upstream AWS Load Balancer Controller IAM policy maintained by the project. Use that JSON as your source of truth; the reference architecture pins a specific revision.

​
Node-group instance roles

These are EC2 instance roles, not IRSA roles, and pods do not assume them. They attach the standard EKS-managed worker-node policies. With IRSA in use, pod-level AWS access (S3, KMS, Secrets Manager, and so on) is granted through the IRSA roles in the preceding table, not through the node role.

​
External Secrets Operator

The Poolside Helm chart does not depend on ESO. It expects the RDS password to be available as a Kubernetes Secret (default name poolside-db-secret) in the poolside namespace and is agnostic to how that Secret was populated. The reference architecture deploys ESO to fetch the RDS password from AWS Secrets Manager at runtime, which keeps the password out of Terraform state. If you provision the Kubernetes Secret another way, for example with kubectl create secret or your own secret-management tooling, you can omit ESO and this IRSA role.