CSI Secret Store Configuration - CrewAI Platform Helm Chart

The csiSecret configuration enables secret management via the Secrets Store CSI Driver for clusters where External Secrets Operator cannot be installed.

Mutually Exclusive with External Secrets: The CSI Secret Store mode (csiSecret.enabled: true) and External Secrets Operator mode (externalSecret.enabled: true) cannot be enabled simultaneously. Choose one secret management strategy for your deployment.

Overview

The CSI Secret Store mode provides an alternative to External Secrets Operator for clusters with the following requirements:

Secrets Store CSI Driver is already installed
External Secrets Operator cannot be installed due to cluster policies
AWS Secrets Manager is used as the secret backend

How It Works:

A SecretProviderClass resource defines which secrets to fetch from AWS Secrets Manager
A csi-syncer deployment mounts the CSI volume to materialize Kubernetes Secrets
Workloads consume the standard crewai-platform-secrets Secret (identical to inline or ESO modes)

Prerequisites:

secrets-store-csi-driver installed with syncSecret.enabled=true
secrets-store-csi-driver-provider-aws installed
Secrets pre-populated in AWS Secrets Manager

Basic Configuration

boolean

default:"false"

Enable Secrets Store CSI Driver mode for secret management.When to Use:

External Secrets Operator cannot be installed in your cluster
Secrets Store CSI Driver is already available
AWS Secrets Manager is your secret backend

Validation:

Fails if externalSecret.enabled is also true (mutually exclusive)
Fails if csiSecret.provider is not "aws" (only AWS is currently supported)
Fails if web.tls.autoGenerate is true (auto-generated TLS not supported in CSI mode)

Example:

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"

string

default:"aws"

Secret store provider type.Valid Values:

"aws" - AWS Secrets Manager (only supported provider)

Note: The chart validates this value and fails template rendering if set to anything other than "aws". Support for additional providers may be added in future releases.

Secret Paths

string

required

AWS Secrets Manager secret name or ARN containing platform secrets.Required: Yes (when csiSecret.enabled: true)Format: Secret name (e.g., "crewai/platform/prod") or full ARNSecret Structure: The secret must be a JSON object with flat string key-value pairs. Required keys depend on your configuration (see Backend Key Reference).Example Secret Content:

{
  "secret_key_base": "your-secret-key-base",
  "encryption_key": "your-encryption-key",
  "github_token": "ghp_...",
  "internal_api_key": "your-internal-api-key"
}

string

required

AWS Secrets Manager secret name or ARN containing the database password.Required: Yes (when csiSecret.enabled: true)Format: Secret name or full ARNSecret Structure: JSON object with a password property:

{
  "password": "your-database-password"
}

Separate Secret: Database credentials are kept in a separate secret for easier credential rotation without touching platform secrets.

string

default:""

AWS Secrets Manager secret name or ARN containing OAuth service secrets.Default Behavior: When empty, defaults to csiSecret.secretPath (OAuth secrets stored in the same secret as platform secrets).When to Use a Separate Secret:

Different rotation schedules for OAuth vs platform secrets
Different IAM permission boundaries
Organizational secret separation requirements

Secret Structure: JSON object with OAuth-specific keys:

{
  "oauth_cookie_secret": "your-oauth-cookie-secret",
  "oauth_db_encryption_key": "your-oauth-db-encryption-key",
  "oauth_internal_api_key": "your-oauth-internal-api-key"
}

Example (separate OAuth secret):

csiSecret:
  enabled: true
  secretPath: "crewai/platform/prod"
  oauthSecretPath: "crewai/platform/prod/oauth"

Property Mapping

object

default:"{}"

Override JSON property names for specific secrets in AWS Secrets Manager.Default Behavior: When not specified, the chart uses lowercase versions of Kubernetes Secret keys. For example, SECRET_KEY_BASE maps to the secret_key_base JSON property.When to Use:

Your AWS Secrets Manager secret uses non-standard property names
Migrating from a different secret structure
Adding custom secrets not in the chart’s default set

Behavior:

Listed keys override the default property name
Listing a key that isn’t in the chart’s default set adds it to the SecretProviderClass request

Example (custom property names):

csiSecret:
  propertyMap:
    SECRET_KEY_BASE: "rails_secret_key"
    GITHUB_TOKEN: "gh_pat"
    CUSTOM_API_KEY: "custom_api_key"  # Adds a new secret to request

