Skip to main content

Terraform EKS/AWS Authentication

If you're using an EKS cluster as your agent, and you want to run Terraform that deploys resources on AWS, you can use a service account to do the authentication and permissions between the pod and the AWS account where the resources will be created. This is done by connecting 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.

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.

  2. 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"

  3. 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 the Terraform actions. 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

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. For details, 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 Terraform resources are to be created in a different AWS account than the one hosting the EKS cluster which is our agent, you'll need to perform steps (1) and (2) on the target account. See AWS' Technical overview.