Skip to main content

Agents on AWS

If you're using a Torque K8s agent that runs on an EKS cluster, and you want to deploy AWS resources using Infrastructure as Code (IaC) tools such as Terraform, CloudFormation, CDK, OpenTofu, Ansible, or others, you need to configure authentication and permissions between the Runner pod and the AWS account where the resources will be created. This is done by a service account, which contains these permissions, to the container. The permissions are defined in an IAM role that needs to be associated to the service account.

This authentication setup is required for any IaC tool that provisions AWS resources. While we'll use Terraform as the primary example throughout this guide, the same authentication mechanism applies to all AWS IaC tools.

The basic process is as follows:

For brevity, the term "cluster account" refers to the account hosting the EKS, and "target accounts" is where the rest of the AWS resources are created.

Prerequisites​

Associate your cluster to the cluster account​

To associate the cluster to the account:

  1. In AWS CLI, find the cluster’s OIDC provider by running:

    aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text

    Where my-cluster is the name of the cluster.

    The output looks something like this:

    https://oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE

    Where EXAMPLED539D4633E53DE1B71EXAMPLE is the cluster's OIDC provider

info

Make sure to perform steps 2 and 3 on every target account in which the cluster will perform actions.

  1. Check if the OIDC provider from the cluster's account exists in the target accounts:

    aws iam list-open-id-connect-providers | grep my-cluster-oidc-provider

    The IAM OIDC provider is displayed:

    "Arn": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"

  2. If the IAM OIDC provider is nonexistent, do the following to create it:

    a. Install eksctl on your computer.

    b. Run the following to create the IAM OIDC provider and associate it to your cluster:

    eksctl utils associate-iam-oidc-provider --cluster my-cluster --approve

    c. In AWS CLI, run the following to get the Arn for IAM OIDC provider you created:

    aws iam list-open-id-connect-providers | grep my-cluster-oidc-provider

    You will need this for step 3 in the following procedure.

Create an IAM role for the service account with the required policy​

As we explained before, the service account delegates permissions to the container to perform IaC operations (Terraform, CloudFormation, CDK, OpenTofu, Ansible, etc.). The permissions are defined as a policy in an IAM role that is associated to the service account. Perform these steps on every target account that will be used by your cluster.

Prerequisites

  • IAM policy with the desired permissions for your IaC tool(s). The specific permissions will depend on the AWS resources you plan to provision (EC2, S3, RDS, Lambda, etc.).

To create the IAM role for the service account:

  1. In your AWS Console, go to IAM > Role.
  2. Click Create role, select Web identity.
  3. From the Identity provider dropdown list, select the IAM OIDC that was generated in step 3-c of the above procedure.
  4. From the Audience dropdown list, select sts.amazonaws.com.
  5. Click Next.
  6. Select the IAM policy you wish to associate to the IAM role, and click Next.
  7. Specify a Role name.
  8. Scroll down and click Create role.
  9. Copy the ARN for this role. You will need in the next step.

Create a service account in the cluster’s namespace​

Create the service account in the cluster's namespace you plan on using as the environment namespace, and associate its IAM role to the IAM role you just created.

To create the service account:

  1. Save the following as an SA.yaml file. 
    apiVersion: v1
    kind: ServiceAccount
    metadata:
        annotations:
          eks.amazonaws.com/role-arn: <enter your role arn here>
        name: <service account name>
        namespace: <environment namespace name>
  2. From AWS CLI, run the following command: 
    kubectl apply -f SA.yaml

You're done. All that's left to do is specify the service account name in the blueprint YAML. This authentication method works seamlessly with all AWS IaC tools including Terraform, CloudFormation, CDK, OpenTofu, Ansible, and others. For details on configuring the service account in your blueprint, see Agent.

For additional details, see these AWS docs:​

  1. Create an IAM OIDC provider for your cluster (Instructions).
  2. Create the IAM role to be used by the service account. (Instructions).
  3. Associate the IAM role to a service account on your cluster (Instructions​).
    If the AWS resources are to be created in a different AWS account than the one hosting the EKS cluster (your agent), you'll need to perform steps (1) and (2) on the target account. See AWS' Technical overview.