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

# Pre-Install Checklist

> Everything that must be in place before running helm install for CrewAI Platform.

Complete every item on this checklist before running `helm install`. Most installation failures trace back to a missed prerequisite or a known chart quirk listed here.

## Cluster

* [ ] Kubernetes **1.32.0 or later** (required)
* [ ] Worker nodes are **AMD64 (x86\_64)** — ARM64 is not supported
* [ ] **AWS**: AWS Load Balancer Controller installed
* [ ] **GCP**: Workload Identity enabled on cluster and node pools; Gateway API enabled if using GKE Gateway
* [ ] **Azure**: NGINX Ingress Controller or Azure Application Gateway installed
* [ ] Helm **3.10+** installed locally
* [ ] `kubectl` configured and pointing at the correct cluster and namespace

## Databases

<Warning>
  All four databases must exist **before** `helm install`. The Helm pre-install hook runs migrations immediately — if any database is missing, the hook fails and the release is left in a broken state.
</Warning>

Create these databases on your managed PostgreSQL instance before installing:

| `envVars` key           | Database name to create        |
| ----------------------- | ------------------------------ |
| `POSTGRES_DB`           | `crewai_plus_production`       |
| `POSTGRES_CABLE_DB`     | `crewai_plus_cable_production` |
| `POSTGRES_OAUTH_DB`     | `crewai_plus_oauth_production` |
| `wharf` (Wharf service) | `wharf`                        |

```sql theme={null}
CREATE DATABASE crewai_plus_production;
CREATE DATABASE crewai_plus_cable_production;
CREATE DATABASE crewai_plus_oauth_production;
CREATE DATABASE wharf;

GRANT ALL PRIVILEGES ON DATABASE crewai_plus_production TO <db_user>;
GRANT ALL PRIVILEGES ON DATABASE crewai_plus_cable_production TO <db_user>;
GRANT ALL PRIVILEGES ON DATABASE crewai_plus_oauth_production TO <db_user>;
GRANT ALL PRIVILEGES ON DATABASE wharf TO <db_user>;
```

<Note>
  **GCP Cloud SQL IAM auth**: `GRANT ALL PRIVILEGES ON DATABASE` is not sufficient for Cloud SQL IAM-authenticated users. Schema-level grants are also required. See the [GCP Integration Guide](/cloud-providers/gcp) for the complete SQL.
</Note>

<Warning>
  **`POSTGRES_OAUTH_DB` default mismatch**: The chart default for `POSTGRES_OAUTH_DB` is `oauth_db`. If you create the database as `crewai_plus_oauth_production` (recommended) but do not override `POSTGRES_OAUTH_DB` in `envVars:`, the app connects to a non-existent database and authentication fails silently. Always set `POSTGRES_OAUTH_DB` explicitly:

  ```yaml theme={null}
  envVars:
    POSTGRES_OAUTH_DB: "crewai_plus_oauth_production"
  ```
</Warning>

## Auth Provider

* [ ] **WorkOS**: Redirect URI `https://<your-domain>/auth/workos/callback` added in WorkOS Dashboard → Applications → your app
* [ ] **Entra ID**: Redirect URI `https://<your-domain>/auth/entra_id/callback` registered in Azure App Registration (Web platform). Must be done before `helm install` — auth fails at login if missing.
* [ ] **Okta**: Sign-in redirect URI `https://<your-domain>/auth/okta/callback` configured in Okta app
* [ ] **Keycloak**: Valid redirect URI `https://<your-domain>/auth/keycloak/callback` added to the Keycloak client

## Cloud IAM / Credentials