Default Mappings (automatically applied):

Kubernetes Secret Key	Default JSON Property
`SECRET_KEY_BASE`	`secret_key_base`
`ENCRYPTION_KEY`	`encryption_key`
`GITHUB_TOKEN`	`github_token`
`SSL_PRIVATE_KEY`	`platform_ssl_key`
`SSL_CERTIFICATE`	`platform_ssl_cert`
`REGISTRY_HTTP_SECRET`	`registry_http_secret`

See the Backend Key Reference for the complete list.

object

default:"{}"

Override JSON property names for OAuth service secrets in AWS Secrets Manager.Default Behavior: When not specified, the chart uses lowercase versions of Kubernetes Secret keys for OAuth secrets. For example, OAUTH_COOKIE_SECRET maps to the oauth_cookie_secret JSON property.When to Use:

Your OAuth secret uses non-standard property names
A single product integration uses a different client than its provider default
Migrating from External Secrets Operator with existing property mappings

You do not need it to add provider credentials. Every provider configured under oauth.secrets is requested automatically, and its base client ID and secret fan out across that provider’s product integrations.Behavior:

Listed keys override the default property name for OAuth secrets
An entry wins over the fan-out for that one key; every other key keeps inheriting the provider default

Example (product-specific credential):

csiSecret:
  oauthPropertyMap:
    GOOGLE_GMAIL_CLIENT_ID: "gmail_client_id"
    GOOGLE_GMAIL_CLIENT_SECRET: "gmail_client_secret"

Example (custom OAuth property names):

csiSecret:
  oauthPropertyMap:
    OAUTH_COOKIE_SECRET: "custom_oauth_cookie_secret"
    OAUTH_DB_ENCRYPTION_KEY: "custom_oauth_db_key"

Default OAuth Mappings (automatically applied when oauth.enabled: true):

Kubernetes Secret Key	Default JSON Property
`OAUTH_COOKIE_SECRET`	`oauth_cookie_secret`
`OAUTH_DB_ENCRYPTION_KEY`	`oauth_db_encryption_key`
`OAUTH_INTERNAL_API_KEY`	`oauth_internal_api_key`

Common OAuth Provider Keys:Requested automatically when the matching oauth.secrets.* block is set:

Google: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_DRIVE_PICKER_KEY, GOOGLE_GMAIL_SERVICE_ACCOUNT_JSON
Microsoft: MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID
HubSpot: HUBSPOT_CLIENT_ID, HUBSPOT_CLIENT_SECRET
Notion: NOTION_CLIENT_ID, NOTION_CLIENT_SECRET
Salesforce: SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET

Credential Fanout: When you configure base provider credentials (e.g., GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET), the chart automatically expands them to all product integrations without requiring separate backend properties:

Google → Fans out to: Calendar, Gmail, Drive, Contacts, Sheets, Slides, Docs (16 total Secret keys from 2 backend properties)
Microsoft → Fans out to: Outlook, OneDrive, SharePoint, Teams, Word, Excel (21 total Secret keys from 3 backend properties)

This means you only need to store 2-3 properties per provider in AWS Secrets Manager instead of storing credentials for each product separately. The chart handles the expansion automatically when you configure oauth.secrets.google or oauth.secrets.microsoft with clientId and clientSecret.Override Individual Products: If you need different credentials for a specific product (e.g., separate Google Calendar credentials), add that specific key to oauthPropertyMap (e.g., GOOGLE_CAL_CLIENT_ID: "google_calendar_client_id") and it will use its own backend property instead of the shared fanout.

Separation from propertyMap: The oauthPropertyMap field was introduced to handle OAuth-specific secrets separately from platform secrets. This matches the External Secrets Operator pattern and ensures provider credentials route to the correct secret when migrating between secret management modes.

AWS Configuration

string

required

AWS region where secrets are stored.Required: Yes (when csiSecret.enabled: true)Example: "us-west-2"IAM Permissions: The pod’s IAM role must have secretsmanager:GetSecretValue permission for secrets in this region.

string

default:""

Optional second AWS region for the CSI provider’s failover lookup.When to Use:

Multi-region disaster recovery setup
AWS Secrets Manager replication is configured
High availability requirements

