Manage service accounts for clusters on Anyscale on GKE

This page describes how to use and manage service accounts for Anyscale clouds deployed on Google Kubernetes Engine (GKE).

How does Anyscale interact with GKE service accounts?

The Anyscale control plane interacts with GKE service accounts through the Anyscale operator. GKE uses Workload Identity Federation to map IAM permissions from Google Cloud service accounts onto Kubernetes service accounts. See the following Google Cloud docs pages for more details:

• About service accounts in GKE
• Workload Identity Federation

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

When you deploy Anyscale on GKE, you configure the following trust relationships between your GKE service accounts, Anyscale, and your Google Cloud service accounts:

Term	Description
Anyscale operator IAM role	When you deploy an Anyscale cloud on GKE, you configure a Kubernetes service account for the Anyscale operator that maps to a Google Cloud service account. The permissions in this service account govern all actions that the Anyscale operator can take in your GKE cluster. The Anyscale operator is responsible for processing all instructions from the Anyscale control plane to deploy nodes for Ray clusters in your GKE cluster.
Cluster service account	When you configure the Anyscale operator for your Anyscale cloud on GKE, you configure a default Kubernetes service account that maps to a Google Cloud service account. When the Anyscale operator deploys a new cluster or autoscales to adds worker nodes, the Pods use this service account and assume the Google Cloud service account 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

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

# Define your GKE namespace.
NAMESPACE="<your-gke-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 Google Cloud service account used by your Kubernetes service account, run the following command:

kubectl get serviceaccount "<your-kubernetes-service-account>" -n "${NAMESPACE}" \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}{"\n"}'

Create and map a GKE cluster service account

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

note

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

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

Complete the following steps to annotate a GKE service account.

important

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

Step 0: Identify or create a Google Cloud service account

Identify or create the Google Cloud service account you need to attach to your GKE cluster.

This service account has the following requirements:

• Your service account must have the same minimum permissions as a service account used for an Anyscale cloud deployed on Google Cloud using virtual machines. See Minimum privileges for Anyscale cluster service accounts.

Record the name of your service account. You need this to define the email for your Google Cloud service account.

Step 1: Configure variables

The following commands configure variables that describe your Google Cloud account, GKE 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 GKE.

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 GKE namespace.
# If you have a different configuration, use that namespace.
export CLOUD_NAME="<your-anyscale-cloud-name>"
export NAMESPACE="${CLOUD_NAME}"

# Specify the Google Cloud region, project ID, and name of your GKE cluster.
export PROJECT_ID="<your-google-cloud-project-id>"
export GKE_REGION="<your-gke-region>"
export GKE_CLUSTER_NAME="<your-gke-cluster-name>"

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

# Define a variable for the name of your Google Cloud service account.
# Use variables to format the email address for the Google Cloud service account.
export GOOGLE_SERVICE_ACCOUNT_NAME="<your-google-service-account-name>"
export GOOGLE_SERVICE_ACCOUNT_EMAIL="${GOOGLE_SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

Step 2: Create a Kubernetes service account

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

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

Step 3: Annotate the Kubernetes service account

Run the following command to annotate the GKE service account with the Google Cloud service account email:

kubectl annotate serviceaccount "${SERVICE_ACCOUNT_NAME}" -n "${NAMESPACE}" \
  iam.gke.io/gcp-service-account="${GOOGLE_SERVICE_ACCOUNT_EMAIL}" --overwrite

Step 4: 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.iam\.gke\.io/gcp-service-account}{"\n"}'

The Google Cloud service account email you assigned to the GKE service account displays.