Skip to main content

​
Overview

This guide details all system requirements, infrastructure prerequisites, and network configurations needed to successfully deploy CrewAI Platform on Kubernetes.

​
Kubernetes Cluster Requirements

​
Version Requirements

  • Recommended Version: Kubernetes 1.32.0 or later
  • Required APIs:
    • apps/v1 (StatefulSets, Deployments)
    • v1 (Services, ConfigMaps, Secrets, PVCs)
    • batch/v1 (Jobs)
    • networking.k8s.io/v1 (Ingress, NetworkPolicy)

​
Architecture Support

  • AMD64 (x86_64): Supported
  • ARM64 (aarch64): Not currently supported
  • Node Architecture: Use AMD64 Kubernetes worker nodes for CrewAI Platform workloads

​
Resource Requirements

​
Minimum Cluster Resources

These are absolute minimum requirements.
  • Total Cluster Memory: 8Gi minimum
  • Total Cluster CPU: 4 cores minimum
  • Nodes: 1 node minimum (3+ nodes recommended for production)
  • Ephemeral Storage: 10Gi per node minimum

​
Database Requirements

​
External PostgreSQL (Required)

  • Version: PostgreSQL 16.8 or later
  • Network Connectivity: Database must be accessible from Kubernetes cluster
  • User Permissions: CREATE, DROP, and ALTER privileges
  • Extensions: Must support standard PostgreSQL extensions
  • Configuration:
    • Host and port accessible from cluster pods
    • Firewall rules allowing Kubernetes cluster IP ranges
    • SSL/TLS support recommended

​
Supported Database Services

  • AWS Aurora for PostgreSQL
  • Azure Database for PostgreSQL
  • Google Cloud SQL for PostgreSQL
  • Self-managed PostgreSQL 16+

​
Object Storage Requirements

​
External S3-Compatible Storage (Required)

  • S3-Compatible API: Full S3 API compatibility required
  • Network Connectivity: Storage service must be accessible from cluster
  • Bucket Configuration: Pre-created bucket with appropriate permissions
  • IAM/Access Keys: Valid credentials with read/write access

​
Supported Storage Services

  • AWS S3
  • Azure Blob Storage (via S3-compatible gateway)
  • Google Cloud Storage (via S3-compatible gateway)
  • Other S3-compatible services

​
Container Image Registry Requirements

​
Writable Registry for Crew Automation (Required)

CrewAI Platform builds crew automation images inside your cluster and pushes them to your configured registry after the internal build process completes.
The image registry configured by envVars.CREW_IMAGE_REGISTRY_OVERRIDE must be reachable from platform/build pods and must allow both push and pull operations.
  • Required Configuration: Set envVars.CREW_IMAGE_REGISTRY_OVERRIDE to your registry hostname
  • Permissions: Grant credentials with image push and pull access
  • Connectivity: Ensure both build pods and runtime pods can access the registry endpoint
  • Supported Registries: AWS ECR, Azure Container Registry (ACR), Google Artifact Registry (GAR), JFrog Artifactory

​
Network Requirements

​
DNS Resolution

  • Cluster DNS: CoreDNS or kube-dns must be functional
  • Service Discovery: Pods must resolve service names
  • External DNS: Access to external domains for authentication and API calls
  • DNS Configuration:
    • Cluster domain: cluster.local (default)
    • DNS policy: ClusterFirst for pods
    • Search domains properly configured

​
Network Connectivity

  • Internal: Pod-to-pod communication within cluster
  • Database: Access to external PostgreSQL (port 5432)
  • Wharf (optional): When the OTLP trace collector is enabled, pods must reach the same PostgreSQL endpoint used for your database configuration; trace data is written to a separate logical database (see Wharf OTLP Trace Collector)
  • Object Storage: Access to S3-compatible storage (typically port 443 for HTTPS)
  • Ingress: External access to web application (port 80/443)
  • Authentication: Outbound HTTPS to authentication provider APIs

​
Network Policies (Optional)

If using network policies for enhanced security:
  • CNI Plugin: Must support NetworkPolicy (Calico, Cilium, Weave, etc.)
  • Recommended Policies:
    • Database access restrictions (PostgreSQL port 5432)
    • Object storage access (HTTPS port 443)
    • Web application ingress (port 2603)
    • Inter-service communication within namespace
    • If Wharf tracing is enabled: allow application pods to reach the Wharf Service in the namespace for OTLP (in addition to PostgreSQL rules above); see Wharf OTLP Trace Collector

