Pod Identity in vCluster

Overview #

vCluster supports pod identity, allowing a pod’s Kubernetes service account to assume roles across environments.

How it works #

1. A pod uses its service account identity

2. This identity assumes a role in the underlying host cluster account

3. With proper trust policies, the host role can:

   • Assume a role in the customer account
   • Perform actions on behalf of the pod

Important Note #

• This functionality is cloud provider–specific and does not work across CSPs

• Behavior depends on where the vCluster is running:

  • EKS cluster → AWS account only
  • MKS cluster → SPC account only

Limitations #

• Supported only on:

  • AWS
  • GCP

• Cross-CSP operations are not supported

  • To access an AWS account, you must run the vCluster on EKS

Note: The cloud provider of the vCluster must match the account you want to access.

AWS (EKS) Setup #

1. Create Target IAM Role #

The original instructions can be found in the official AWS documentation .

Follow AWS documentation (IAM Console):

Steps #

1. Open Amazon IAM Console

2. Navigate to Roles

3. Click Create role

4. Select:

   • Trusted entity type → AWS account
   • Choose Another AWS account

5. Enter account ID:

   • Ex: 678801588313

6. Click Next

2. Attach Permissions #

• Add required policies (example):
  • AmazonS3FullAccess
• Click Next

3. Configure Role #

• Provide role name Example:

  eks-pod-identity-aws-resources
  

  {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::678801588313:root"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ],
            "Condition": {
                "ArnEquals": {
                    "aws:PrincipalARN": "arn:aws:iam::678801588313:role/dx-eks-podidentity-sandbox-prd-apne2-primary-role"
                }
            }
        }
    ]
  }
  

• Add Trust Policy

• Click Create role

4. Share Details with Kosmos Team #

Provide the following:

• Role ARN Example:

  arn:aws:iam::340605141517:role/eks-pod-identity-aws-resources
  

• Service Account Name

• Service Account Namespace

• vCluster Name

GCP (GKE) Setup #

Prerequisites #

Ensure:

• Required APIs support Workload Identity Federation

  • Supported products and limitations

• IAM Service Account Credentials API is enabled

• Required IAM roles :

  • roles/iam.serviceAccountAdmin

1. Create IAM service account #

Follow the steps to Create vcluster and Pod/Service Account

gcloud iam service-accounts create IAM_SA_NAME \
  --project=IAM_SA_PROJECT_ID

2. Assign roles to service account #

gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \
  --member "serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com" \
  --role "ROLE_NAME"

Replace the following:

IAM_SA_NAME: a name for your new IAM service account. IAM_SA_PROJECT_ID: the project ID for your IAM service account.

Example:

roles/spanner.viewer

3. Allow Kubernetes service account to impersonate #

Create an IAM allow policy that gives the Kubernetes ServiceAccount access to impersonate the IAM service account:

gcloud iam service-accounts add-iam-policy-binding \
  IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:kosmos-[ENV_STRING].svc.id.goog[VCLUSTER_NAMESPACE/VCLUSTER_KSA_NAME]"

Environment Prefix: PRD prod-436507

4. Get vCluster service account details #

The VCLUSTER_NAMESPACE and VCLUSTER_KSA_NAME is provided by the kosmos CLI. You should execute the kosmos CLI translate command to obtain the host service account and namespace information.

Run:

kosmos translate serviceaccount \
  --name demo-sa \
  --namespace default \
  --vcluster sync \
  --devspace wyatt-devspace

Output example #

Namespace: loft-devspace-v-sync
Service Account Name: demo-sa-x-default-x-sync

Use:

• Namespace → VCLUSTER_NAMESPACE
• Service Account Name → VCLUSTER_KSA_NAME

5. Annotate Kubernetes service account #

kubectl annotate serviceaccount KSA_NAME \
  --namespace NAMESPACE \
  iam.gke.io/gcp-service-account=IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com

Create vCluster & configure pod identity #

Steps #

1. Create or edit a vCluster

   

2. Enable:

   • Service Account Sync

3. Ensure:

   • Cluster CSP matches target account (AWS ↔ EKS, SPC ↔ MKS)

Final step #

• Create a Kubernetes Service Account

• Assign it to the Pod

• The pod can now:

  • Assume roles
  • Access cloud resources securely

Edit this page on GitHub