Documentation

Adding an EKS cluster

Add your AWS EKS clusters to Opal to allow your developers to request temporary access.

Suggest Edits

Overview

Here's a quick overview of how Opal connects with AWS EKS.

3840

To set up Opal to grant access to your AWS EKS cluster roles, follow the steps below.

Adding an EKS cluster

Step 1: Create an IAM role

First, create an IAM role and attach it to the AWS EKS cluster role that you want to make available on Opal. We've provided two ways to do this below, via AWS CLI commands or Terraform:

# Add your AWS account ID to an environment variable
ACCOUNT_ID=<YOUR_AWS_ACCOUNT_ID>
# Create the IAM role naming it something your developers will understand
ROLE_NAME=<YOUR_ROLE_NAME>
# Add your cluster ARN to an environment variable
CLUSTER_ARN=<YOUR_CLUSTER_ARN>

# Create the role trust policy locally
TRUST="{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Effect\": \"Allow\", \"Principal\": { \"AWS\": \"arn:aws:iam::${ACCOUNT_ID}:root\" }, \"Action\": \"sts:AssumeRole\" } ] }"
echo "{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Effect\": \"Allow\", \"Action\": \"eks:*\", \"Resource\": \"${CLUSTER_ARN}\" } ] }" > /tmp/iam-role-policy

# Create the IAM role
aws iam create-role --role-name "$ROLE_NAME" --assume-role-policy-document "$TRUST" --output text --query 'Role.Arn'

# Attach the policy to the role
aws iam put-role-policy --role-name "$ROLE_NAME" --policy-name eks-admin --policy-document file:///tmp/iam-role-policy

resource "aws_iam_policy" "AmazonEKSAdminPolicy" {
  name   = "AmazonEKSAdminPolicy"
  policy = <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "eks:*",
            "Resource": "${CLUSTER_ARN}"
        }
    ]
}
EOF
}

resource "aws_iam_role" "eks_cluster_admin_role" {
  name = ${ROLE_NAME}

  assume_role_policy = <<POLICY
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::${ACCOUNT_ID}:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
POLICY

  max_session_duration = 12 * 60 * 60
}

resource "aws_iam_role_policy_attachment" "AmazonEKSAdminPolicy" {
  policy_arn = aws_iam_policy.AmazonEKSAdminPolicy.arn
  role       = aws_iam_role.eks_cluster_admin_role.name
}

Make sure to set the following variables when running the above code:

  • ACCOUNT_ID=<YOUR_AWS_ACCOUNT_ID>
  • ROLE_NAME=<YOUR_ROLE_NAME>
  • CLUSTER_ARN=<YOUR_CLUSTER_ARN>

Step 2: Update the aws-auth Configmap

The aws-auth Configmap exists on every EKS cluster and is what AWS uses to map IAM roles to Kubernetes roles. To map the role you created above to a cluster-admin level role in Kubernetes, please run the following commands:

ROLE="    - rolearn: arn:aws:iam::$ACCOUNT_ID:role/$ROLE_NAME\n      username: eks-cluster-admin:{{SessionName}}\n      groups:\n        - system:masters"

kubectl get -n kube-system configmap/aws-auth -o yaml | awk "/mapRoles: \|/{print;print \"$ROLE\";next}1" > /tmp/aws-auth-patch.yml

kubectl patch configmap/aws-auth -n kube-system --patch "$(cat /tmp/aws-auth-patch.yml)"

📘

Creating different levels of privilege in Kubernetes

The aws-auth Configmap lets you map IAM roles to different Kubernetes roles. You'll need to do this if you want to allow users to request access to custom access levels, like a "read-only" role. You can manually edit the Configmap by running the following command:

kubectl edit configmaps aws-auth -n kube-system

Then, you can map different roles to your IAM role ARN. You can read up on how to this by checking out these articles:

If this part of the setup is confusing, please feel free to reach out to [email protected] - we're happy to help.

Step 3: Tag your EKS cluster

You'll need to tag your EKS cluster in 2 ways to properly set it up for Opal.

First, you must tag the cluster with any IAM roles that you set up in Step 1. For each IAM role, create a tag whose key is prefixed with opal:eks:role, and whose value is the name of the AWS IAM role. Below, we show an example of a cluster tagged with 2 IAM roles:

aws eks tag-resource --resource-arn "$CLUSTER_ARN" --region $REGION —tags "opal:eks:role:1=ClusterAdmin,opal:eks:role:2=ClusterView"

module "eks" {
  # ... other configuration

  cluster_tags = {
    "opal:eks:role:1" = ClusterAdmin
    "opal:eks:role:2" = ClusterView
  }
}

Each of these roles will be auto-imported as a Role on the cluster in Opal.

2314

Second, to have your EKS cluster auto-imported into Opal in Opal's hourly sync, tag the cluster with key opal:

aws eks tag-resource --resource-arn "$CLUSTER_ARN" --region $REGION --tags "opal="

module "eks" {
  # ... other configuration

  cluster_tags = {
    # Note: the tag value can be empty; however currently terraform-aws-provider has an issue
    # adding tags with empty values
    # https://github.com/hashicorp/terraform-provider-aws/issues/21896
    "opal" = "x"
  }
}

Accessing your cluster in Opal

Any EKS clusters tagged using with key opal will be auto-imported into the "Resources" page in the "Kubernetes" folder.

Permissions to EKS clusters are session-based, meaning users must initiate temporary sessions to them. They can do so using the Connect button after clicking into an EKS cluster resource.

2312

Use the "Connect" button to start an EKS session via Opal.

Once they're connected, they'll be given temporary credentials to access the Kubernetes cluster.

1112

Kubernetes session credentials in Opal.

Updated 26 days ago