> ## 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.

# ServiceAccount Configuration

> Kubernetes ServiceAccount configuration for CrewAI Platform pods and Workload Identity binding.

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.

<ParamField path="serviceAccount.name" type="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:**

  ```yaml theme={null}
  serviceAccount:
    name: crewai-platform-sa
  ```

  <Note>
    The default ServiceAccount name is automatically generated based on the Helm release name. Most deployments don't need to override this.
  </Note>
</ParamField>

<ParamField path="serviceAccount.annotations" type="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:**

  ```yaml theme={null}
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: crewai-platform@my-project.iam.gserviceaccount.com
  ```

  **Example - AWS IRSA:**

  ```yaml theme={null}
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/crewai-platform
  ```

  **Example - Azure Workload Identity:**

  ```yaml theme={null}
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: 12345678-1234-1234-1234-123456789abc
  ```

  **Example - Multiple Annotations:**

  ```yaml theme={null}
  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
  ```
</ParamField>

## 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:**

```yaml theme={null}
serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
```

**IAM Binding Command:**

```bash theme={null}
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:**

```yaml theme={null}
# 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](/cloud-providers/gcp#step-3-bind-workload-identity) 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:**

```yaml theme={null}
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME
```

**IAM Trust Relationship Example:**

```json theme={null}
{
  "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:**

```yaml theme={null}
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](/cloud-providers/aws#iam-roles-for-service-accounts-irsa) 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:**

```yaml theme={null}
serviceAccount:
  annotations:
    azure.workload.identity/client-id: MANAGED_IDENTITY_CLIENT_ID
```

**Complete Example:**

```yaml theme={null}
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

<ParamField path="rbac.create" type="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:**

  ```yaml theme={null}
  rbac:
    create: false

  serviceAccount:
    name: existing-service-account
  ```
</ParamField>

<ParamField path="rbac.namespaceIsolation" type="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:**

  ```yaml theme={null}
  rbac:
    create: true
    namespaceIsolation: true
  ```

  <Warning>
    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.
  </Warning>

  <Note>
    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.
  </Note>
</ParamField>

## Complete Examples

### GCP with Workload Identity (Recommended for GCP)

```yaml theme={null}
# 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)

```yaml theme={null}
# 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

```yaml theme={null}
# 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

```yaml theme={null}
rbac:
  create: false

serviceAccount:
  name: my-existing-serviceaccount
```

<Note>
  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.
</Note>

## Troubleshooting

### Workload Identity Not Working

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

**Debug Steps:**

```bash theme={null}
# 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:**

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

**AWS:**

```bash theme={null}
aws iam get-role --role-name ROLE_NAME
aws iam list-attached-role-policies --role-name ROLE_NAME
```

**Azure:**

```bash theme={null}
az role assignment list \
  --assignee MANAGED_IDENTITY_CLIENT_ID \
  --output table
```

***

## Related Configuration

**GCP Workload Identity Setup:** See [GCP Integration Guide](/cloud-providers/gcp) for complete Workload Identity configuration including IAM bindings and permissions.

**AWS IRSA Setup:** See [AWS Integration Guide](/cloud-providers/aws) for complete IRSA configuration including trust relationships and IAM policies.

**RBAC Configuration:** See [Global Configuration - RBAC](/reference/chart-values/global#rbac-create) for Role and RoleBinding creation settings.

**Cloud SQL Proxy:** See [Cloud SQL Auth Proxy](/reference/chart-values/cloud-sql-proxy) for using Workload Identity with Cloud SQL.