​
RBAC Requirements

​
Service Account Permissions

The Kubernetes service account must have permissions to:
  • Create/Read/Update/Delete: Pods, Services, ConfigMaps, Secrets
  • Create/Read/Update/Delete: StatefulSets, Deployments, Jobs
  • Create/Read/Update/Delete: PersistentVolumeClaims
  • Read: Nodes (for resource checking)
  • Create: Ingress (if ingress enabled)

​
Cluster Permissions

Some advanced features may require cluster-admin permissions or specific cluster-wide access.

​
Security Requirements

​
Secrets Management

Choose one of the following approaches:
  1. Kubernetes Secrets (default): Native Kubernetes secret storage
  2. External Secret Stores: Integration with external secret management
    • AWS Secrets Manager
    • Azure Key Vault
    • HashiCorp Vault
    • Other ESO-compatible providers

​
Authentication Provider Requirements

​
Microsoft Entra ID (Azure AD)

  • Application Registration: Client ID and Tenant ID
  • Client Secret: Valid client secret for authentication
  • Redirect URIs: Configured for your application hostname
  • API Permissions: User.Read (minimum)

​
Okta

  • Application: Web application configured in Okta
  • Client ID: Okta application client ID
  • Authorization Server: Default or custom authorization server
  • Audience: Configured API audience

​
WorkOS

  • Client ID: WorkOS application client ID
  • AuthKit Domain: Custom AuthKit domain
  • Organization Setup: Organizations configured in WorkOS dashboard

​
Tools and Client Requirements

​
Required Tools

  • Helm: Version 3.10 or later
  • kubectl: Compatible with your cluster version
  • Registry Access: Valid credentials for registry.crewai.com
  • kubectl-preflight: For pre-installation validation 
    kubectl krew install preflight
  • kubectl-support-bundle: For diagnostics and troubleshooting 
    kubectl krew install support-bundle

​
Infrastructure Provisioning Approach

You can prepare infrastructure in either of these ways:
  1. Manual cloud setup using provider documentation
  2. Terraform-based provisioning using Feature Guides
Terraform guides:

​
TLS Certificate Requirements

For production deployments with HTTPS:
  • Valid TLS Certificate: Issued by trusted CA or internal CA
  • Private Key: Corresponding private key for the certificate
  • Certificate Format: PEM-encoded certificate and key
  • Subject Alternative Names: Must include your application hostname

​
Certificate Options

  1. AWS Certificate Manager (ACM): For AWS ALB ingress
  2. cert-manager: For automatic certificate management
  3. Manual Certificates: Upload via Kubernetes secrets

​
Compliance and Governance

​
Production Checklist

Before deploying to production, ensure:
  • Infrastructure provisioned (manual setup or Terraform)
  • Kubernetes cluster version 1.32.0 or later
  • Kubernetes worker nodes use AMD64 (x86_64) architecture
  • External PostgreSQL 16+ configured and accessible
  • If Wharf tracing is enabled: separate logical PostgreSQL database for Wharf exists, naming matches chart configuration, and connectivity from the cluster is verified (see Wharf OTLP Trace Collector)
  • External S3-compatible storage configured
  • Writable image registry configured for crew automation builds
  • Enterprise authentication provider configured (Entra ID, Okta, or WorkOS)
  • Valid TLS certificate installed
  • Network policies configured (if required)

​
Validation

​
Pre-Installation Validation

Run preflight checks to validate all requirements: 
helm template oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml \
  | kubectl preflight -
Preflight checks will validate:
  • Kubernetes version compatibility
  • Cluster resource availability
  • Storage class configuration
  • Container runtime compatibility
  • DNS resolution
  • RBAC permissions
  • Database connectivity (external PostgreSQL)
  • Network policies support
Address any failures before proceeding with installation.
Wharf (optional): The chart can deploy Wharf, an OTLP trace collector for distributed tracing. It is disabled by default. If you enable it, traces must be stored in a separate logical PostgreSQL database, never the CrewAI Platform application database. For prerequisites, Helm values, GCP Cloud SQL Auth Proxy sidecar behavior, retention, and production checklists, see the Wharf OTLP Trace Collector reference.

​
Next Steps