Installation - CrewAI Platform Helm Chart

Overview

CrewAI Platform is distributed as a Helm chart via OCI registry through the Replicated platform. This guide covers installation, preflight validation, and post-installation configuration.

Before running helm install, complete the Pre-Install Checklist — it covers database creation, auth provider redirect URIs, IAM setup, and known chart gotchas that cause silent failures.

Step 1: Registry Authentication

Access your registry credentials via the CrewAI enterprise customer portal at https://enterprise.crewai.com/crewai.

Replace customer@company.com with your actual customer email and [YOUR_SECRET_TOKEN] with the token provided in the customer portal.

# Export your authentication token
export AUTH_TOKEN=[YOUR_SECRET_TOKEN]

# Log in to the Replicated registry
helm registry login registry.crewai.com \
  --username customer@company.com \
  --password $AUTH_TOKEN

Step 2: Install Required Plugins

Install the preflight and support-bundle kubectl plugins for cluster validation and diagnostics:

# Install Krew plugin manager
curl https://krew.sh | bash

# Insall preflight and support-bundle plugins
kubectl krew install preflight support-bundle

# Verify installation
kubectl preflight --version
kubectl support-bundle --version

Step 2.5: Provision Infrastructure (Terraform Option)

If you want to provision cloud infrastructure before chart installation, use one of these Terraform feature guides:

Request the Terraform files from the CrewAI Factory Engineering team before starting Terraform provisioning.

Each guide covers infrastructure provisioning and how to map Terraform outputs into your Helm values.

Step 3: Create Configuration File

Create a my-values.yaml file with your deployment configuration. See the Configuration Guide for detailed examples.

Pre-install checklist for Microsoft Entra ID users: If you are using Microsoft Entra ID as your authentication provider, configure the redirect URI in your Azure App Registration to https://<your-domain>/auth/entra_id/callback before running helm install. Authentication will fail at login if this is missing or incorrect. See the Microsoft Entra ID Guide for step-by-step instructions.

External PostgreSQL users: If you set postgres.enabled: false, you must manually create the Wharf database before running helm install. Wharf is enabled by default (wharf.enabled: true).

-- AWS RDS / Azure Database for PostgreSQL
CREATE DATABASE wharf;
GRANT ALL PRIVILEGES ON DATABASE wharf TO your_db_user;

# GCP Cloud SQL
gcloud sql databases create wharf --instance=<YOUR_INSTANCE_NAME>

See Wharf Configuration for details.

GCP Cloud SQL IAM authentication users must also run schema-level SQL grants (not just GRANT ALL PRIVILEGES ON DATABASE). The GRANT ALL PRIVILEGES ON DATABASE command alone is insufficient for Cloud SQL IAM auth users — additional schema, table, and sequence grants are required before helm install. See the GCP Integration Guide for the complete SQL.

Direct Helm Install Users

Direct Helm install users (non-KOTS/non-Replicated): You must manually set secrets.UV_DEFAULT_INDEX. In Replicated KOTS deployments this value is auto-generated from your license credentials. For direct OCI Helm installs — including Helm CLI installs and ArgoCD — no Replicated license context is available, so UV_DEFAULT_INDEX is not set automatically.Without it, crew container builds fail because the Python package registry at pypi.crewaifactory.com requires credentials. To obtain your credentials, log in to the customer portal at https://enterprise.crewai.com/crewai and navigate to your license details.

secrets:
  UV_DEFAULT_INDEX: "https://<customer-id>:<registry-password>@pypi.crewaifactory.com/simple/"

Crew automation deployments require a writable container registry. See Container Image Registry Requirements.

The following features CANNOT be pre-configured in values.yaml — they require post-installation steps and will be silently ignored if added as Helm values:

Admin users and org ownership — there is no adminUsers Helm key. Use kubectl exec commands after install. See the Post-Installation Guide.
Studio V2 — there is no studioV2.enabled Helm key. Studio V2 requires interactive UI setup plus kubectl exec commands. See the Post-Installation Guide and Studio V2 Setup Guide.

Do not set image.tag: latest in production. Using latest means upgrades are non-deterministic and the exact version running cannot be verified. Always specify an explicit version tag matching your Helm chart version. The chart’s values.yaml explicitly warns against latest. Check the Release History at https://enterprise.crewai.com/crewai/release-history for available image tags.