* [ ] **AWS (Pod Identity)**: Pod Identity association created for `crewai-sa` ServiceAccount with S3 + ECR permissions
* [ ] **AWS (IRSA)**: IRSA trust policy references correct namespace and ServiceAccount name (`crewai-sa`) **and** includes `crewai-crews:default` for crew build pods (see [Post-Install: IRSA Trust Policy for Crew Build Pods](/cloud-providers/aws#post-install-irsa-trust-policy-for-crew-build-pods))
* [ ] **GCP**: GSA created with required IAM roles; Workload Identity binding created for `crewai-sa`
* [ ] **Azure**: Managed Identity created; federated credential configured for `crewai-sa` ServiceAccount

## Container Registry

* [ ] ECR / ACR / GAR repository created with path ending in `/crewai-enterprise`
* [ ] **ECR**: Image tag mutability set to **MUTABLE** (CrewAI overwrites image tags)
* [ ] `CREW_IMAGE_REGISTRY_OVERRIDE` set to the **registry prefix only** — do not include `/crewai-enterprise` (the platform appends it automatically)

## Known Chart Gotchas

These are silent failures — the chart installs without errors but the platform behaves incorrectly at runtime.

### WorkOS: API key and cookie password placement

<Warning>
  `WORKOS_API_KEY` and `WORKOS_COOKIE_PASSWORD` **must** be under `envVars:`, not `secrets:`. This is a known chart limitation: the secrets template does not render these values into pod environments. Placing them under `secrets:` causes WorkOS authentication to fail with no error message in application logs.

  ```yaml theme={null}
  # ✅ Correct
  envVars:
    WORKOS_API_KEY: "sk_live_..."
    WORKOS_COOKIE_PASSWORD: "your-32-char-string"

  # ❌ Wrong — silently ignored
  secrets:
    WORKOS_API_KEY: "sk_live_..."
  ```

  `WORKOS_COOKIE_PASSWORD` must also be **32 characters or fewer**. Generate with:

  ```bash theme={null}
  openssl rand -base64 32 | cut -c -32
  ```
</Warning>

### Entra ID: client ID and tenant ID placement

<Warning>
  `ENTRA_ID_CLIENT_ID` and `ENTRA_ID_TENANT_ID` are non-sensitive identifiers and **must** be under `envVars:`. Only `ENTRA_ID_CLIENT_SECRET` belongs under `secrets:`. The chart does not inject Entra ID identity values from the secrets section into pod environments — placing them there causes silent authentication failures.

  ```yaml theme={null}
  # ✅ Correct
  envVars:
    ENTRA_ID_CLIENT_ID: "<Application client ID>"
    ENTRA_ID_TENANT_ID: "<Directory tenant ID>"
  secrets:
    ENTRA_ID_CLIENT_SECRET: "<client secret value>"

  # ❌ Wrong
  secrets:
    ENTRA_ID_CLIENT_ID: "..."   # silently absent from pods
    ENTRA_ID_TENANT_ID: "..."   # silently absent from pods
  ```
</Warning>

### AWS ALB: SSL termination

<Warning>
  `web.enableSslFromPuma` must be set to `false` when using an AWS ALB. The chart default is `true`. ALB terminates TLS and forwards plain HTTP to backend pods; with the default `true`, Puma expects HTTPS and returns 502 Bad Gateway on every request.

  ```yaml theme={null}
  web:
    enableSslFromPuma: false  # required for ALB
  ```
</Warning>

### AWS ALB: scheme casing

The `alb.scheme` value is case-sensitive. The AWS Load Balancer Controller accepts only lowercase:

* ✅ `"internet-facing"` / `"internal"`
* ❌ `"Internet-Facing"` / `"Internal"` — silently fails to provision the ALB

### GCP: signed URL generation

<Warning>
  Set `GCS_IAM_SIGNING: "true"` in `envVars:` whenever using GCP Workload Identity for GCS. Without it, the platform attempts to sign GCS URLs using a service account key file that does not exist in Workload Identity environments. The error (`Google::Cloud::Storage::SignedUrlUnavailable`) only appears when users access uploaded files — the install and health checks succeed, making this easy to miss.

  ```yaml theme={null}
  envVars:
    GCS_IAM_SIGNING: "true"
  ```
</Warning>

### ECR: do not set `global.imageRegistry` for crew builds only

<Warning>
  `global.imageRegistry` redirects **all** platform image pulls — Redis, BuildKit, Wharf, busybox, the main application — away from `images.crewai.com`. Setting it without a complete image mirror causes `ImagePullBackOff` on every pod.

  For crew image builds only, use `CREW_IMAGE_REGISTRY_OVERRIDE` instead and leave `global.imageRegistry` unset:

  ```yaml theme={null}
  # ✅ Correct — for crew builds only
  envVars:
    CREW_IMAGE_REGISTRY_OVERRIDE: "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-org"

  # ❌ Wrong — unless you have a full platform image mirror
  global:
    imageRegistry: "123456789012.dkr.ecr.us-east-1.amazonaws.com"
  ```

  See the [Private Registry guide](/configuration/private-registry) if you need a full image mirror.
</Warning>

### Studio V2 has no Helm values

<Warning>
  Studio V2 **cannot** be configured in `values.yaml`. Setting `studioV2.enabled`, `STUDIO_V2_ENABLED`, or similar keys has no effect — Helm silently ignores unrecognized keys. Studio V2 requires post-install setup via the web UI and `kubectl exec` commands. See [Enable Studio V2](/features/studio-v2) for the complete setup sequence.
</Warning>

### Admin users have no Helm key

There is no `adminUsers` key in the chart. Admin roles are granted after install via:

```bash theme={null}
kubectl exec -it deploy/crewai-web -- bin/rails 'factory:grant_admin[admin@company.com]'
```

**Exception**: Entra ID users receive admin access by assigning the `factory-admin` App Role in the Azure portal. `factory:grant_admin` has no effect for Entra ID users.

### ArgoCD / GitOps: auto-generated secrets

The chart auto-generates several secrets (`SECRET_KEY_BASE`, `ENCRYPTION_KEY`, `OAUTH_DB_ENCRYPTION_KEY`, `FACTORY_DEBUG_TOKEN`, `WHARF_JWT_SECRET`, `CUBE_JWT_SECRET`, `DEPLOYMENT_INSTANCE_JWT_SECRET`) using the Helm `lookup` function, which does not work in GitOps pipelines. If deploying via ArgoCD or Flux, set these explicitly in your values. Generate with:

```bash theme={null}
openssl rand -hex 32
```

See the [ArgoCD Deployment Guide](/configuration/argocd) for the complete list and configuration.