Skip to main content

Manage IAM roles for clusters on Anyscale on EKS

This page describes how to use and manage IAM roles for Anyscale clouds deployed on Amazon Elastic Kubernetes Service (EKS).

How does Anyscale interact with EKS service accounts?​

The Anyscale control plane interacts with EKS service accounts through the Anyscale operator. You must configure how EKS service accounts map to IAM permissions to control access to resources in your AWS account. See the following AWS documentation for supported methods:

You annotate your EKS service account to add a trust relationship with the IAM role. This annotation provides nodes in your Anyscale cluster access to resources in your cloud provider account, such as the default S3 bucket configured during your cloud deployment.

When you deploy Anyscale on EKS, you configure the following trust relationships between your EKS service accounts, Anyscale, and your AWS IAM roles:

TermDescription
Anyscale operator IAM roleWhen you deploy an Anyscale cloud on EKS, you configure a Kubernetes service account for the Anyscale operator that maps to an IAM role in your cloud provider account.

The permissions in this IAM role govern all actions that the Anyscale operator can take in your EKS cluster. The Anyscale operator is responsible for processing all instructions from the Anyscale control plane to deploy nodes for Ray clusters in your EKS cluster.
Cluster IAM roleWhen you configure the Anyscale operator for your Anyscale cloud on EKS, you configure a default Kubernetes service account that maps to an IAM role. When the Anyscale operator deploys a new cluster or autoscales to adds worker nodes, the Pods use this service account and assume the IAM role to gain access to necessary resources in your cloud provider account.

You must define a Kubernetes service account for each unique set of IAM permissions you want to assign to a given user, workload, or project through cloud IAM mapping.

View cluster service account and IAM role​

Run the following commands to find the Kubernetes service account in use Pods in your Anyscale cluster:

# Define your EKS namespace.
NAMESPACE="<your-eks-namespace>"

# Get all Pods and manually identify your Pod.
kubectl get pods -n ${NAMESPACE} | grep k-

# Define a variable for your Pod name.
POD_NAME="<your-pod-name>"

# Get the Kubernetes service account name use by your Pod.
kubectl get pod ${POD_NAME} -n ${NAMESPACE} -o jsonpath='{.spec.serviceAccountName}'

To see the AWS IAM role used by your Kubernetes service account, run the following command:

kubectl get serviceaccount "<your-kubernetes-service-account>" -n "${NAMESPACE}" \
  -o jsonpath='{.metadata.annotations.eks\.amazonaws\.com/role-arn}{"\n"}'

Create and map an EKS cluster IAM role​

To create a new cluster IAM role, you annotate a Kubernetes service account with an AWS IAM role. You use the permissions in the IAM role to grant access to additional resources in your cloud provider account, such as S3 buckets.

note

Use cloud IAM mapping to control how Anyscale assigns cluster IAM roles based on user identity, workload type, or project.

You must create and annotate a Kubernetes service account for each unique IAM role you need to assign to Anyscale clusters. See Anyscale cloud IAM mapping.

Complete the following steps to annotate an EKS service account.

important

The following instructions assume you have installed and configured the AWS CLI and kubectl.

Step 0: Identify or create an IAM role​

Identify or create the IAM role you need to attach to your EKS cluster.

This IAM role has the following requirements:

Record the name of your IAM role. You need this to define the ARN for the IAM role.

Step 1: Configure variables​

The following commands configure variables that describe your AWS account, EKS cluster, and Anyscale account. Replace the variables denoted with <> before running these commands. For example, replace <your-anyscale-cloud-name> with the name of your Anyscale cloud deployed on EKS.

note

You can save and run these commands as a .sh script, or run each command sequentially from the command line.

#!/bin/bash

# Anyscale recommends using the cloud name as your EKS namespace.
# If you have a different configuration, use that namespace.
export CLOUD_NAME="<your-anyscale-cloud-name>"
export NAMESPACE="${CLOUD_NAME}"

# Specify the AWS region and name of your EKS cluster.
export AWS_REGION="<your-aws-region>"
export EKS_CLUSTER_NAME="<your-eks-cluster-name>"

# Capture the AWS account ID as a variable.
export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"

# Define the name for a new service account.
export SERVICE_ACCOUNT_NAME="<your-service-account-name>"

# Define the ARN for the IAM role.
export AWS_ROLE_ARN="arn:aws:iam::${AWS_ACCOUNT_ID}:role/<your-iam-role>"

Step 2: Validate EKS configuration​

Run the following command to connect to your EKS cluster and display your current configuration:

aws eks update-kubeconfig --region "${AWS_REGION}" --name "${EKS_CLUSTER_NAME}"
kubectl config current-context

Step 3: Create a Kubernetes service account​

Run the following command to create a Kubernetes service account in the namespace of you EKS cluster:

kubectl create serviceaccount "${SERVICE_ACCOUNT_NAME}" -n "${NAMESPACE}" \
  --dry-run=client -o yaml | kubectl apply -f -

Step 4: Annotate the Kubernetes service account​

Run the following command to annotate the EKS service account with the IAM role ARN:

kubectl annotate serviceaccount "${SERVICE_ACCOUNT_NAME}" -n "${NAMESPACE}" \
  eks.amazonaws.com/role-arn="${AWS_ROLE_ARN}" --overwrite

Step 5: Verify the annotation​

Run the following command to display the annotation field of your service account:

kubectl get serviceaccount "${SERVICE_ACCOUNT_NAME}" -n "${NAMESPACE}" \
  -o jsonpath='{.metadata.annotations.eks\.amazonaws\.com/role-arn}{"\n"}'

The IAM role ARN you assigned to the service account displays.