Minimum Production Configuration:

my-values.yaml

postgres:
  enabled: false  # Use external database

envVars:
  APPLICATION_HOST: "crewai.company.com"
  DB_HOST: "crewai-prod.cluster-xyz.us-west-2.rds.amazonaws.com"
  DB_PORT: "5432"
  DB_USER: "crewai"
  POSTGRES_DB: "crewai_plus_production"
  POSTGRES_CABLE_DB: "crewai_plus_cable_production"

  STORAGE_SERVICE: "amazon"
  AWS_REGION: "us-west-2"
  AWS_BUCKET: "crewai-prod-storage"
  CREW_IMAGE_REGISTRY_OVERRIDE: "123456789012.dkr.ecr.us-west-2.amazonaws.com"

  AUTH_PROVIDER: "entra_id"
  # Client ID and Tenant ID are non-sensitive identifiers — must be in envVars, not secrets
  ENTRA_ID_CLIENT_ID: "your-client-id"
  ENTRA_ID_TENANT_ID: "your-tenant-id"

secrets:
  DB_PASSWORD: "your-db-password"
  AWS_ACCESS_KEY_ID: "your-aws-key"
  AWS_SECRET_ACCESS_KEY: "your-aws-secret"
  ENTRA_ID_CLIENT_SECRET: "your-client-secret"

web:
  replicaCount: 2
  ingress:
    enabled: true
    className: nginx
    host: "crewai.company.com"
    nginx:
      tls:
        enabled: true
        secretName: "crewai-tls"

Never commit secrets to version control. Store my-values.yaml securely and use CI/CD secret management or external secret stores for production.

Step 3.5: Validate Your Values File

Before running preflight checks, validate that your values file is syntactically correct and free of duplicate keys:

Run yamllint before every helm install or helm upgrade. Helm silently accepts YAML files with duplicate top-level keys (e.g., two envVars: blocks or two image: blocks) and keeps only the last occurrence — the first block is dropped with no error or warning. This means database credentials, auth configuration, or image tags can vanish silently.The helm template dry-run and helm lint commands do NOT catch duplicate keys.

# Install yamllint (once)
pip install yamllint

# Check your values file before EVERY install or upgrade
yamllint my-values.yaml

A common mistake is writing envVars: twice — once for database/auth config and once for GitHub App or other feature config. Merge all envVars: keys into a single block.

Step 4: Run Preflight Checks

Validate your Kubernetes cluster meets all requirements before installation:

# Run preflight checks against your cluster
helm template oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml \
  | kubectl preflight -

Preflight checks validate cluster requirements and run environment-specific probes from inside the cluster to verify:

Kubernetes version (1.32.0+ required), cluster resources (14Gi memory, 4 CPU cores minimum), and storage classes
External PostgreSQL: Connectivity, version 15+, and database existence
S3-Compatible Storage: Write/delete permissions to the configured bucket
Crew Image Registry: Push permission (or reachability if using credential helpers like ECR/GCR)
CrewAI Hosted Services: Egress to images.crewai.com and pypi.crewaifactory.com (online installs)
APPLICATION_HOST: DNS resolution (advisory)

Address any failures before proceeding with installation. For probe failures, check the support bundle pod logs for specific error messages.CrewAI Platform supports AMD64 (x86_64) Kubernetes worker nodes. ARM64 (aarch64) worker nodes are not currently supported. See the Requirements Guide for details.

Common Preflight Issues

Kubernetes Version:

Kubernetes 1.32.0 or later is required. Upgrade your cluster if the version check fails.

Insufficient Cluster Resources:

Minimum requirements: 14Gi memory, 4 CPU cores (20Gi+ memory and 8+ cores recommended)
Review node resources: kubectl top nodes
Scale cluster if needed before installation

Missing Default Storage Class: Only required if using internal PostgreSQL.

# Set gp2 (EKS) as default storage class
kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

# Or for GKE standard storage
kubectl patch storageclass standard -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

External Database Probe Failure: If the external PostgreSQL probe fails, verify:

Database host is reachable from cluster pods on the configured port
PostgreSQL version is 15 or later
All required databases exist (check default names: crewai_plus_production, crewai_plus_cable_production, crewai_plus_oauth_production, wharf)
Database credentials are correct in your values file