Behavior: If the primary region lookup fails, the CSI provider attempts to fetch secrets from this region.Example:

csiSecret:
  aws:
    region: "us-west-2"
    failoverRegion: "us-east-1"

string

default:""

IAM role ARN for IRSA (IAM Roles for Service Accounts) authentication.When to Use:

EKS clusters using IRSA for pod-level IAM permissions
Fine-grained secret access control per namespace

Behavior: When set, this role ARN is annotated onto the csi-syncer ServiceAccount with the eks.amazonaws.com/role-arn annotation.Leave Empty When:

Node IAM role already grants secretsmanager:GetSecretValue
Using EKS Pod Identity (newer AWS authentication method)
Using static credentials

Example:

csiSecret:
  aws:
    roleArn: "arn:aws:iam::123456789012:role/crewai-csi-secrets-reader"

IAM Policy Example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": [
        "arn:aws:secretsmanager:us-west-2:123456789012:secret:crewai/platform/*"
      ]
    }
  ]
}

Additional Options

boolean

default:"false"

Pull AWS credentials from the platform secret for use by application workloads.When to Use:

Application needs AWS API access (S3, SQS, etc.)
AWS credentials should be managed alongside other secrets

Behavior: When true, adds AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to the list of secrets fetched from csiSecret.secretPath.JSON Properties Expected:

aws_access_key_id (or override via propertyMap)
aws_secret_access_key (or override via propertyMap)

Example:

csiSecret:
  includes_aws_credentials: true

Alternative: For production environments, prefer IAM roles (node role, IRSA, or Pod Identity) over static credentials.

Sync Behavior

Automatic Secret Synchronization:When CSI Secret Store mode is enabled, the chart automatically handles secret synchronization via a two-phase hook mechanism:

CSI Syncer Deployment (hook weight: -40) - Starts a deployment that mounts the CSI volume to materialize the Kubernetes Secret
Gate Pod (hook weight: -25) - A validation pod that waits for secrets to be available before Helm proceeds

This synchronization is always enabled and ensures all required secrets are available before workloads start. Unlike External Secrets Operator mode (which has a configurable externalSecret.waitForSync), the CSI sync mechanism is built into the deployment pattern and cannot be disabled.Why This Matters:

Prevents pod CrashLoops due to missing secrets during deployment
Helm waits for the gate Pod to succeed before proceeding with migration jobs and workloads
Failed secret mounts are detected early with clear error messages from AWS

If secret mounting fails, the gate Pod will fail with the AWS error message, and Helm will halt the deployment before any workloads are affected.

Backend Key Reference

The following table lists all secrets that may be required in your AWS Secrets Manager backend, depending on your configuration. Each secret is fetched from the appropriate path (secretPath, databaseSecretPath, or oauthSecretPath).

Core Platform Secrets

Fetched from csiSecret.secretPath:

Kubernetes Key	Default JSON Property	Required	Description
`SECRET_KEY_BASE`	`secret_key_base`	Always	Rails secret for session signing
`ENCRYPTION_KEY`	`encryption_key`	Always	General encryption key
`ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`	`active_record_encryption_primary_key`	Always	Rails ActiveRecord encryption
`ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY`	`active_record_encryption_deterministic_key`	Always	Rails deterministic encryption
`ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT`	`active_record_encryption_key_derivation_salt`	Always	Rails key derivation salt
`CREWAI_PLUS_INTERNAL_API_KEY`	`internal_api_key`	Always	Internal API authentication
`GITHUB_TOKEN`	`github_token`	Always	GitHub repository access
`GITHUB_CREW_STUDIO_TOKEN`	`github_crew_studio_token`	Always	Crew Studio integration
`REGISTRY_HTTP_SECRET`	`registry_http_secret`	Always	Internal registry auth
`FACTORY_DEBUG_TOKEN`	`factory_debug_token`	Always	Debug access token
`DEPLOYMENT_INSTANCE_JWT_SECRET`	`deployment_instance_jwt_secret`	Always	Instance JWT signing
`OIDC_PRIVATE_KEY`	`oidc_private_key`	Always	OIDC authentication key
`OIDC_KEY_ID`	`oidc_key_id`	Always	OIDC key identifier

Database Secrets

Fetched from csiSecret.databaseSecretPath:

Kubernetes Key	JSON Property	Required	Description
`DB_PASSWORD`	`password`	Always	Database password

