ServiceAccount Configuration - CrewAI Platform Helm Chart

The Kubernetes ServiceAccount provides an identity for processes running in pods. For cloud provider integrations (GCP, AWS, Azure), annotations on the ServiceAccount enable Workload Identity or IRSA to grant cloud permissions without static credentials.

serviceAccount.name

string

default:""

Name of the Kubernetes ServiceAccount to create or use.Default Behavior: When empty, defaults to {release-name}-sa when rbac.create: true.Purpose: Provides an identity for web, worker, buildkit, and job pods.Example:

serviceAccount:
  name: crewai-platform-sa

The default ServiceAccount name is automatically generated based on the Helm release name. Most deployments don’t need to override this.

serviceAccount.annotations

object

default:"{}"

Annotations to add to the ServiceAccount.Purpose: Enable cloud provider Workload Identity or IRSA bindings to grant cloud permissions without static credentials.Common Use Cases:

GCP Workload Identity - Bind Kubernetes ServiceAccount to Google Service Account
AWS IRSA - Bind Kubernetes ServiceAccount to IAM Role
Azure Workload Identity - Bind Kubernetes ServiceAccount to Azure Managed Identity
Custom Metadata - Add arbitrary metadata for organizational tracking

Example - GCP Workload Identity:

serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com

Example - AWS IRSA:

serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/crewai-platform

Example - Azure Workload Identity:

serviceAccount:
  annotations:
    azure.workload.identity/client-id: 12345678-1234-1234-1234-123456789abc

Example - Multiple Annotations:

serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com
    company.com/team: platform-engineering
    company.com/cost-center: engineering

Cloud Provider Workload Identity

GCP Workload Identity

Workload Identity allows Kubernetes pods to authenticate as a Google Service Account without needing static credentials (JSON keys). Prerequisites:

GKE cluster has Workload Identity enabled
Google Service Account (GSA) created with required IAM roles
IAM binding created between Kubernetes ServiceAccount and GSA

Configuration:

serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

IAM Binding Command:

gcloud iam service-accounts add-iam-policy-binding \
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

Complete Example:

# values.yaml
serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com

# GCS configuration
envVars:
  STORAGE_SERVICE: google
  GCS_PROJECT_ID: my-project
  GCS_BUCKET: crewai-storage
  GCS_IAM_SIGNING: "true"

# Cloud SQL Proxy with IAM auth
cloudSqlProxy:
  enabled: true
  instanceConnectionName: my-project:us-central1:crewai-db
  autoIamAuthn: true

See Also: GCP Integration Guide for complete Workload Identity setup.

AWS IRSA (IAM Roles for Service Accounts)

IRSA allows Kubernetes pods to assume an IAM role without needing static access keys. Prerequisites:

EKS cluster has IRSA enabled (OIDC provider configured)
IAM role created with required policies
Trust relationship configured between IAM role and Kubernetes ServiceAccount

Configuration:

serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME

IAM Trust Relationship Example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/oidc.eks.REGION.amazonaws.com/id/CLUSTER_ID"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.REGION.amazonaws.com/id/CLUSTER_ID:sub": "system:serviceaccount:NAMESPACE:KSA_NAME"
        }
      }
    }
  ]
}

Complete Example:

serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/crewai-platform

envVars:
  STORAGE_SERVICE: amazon
  AWS_REGION: us-west-2
  AWS_BUCKET: crewai-storage

# No AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY needed

See Also: AWS Integration Guide for complete IRSA setup.

Azure Workload Identity

Azure Workload Identity allows Kubernetes pods to authenticate as an Azure Managed Identity. Prerequisites:

AKS cluster has Workload Identity enabled
Azure Managed Identity created with required permissions
Federated identity credential configured

Configuration:

serviceAccount:
  annotations:
    azure.workload.identity/client-id: MANAGED_IDENTITY_CLIENT_ID

Complete Example:

serviceAccount:
  annotations:
    azure.workload.identity/client-id: 12345678-1234-1234-1234-123456789abc

envVars:
  STORAGE_SERVICE: microsoft
  AZURE_STORAGE_ACCOUNT_NAME: crewaistorage

# No AZURE_STORAGE_ACCESS_KEY needed

RBAC Integration

rbac.create

boolean

default:"true"

Create RBAC resources (ServiceAccount, Role, RoleBinding) automatically.When true:

Chart creates ServiceAccount
Chart creates Role with required permissions
Chart creates RoleBinding linking ServiceAccount to Role

When false:

ServiceAccount must already exist
Permissions must be manually configured
Specify existing ServiceAccount name via serviceAccount.name

Example - Use Existing ServiceAccount:

rbac:
  create: false

serviceAccount:
  name: existing-service-account

rbac.namespaceIsolation

boolean

default:"false"

Enable ClusterRole and ClusterRoleBinding for namespace isolation.When true:

Chart creates ClusterRole with permissions to manage resources across namespaces
Chart creates ClusterRoleBinding to grant ServiceAccount cluster-wide access
Required when k8s_namespace_isolation feature flag is enabled

When false:

Platform operates within release namespace and configured crew namespace only
No cluster-wide permissions granted

Purpose: Allows CrewAI Platform to dynamically create and manage per-organization namespaces (e.g., crewai-crews-org-1, crewai-crews-org-2) for workload isolation when the k8s_namespace_isolation feature flag is enabled.Permissions Granted (when enabled):