Object Storage Probe Failure: If the S3-compatible storage probe fails, verify:

Bucket exists and is accessible from the cluster
Credentials have write and delete permissions
Endpoint URL is correct (if using non-AWS S3)

Registry Push Probe Failure: If the crew image registry probe fails, verify:

Registry hostname is reachable from cluster pods
Credentials have push permission to the configured repository
For ECR/ACR/GAR: Ensure credentials or credential helpers are properly configured

CrewAI Services Egress Failure: If the CrewAI hosted services probe fails (online installs only):

Verify firewall/proxy allows HTTPS egress to images.crewai.com and pypi.crewaifactory.com
Check cluster DNS can resolve these hostnames
Review network policies if using restricted egress

Step 5: Install the Chart

# Install with your configuration
helm install crewai-platform \
  oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml

# Monitor installation progress
kubectl get pods -w

After installation completes, Helm displays important information including:

Chart version and app image tag
Link to complete documentation
Configuration warnings (if any)

If you see a warning about RAILS_MASTER_KEY in the installation output, remove this configuration from your values file. The chart automatically manages this key and manual configuration is not needed.

Verify Installation

# Check all pods are running
kubectl get pods

# Check services
kubectl get svc

# View installation logs
kubectl logs -l app.kubernetes.io/name=crewai-platform --tail=50

Step 6: Complete Post-Installation Setup

After successful installation, complete the required post-installation configuration steps. See the Post-Installation Guide for detailed instructions. MANDATORY — required before any user can log in:

Initialize the internal organization (studio:install_internal_organization)
Set up default permissions (factory:setup_permissions_defaults)
Grant Admin Panel access (factory:grant_admin)
Add an owner to the organization (factory:add_owner)

Admin user setup cannot be expressed in values.yaml — it requires kubectl exec commands after the platform is running.

OPTIONAL — can be performed after the platform is accessible:

Enable Studio V2 features (requires interactive UI setup — cannot be pre-configured in values.yaml)
Enable Multi-Organization Namespace Isolation
Accessing the application via port forwarding, ingress, or LoadBalancer

Troubleshooting Installation

Pods Not Starting

# Check pod status and events
kubectl describe pod <POD_NAME>

# View pod logs
kubectl logs <POD_NAME>

# Check for image pull issues
kubectl get events --sort-by='.lastTimestamp'

Generate Support Bundle

For comprehensive diagnostics, you can generate a support bundle that collects logs, resource status, and configuration information.

Install the support-bundle Plugin

# Using Krew (recommended)
kubectl krew install support-bundle

Generate the Support Bundle

# Automatically detect support bundle specs from cluster
kubectl support-bundle --load-cluster-specs

The support bundle will be saved as a .tar.gz file that can be shared with CrewAI support for troubleshooting.

Next Steps

Post-Installation - Complete setup and access the application
Configuration Guide - Detailed production configuration patterns
Troubleshooting - Common issues and solutions

Additional Resources

Customer Portal: https://enterprise.crewai.com/crewai
Release History: https://enterprise.crewai.com/crewai/release-history

​Overview

​Step 1: Registry Authentication

​Step 2: Install Required Plugins

​Step 2.5: Provision Infrastructure (Terraform Option)

​Step 3: Create Configuration File

​Step 3.5: Validate Your Values File

​Step 4: Run Preflight Checks

​Common Preflight Issues

​Step 5: Install the Chart

​Verify Installation

​Step 6: Complete Post-Installation Setup

​Troubleshooting Installation

​Pods Not Starting

​Generate Support Bundle

​Install the support-bundle Plugin

​Generate the Support Bundle

​Next Steps

​Additional Resources

Overview

Step 1: Registry Authentication

Step 2: Install Required Plugins

Step 2.5: Provision Infrastructure (Terraform Option)

Step 3: Create Configuration File

Step 3.5: Validate Your Values File

Step 4: Run Preflight Checks

Common Preflight Issues

Step 5: Install the Chart

Verify Installation

Step 6: Complete Post-Installation Setup

Troubleshooting Installation

Pods Not Starting

Generate Support Bundle

Install the support-bundle Plugin

Generate the Support Bundle

Next Steps

Additional Resources