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