> For the complete documentation index, see [llms.txt](https://docs.firefly.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firefly.ai/detailed-guides/workflows/creating-self-hosted-runner/self-hosted-runner-aws-irsa.md).

# 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:

```bash
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:

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

### Helm Chart

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

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

### Helm Values

Annotate the service account with the IAM role ARN:

```yaml
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`:

```hcl
provider "aws" {
}

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

## Cross-Account Terraform Execution with IRSA on Self-Hosted Runners

Firefly self-hosted runners support IAM Roles for Service Accounts (IRSA) for authenticating Terraform operations across multiple AWS accounts — without requiring a dedicated runner in each account.

### How It Works

The setup relies on IAM role chaining, where the runner's service account role assumes a role in a target account. This is standard Terraform behavior using the S3 backend's `role_arn` configuration.

### Configuration Steps

1. In the Helm chart, define the IAM role ARN (Role A) under `.Values.serviceAccount.annotations`. This role must reside in the same AWS account as the Firefly runners.
2. In `providers.tf`, set `terraform.backend.s3.role_arn` to a role in the target AWS account (Role B).
3. Ensure the appropriate cross-account trust is in place: Role A must have permission to assume Role B (via its IAM policy), and Role B's trust policy must allow Role A to assume it.

Once configured, `terraform plan` and other operations execute against the target AWS account by design — eliminating the need to deploy a runner in every account.

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.firefly.ai/detailed-guides/workflows/creating-self-hosted-runner/self-hosted-runner-aws-irsa.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.