Optional Platform Secrets

Fetched from csiSecret.secretPath when conditions are met:

Kubernetes Key	Default JSON Property	Condition	Description
`SSL_PRIVATE_KEY`	`platform_ssl_key`	Application-level TLS	Platform SSL private key
`SSL_CERTIFICATE`	`platform_ssl_cert`	Application-level TLS	Platform SSL certificate
`CREW_SSL_CERT`	`crew_ssl_cert`	Application-level TLS	Crew SSL certificate
`CREW_SSL_KEY`	`crew_ssl_key`	Application-level TLS	Crew SSL private key
`AWS_ACCESS_KEY_ID`	`aws_access_key_id`	`includes_aws_credentials: true`	AWS access key
`AWS_SECRET_ACCESS_KEY`	`aws_secret_access_key`	`includes_aws_credentials: true`	AWS secret key

GitHub App Secrets

Fetched from csiSecret.secretPath when envVars.GITHUB_APP_ID is set:

Kubernetes Key	Default JSON Property	Description
`GITHUB_CLIENT_SECRET`	`github_client_secret`	GitHub App OAuth client secret
`GITHUB_WEBHOOK_SECRET_TOKEN`	`github_webhook_secret`	GitHub webhook validation token
`GITHUB_APP_PRIVATE_KEY`	`github_app_private_key`	GitHub App authentication key

OAuth Provider Secrets

Fetched from csiSecret.oauthSecretPath (or csiSecret.secretPath if not specified) when envVars.AUTH_PROVIDER is configured:

Kubernetes Key	Default JSON Property	Auth Provider	Description
`ENTRA_ID_CLIENT_SECRET`	`entra_client_secret`	`entra_id`	Microsoft Entra ID secret
`AUTH0_CLIENT_SECRET`	`auth0_client_secret`	`auth0`	Auth0 client secret
`OKTA_CLIENT_SECRET`	`okta_client_secret`	`okta`	Okta client secret
`KEYCLOAK_CLIENT_SECRET`	`keycloak_client_secret`	`keycloak`	Keycloak client secret
`WORKOS_API_KEY`	`workos_api_key`	`workos`	WorkOS API key

OAuth Service Secrets

Fetched from csiSecret.oauthSecretPath (or csiSecret.secretPath if not specified) when oauth.enabled: true:

Kubernetes Key	Default JSON Property	Description
`OAUTH_COOKIE_SECRET`	`oauth_cookie_secret`	OAuth service cookie encryption
`OAUTH_DB_ENCRYPTION_KEY`	`oauth_db_encryption_key`	OAuth database encryption
`OAUTH_INTERNAL_API_KEY`	`oauth_internal_api_key`	OAuth internal API authentication

OAuth Provider Credentials

Fetched from csiSecret.oauthSecretPath (or csiSecret.secretPath if not specified) when explicitly added via csiSecret.oauthPropertyMap:

Not Requested by Default: OAuth provider credentials for end-user integrations must be explicitly added to csiSecret.oauthPropertyMap. The chart does not request these by default.

Kubernetes Key	Default JSON Property	OAuth Provider	Description
`GOOGLE_CLIENT_ID`	`google_client_id`	Google OAuth	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	`google_client_secret`	Google OAuth	Google OAuth client secret
`MICROSOFT_CLIENT_ID`	`microsoft_client_id`	Microsoft OAuth	Microsoft OAuth client ID
`MICROSOFT_CLIENT_SECRET`	`microsoft_client_secret`	Microsoft OAuth	Microsoft OAuth client secret
`MICROSOFT_TENANT_ID`	`microsoft_tenant_id`	Microsoft OAuth	Microsoft tenant ID
`HUBSPOT_CLIENT_ID`	`hubspot_client_id`	HubSpot OAuth	HubSpot OAuth client ID
`HUBSPOT_CLIENT_SECRET`	`hubspot_client_secret`	HubSpot OAuth	HubSpot OAuth client secret
`NOTION_CLIENT_ID`	`notion_client_id`	Notion OAuth	Notion OAuth client ID
`NOTION_CLIENT_SECRET`	`notion_client_secret`	Notion OAuth	Notion OAuth client secret
`SALESFORCE_CLIENT_ID`	`salesforce_client_id`	Salesforce OAuth	Salesforce OAuth client ID
`SALESFORCE_CLIENT_SECRET`	`salesforce_client_secret`	Salesforce OAuth	Salesforce OAuth client secret