Namespace management: create, get, list, watch
Resource management across namespaces: secrets, configmaps, services, pods, PVCs, deployments, statefulsets, jobs, ingresses
Pod operations: exec, logs

Example - Enable Namespace Isolation:

rbac:
  create: true
  namespaceIsolation: true

Enabling namespace isolation grants cluster-wide permissions to the CrewAI Platform ServiceAccount. Ensure your organization’s security policies allow ClusterRole creation before enabling this feature.

This setting is only relevant when rbac.create: true. If using an existing ServiceAccount (rbac.create: false), you must manually configure the required ClusterRole and ClusterRoleBinding permissions for namespace isolation to work.

Complete Examples

GCP with Workload Identity (Recommended for GCP)

# ServiceAccount configuration
serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com

# RBAC
rbac:
  create: true

# Cloud services using Workload Identity
cloudSqlProxy:
  enabled: true
  instanceConnectionName: my-project:us-central1:crewai-db
  autoIamAuthn: true

envVars:
  STORAGE_SERVICE: google
  GCS_PROJECT_ID: my-project
  GCS_BUCKET: crewai-storage
  GCS_IAM_SIGNING: "true"
  CREW_IMAGE_REGISTRY_OVERRIDE: us-central1-docker.pkg.dev/my-project/crewai

# No static credentials needed

AWS with IRSA (Recommended for AWS)

# ServiceAccount configuration
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/crewai-platform

# RBAC
rbac:
  create: true

# Cloud services using IRSA
envVars:
  STORAGE_SERVICE: amazon
  AWS_REGION: us-west-2
  AWS_BUCKET: crewai-storage
  CREW_IMAGE_REGISTRY_OVERRIDE: 123456789012.dkr.ecr.us-west-2.amazonaws.com/crewai

# No AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY needed

Azure with Workload Identity

# ServiceAccount configuration
serviceAccount:
  annotations:
    azure.workload.identity/client-id: 12345678-1234-1234-1234-123456789abc

# RBAC
rbac:
  create: true

# Cloud services using Workload Identity
envVars:
  STORAGE_SERVICE: microsoft
  AZURE_STORAGE_ACCOUNT_NAME: crewaistorage

# No AZURE_STORAGE_ACCESS_KEY needed

Using Existing ServiceAccount

rbac:
  create: false

serviceAccount:
  name: my-existing-serviceaccount

When using an existing ServiceAccount (rbac.create: false), ensure it has the required permissions for CrewAI Platform operations. See the chart’s Role template for the full list of required permissions.

Troubleshooting

Workload Identity Not Working

Symptoms: Pods show could not retrieve default credentials or 403 Forbidden when accessing cloud services. Debug Steps:

# Verify ServiceAccount annotation
kubectl get serviceaccount <sa-name> -n <namespace> -o yaml

# Should show annotation:
#   iam.gke.io/gcp-service-account: GSA@PROJECT.iam.gserviceaccount.com (GCP)
#   eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT:role/ROLE (AWS)
#   azure.workload.identity/client-id: CLIENT_ID (Azure)

# Test from a pod (GCP example)
kubectl run -it --rm test \
  --image=google/cloud-sdk:slim \
  --serviceaccount=<sa-name> \
  --restart=Never -- \
  gcloud auth print-access-token

Common Causes:

Annotation missing or incorrect
IAM binding not configured (cloud provider side)
Workload Identity not enabled on cluster
Namespace or ServiceAccount name mismatch in IAM binding

Pods Can’t Access Cloud Resources

Symptoms: Application logs show Access Denied, Unauthorized, or InvalidCredentials. Verify IAM Permissions: GCP:

gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:GSA@PROJECT.iam.gserviceaccount.com" \
  --format="table(bindings.role)"

AWS:

aws iam get-role --role-name ROLE_NAME
aws iam list-attached-role-policies --role-name ROLE_NAME

Azure:

az role assignment list \
  --assignee MANAGED_IDENTITY_CLIENT_ID \
  --output table

GCP Workload Identity Setup: See GCP Integration Guide for complete Workload Identity configuration including IAM bindings and permissions. AWS IRSA Setup: See AWS Integration Guide for complete IRSA configuration including trust relationships and IAM policies. RBAC Configuration: See Global Configuration - RBAC for Role and RoleBinding creation settings. Cloud SQL Proxy: See Cloud SQL Auth Proxy for using Workload Identity with Cloud SQL.

​Cloud Provider Workload Identity

​GCP Workload Identity

​AWS IRSA (IAM Roles for Service Accounts)

​Azure Workload Identity

​RBAC Integration

​Complete Examples

​GCP with Workload Identity (Recommended for GCP)

​AWS with IRSA (Recommended for AWS)

​Azure with Workload Identity

​Using Existing ServiceAccount

​Troubleshooting

​Workload Identity Not Working

​Pods Can’t Access Cloud Resources

​Related Configuration

Cloud Provider Workload Identity

GCP Workload Identity

AWS IRSA (IAM Roles for Service Accounts)

Azure Workload Identity

RBAC Integration

Complete Examples

GCP with Workload Identity (Recommended for GCP)

AWS with IRSA (Recommended for AWS)

Azure with Workload Identity

Using Existing ServiceAccount

Troubleshooting

Workload Identity Not Working

Pods Can’t Access Cloud Resources

Related Configuration