AWS Authentication via IRSA

This guide explains how to configure a Firefly self-hosted runner on EKS to authenticate with AWS using IAM Roles for Service Accounts (IRSA). With IRSA, Terraform running inside the runner can access AWS resources (state backend, provider APIs) without static credentials.

Prerequisites

1. EKS Cluster with OIDC Provider

Your EKS cluster must have an OpenID Connect (OIDC) provider configured. Verify with:

aws eks describe-cluster --name <cluster-name> \
  --query "cluster.identity.oidc.issuer" --output text

2. IAM Role

Create an IAM role that:

• Has a trust policy allowing the Kubernetes service account to assume it via sts:AssumeRoleWithWebIdentity

• Has permissions for the S3 state backend and any AWS resources Terraform will manage

Configuration

Runner Image

Update the runner to an image that includes IRSA credential forwarding. Use latest or pin a specific tag:

repository:
  tag: "latest"  # or a specific version tag

Helm Chart

Update to the latest version of the ci-runner-worker chart:

chart: "ci-runner-worker"
targetRevision: "0.0.10"

Helm Values

Annotate the service account with the IAM role ARN:

serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"

The EKS webhook uses this annotation to automatically inject the projected token volume, volumeMounts, and AWS_ROLE_ARN / AWS_WEB_IDENTITY_TOKEN_FILE env vars into all containers in the pod. No manual volume or volumeMount configuration is required.

Workspace Variables

Set the following as environment variables on the workspace in the Firefly UI:

Variable	Value
AWS_DEFAULT_REGION	Target AWS region (e.g. eu-west-1)
AWS_REGION	Target AWS region (e.g. eu-west-1)

Terraform Configuration

No special provider configuration is needed. The AWS SDK automatically detects the IRSA env vars and calls sts:AssumeRoleWithWebIdentity:

provider "aws" {
}

terraform {
  backend "s3" {
    bucket = "<BUCKET_NAME>"
    key    = "<STATE_KEY>"
    region = "<REGION>"
  }
}

Limitations

1. EKS only. IRSA is an EKS-specific feature. This approach does not work on other Kubernetes distributions (GKE, AKS, vanilla k8s). Alternative authentication methods (static credentials via workspace variables) are needed there.

2. Single AWS account per runner. The IRSA role is bound to the runner's service account. All Terraform workspaces executed by that runner assume the same IAM role.

3. Token expiry. The projected token has a default expiration of 24 hours. Kubelet automatically refreshes it before expiry, however, long-running Terraform operations that exceed the token's remaining lifetime may fail mid-operation.