Example (adding Google OAuth credentials):

csiSecret:
  oauthPropertyMap:
    GOOGLE_CLIENT_ID: "google_client_id"
    GOOGLE_CLIENT_SECRET: "google_client_secret"

See the OAuth Provider Credentials configuration example for detailed setup instructions.

Optional Service Secrets

Fetched from csiSecret.secretPath when services are enabled:

Kubernetes Key	Default JSON Property	Condition	Description
`WHARF_JWT_SECRET`	`wharf_jwt_secret`	`wharf.enabled: true`	Wharf service JWT secret
`WHARF_POSTGRES_URL`	`wharf_postgres_url`	`wharf.enabled: true`	Complete Wharf database URL
`CUBE_JWT_SECRET`	`cube_jwt_secret`	`cube.enabled: true`	Cube.js JWT secret

TLS Auto-Generation Not Supported: The chart’s web.tls.autoGenerate feature is not compatible with CSI Secret Store mode. If you need application-level TLS, you must either:

Store SSL certificates in AWS Secrets Manager at csiSecret.secretPath (properties: platform_ssl_key, platform_ssl_cert, crew_ssl_cert, crew_ssl_key)
Disable application-level TLS and terminate TLS externally (load balancer or ingress controller)

Example Configurations

Minimal Configuration

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"
  aws:
    region: "us-west-2"

With IRSA Authentication

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"
  aws:
    region: "us-west-2"
    roleArn: "arn:aws:iam::123456789012:role/crewai-csi-secrets"

Separate OAuth Secrets

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"
  oauthSecretPath: "crewai/platform/prod/oauth"
  aws:
    region: "us-west-2"

oauth:
  enabled: true

With OAuth Provider Credentials

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"
  oauthSecretPath: "crewai/platform/prod/oauth"
  oauthPropertyMap:
    GOOGLE_CLIENT_ID: "google_client_id"
    GOOGLE_CLIENT_SECRET: "google_client_secret"
    MICROSOFT_CLIENT_ID: "microsoft_client_id"
    MICROSOFT_CLIENT_SECRET: "microsoft_client_secret"
  aws:
    region: "us-west-2"

oauth:
  enabled: true
  secrets:
    google:
      enabled: true
    microsoft:
      enabled: true

With Custom Property Names

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"
  propertyMap:
    SECRET_KEY_BASE: "rails_secret_key"
    GITHUB_TOKEN: "github_pat"
  aws:
    region: "us-west-2"

Multi-Region with Failover

csiSecret:
  enabled: true
  provider: aws
  secretPath: "crewai/platform/prod"
  databaseSecretPath: "crewai/platform/prod/db"
  aws:
    region: "us-west-2"
    failoverRegion: "us-east-1"
    roleArn: "arn:aws:iam::123456789012:role/crewai-csi-secrets"

CSI Secret Store Setup Guide - Step-by-step deployment instructions
External Secrets Operator - Alternative secret management approach
Secrets Configuration - Direct secret values (inline mode)

​Overview

​Basic Configuration

​Secret Paths

​Property Mapping

​AWS Configuration

​Additional Options

​Sync Behavior

​Backend Key Reference

​Core Platform Secrets

​Database Secrets

​Optional Platform Secrets

​GitHub App Secrets

​OAuth Provider Secrets

​OAuth Service Secrets

​OAuth Provider Credentials

​Optional Service Secrets

​Example Configurations

​Minimal Configuration

​With IRSA Authentication

​Separate OAuth Secrets

​With OAuth Provider Credentials

​With Custom Property Names

​Multi-Region with Failover

​Related Documentation

Overview

Basic Configuration

Secret Paths

Property Mapping

AWS Configuration

Additional Options

Sync Behavior

Backend Key Reference

Core Platform Secrets

Database Secrets

Optional Platform Secrets

GitHub App Secrets

OAuth Provider Secrets

OAuth Service Secrets

OAuth Provider Credentials

Optional Service Secrets

Example Configurations

Minimal Configuration

With IRSA Authentication

Separate OAuth Secrets

With OAuth Provider Credentials

With Custom Property Names

Multi-Region with Failover

Related Documentation