How to run the agent on EKS (AWS Kubernetes) with a specific IAM role – HashiCorp Help Center

Introduction

When running self-hosted Terraform Enterprise agents on Amazon EKS, you may need to configure the agent's workspace to execute runs using a specific AWS IAM role. This allows Terraform to manage AWS resources with a defined set of permissions.

This guide provides two methods for associating an IAM role with a Terraform Enterprise agent running on EKS.

Prerequisites

Before proceeding, ensure you have met the AWS prerequisites for associating an IAM role with a Kubernetes service account. This includes:

An EKS cluster with an OIDC provider configured.
An IAM role with the necessary policies to manage the target AWS resources.
A trust relationship established between the IAM role and the OIDC provider.

For detailed instructions, refer to the AWS documentation on IAM roles for service accounts.

Solutions

Choose one of the following options to configure the agent.

Option 1: Use the AWS Provider `assume_role` Block

This approach involves configuring the AWS provider directly within your Terraform configuration to assume a specific IAM role. This method is useful when you want to manage the role assumption explicitly in your code.

Configure your AWS provider block to assume the desired role.

provider "aws" {
  region = "us-east-1"

  assume_role {
    role_arn     = "arn:aws:iam::<ACCOUNT_ID>:role/test-run"
    session_name = "TFE-Deployment"
  }
}

Option 2: Use an IAM Role for the Service Account

This approach involves associating the IAM role directly with the Kubernetes service account that the Terraform Enterprise agent pod uses. When configured, any process running in the pod, including Terraform, will automatically assume the specified IAM role without needing an assume_role block in the provider configuration.

Procedure

Create a Kubernetes ServiceAccount in the same namespace as your agents. Annotate it with the ARN of the IAM role you want to use. Note that your namespace may differ from the example.

apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/test-run2
  name: tfe-run
  namespace: terraform-enterprise-agents

Modify your Terraform Enterprise Helm chart or deployment configuration to specify that the agent pods should use this service account. The example below shows a modification to the agentWorkerPodTemplate.
```
agentWorkerPodTemplate:
  metadata:
    labels:
      app: pod-template-app-patrick
  spec:
    serviceAccountName: tfe-run
```
With this configuration, you can use a simpler AWS provider block in your Terraform code, as the authentication is handled by the service account.
```
provider "aws" {
  region = "us-east-1"
}
```

When a run starts, the agent pod will launch using the tfe-run service account and automatically inherit the permissions of the associated IAM role.

Additional Information

For more details on the assume_role block, see the AWS Provider - Assuming an IAM Role documentation.
For more information on the underlying Kubernetes and AWS configuration, refer to the AWS documentation on IAM roles for service accounts.