Skip to main content

Documentation Index

Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. GKE cluster has Workload Identity enabled
  2. Google Service Account (GSA) created with required IAM roles
  3. 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:
  1. EKS cluster has IRSA enabled (OIDC provider configured)
  2. IAM role created with required policies
  3. 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:
  1. AKS cluster has Workload Identity enabled
  2. Azure Managed Identity created with required permissions
  3. 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

# 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

# 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:
  1. Annotation missing or incorrect
  2. IAM binding not configured (cloud provider side)
  3. Workload Identity not enabled on cluster
  4. 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.