Skip to main content

Overview

This guide covers a full production deployment of CrewAI Platform on Azure AKS using:
  • Azure Database for PostgreSQL Flexible Server (PostgreSQL 16) for all databases including Wharf
  • Azure Blob Storage for object storage
  • Azure Container Registry (ACR) for crew container images
  • Kubernetes Gateway API on AKS App Routing for ingress, with cert-manager TLS certificates
  • Microsoft Entra ID for SSO authentication
  • Wharf for OTLP trace and span collection
  • Studio V2 for the AI-powered crew builder (post-install)
Entra ID is the natural auth choice for Azure deployments — your users are already in Azure AD, so there is no separate identity provider to configure. This is a self-contained guide. All required configuration is included here — no cross-referencing other guides for values.

Prerequisites Checklist

Complete every item before running helm install.

Azure Infrastructure

CrewAI Platform only supports AMD64 (x86_64) worker nodes. ARM64 worker nodes are not supported.

Microsoft Entra ID

The redirect URI must be configured in Azure before running helm install. Authentication will fail silently if it is missing or uses the wrong path.

Tools

  • kubectl connected to your AKS cluster
  • helm 3.10+
  • Azure CLI (az) authenticated to your subscription

Infrastructure Setup

PostgreSQL: Pre-Create All Four Databases

Create the Azure PostgreSQL Flexible Server if it does not already exist:
Create all four required databases:
Allow the PostgreSQL extensions the platform uses. Azure Database for PostgreSQL only lets you create extensions that are on this allow-list, and the value replaces any list already set:
Then connect as the admin user and grant privileges:
The chart default for POSTGRES_OAUTH_DB is oauth_db. You must override it to crewai_plus_oauth_production to match the database you created above. A mismatch causes the OAuth service to fail on startup.
When postgres.enabled: false, the Helm chart does not create databases automatically. All four databases must exist before helm install runs.
This guide connects as the server’s admin user (crewai). To connect with a dedicated role instead, give that role CREATEDB, make it the owner of the public schema in each of the four databases, and create the vector extension as the admin before the first install, then add the vector column after it. See Using a Dedicated Application Role.

Azure Blob Storage: Create Container

ACR: Create Repository and Grant AKS Access

ACR image tags must be mutable. CrewAI overwrites tags for crew versions — immutable tags cause build failures. The default ACR configuration allows mutable tags.
CREW_IMAGE_REGISTRY_OVERRIDE must be set to <YOUR_ACR_NAME>.azurecr.io/<YOUR_ORG> — without the /crewai-enterprise suffix. The platform appends /crewai-enterprise automatically. If your ACR image path is myregistry.azurecr.io/production/crewai-enterprise, set only myregistry.azurecr.io/production.

AKS Workload Identity: Managed Identity for Blob Storage

Using AKS Workload Identity is the recommended approach. It avoids storing storage account keys in Kubernetes secrets.
The federated credential subject must match the ServiceAccount that the Helm chart creates. With rbac.create: true (the chart default), the chart creates a ServiceAccount named crewai-sa in the namespace you deploy into. If you deploy to a namespace other than crewai, update the subject accordingly.

Gateway API and cert-manager

Enable the managed Gateway API and the App Routing implementation on the cluster:
This guide uses App Routing. To use Application Gateway for Containers instead, follow Option 2 in the Azure guide and change the gateway block in values.yaml accordingly.
Create the ConfigMap that makes the Gateway preserve the client IP. The platform uses the client IP for rate limiting and audit records. Pick a node port (30000-32767) that no other Service uses:
Install cert-manager with Gateway API support:
Create a ClusterIssuer for Let’s Encrypt that solves HTTP-01 challenges through the Gateway:

Entra ID: Azure Portal Setup

Step 1: App Registration

  1. Go to portal.azure.com > Microsoft Entra ID > App registrations > New registration
  2. Name: CrewAI (or your preferred name)
  3. Supported account types: Accounts in this organizational directory only
  4. Redirect URI: Web platform — https://<YOUR_DOMAIN>/auth/entra_id/callback
  5. Click Register
The redirect URI path must be exactly /auth/entra_id/callback (lowercase, underscore). Configure this before running helm install — a missing or incorrect URI causes authentication to fail with no clear error.

Step 2: Collect Credentials

From the app overview page, copy:
  • Application (client) ID → ENTRA_ID_CLIENT_ID
  • Directory (tenant) ID → ENTRA_ID_TENANT_ID

Step 3: Create Client Secret

  1. Left sidebar > Manage > Certificates & secrets
  2. New client secret — enter a description, choose expiration
  3. Copy the Value immediately — it is not shown again → ENTRA_ID_CLIENT_SECRET
  1. App registrations > select your app > API permissions > Add a permission > Microsoft Graph > Delegated permissions
  2. Under OpenId permissions, select email, openid and profile, then Add permissions
  3. Enterprise applications > select your app
  4. Security > Permissions > Grant admin consent
  5. Confirm consent for Microsoft Graph email, openid, profile and User.Read
The platform signs users in with the openid, profile and email scopes. Without admin consent for them, users are asked to consent at their first sign-in, or are blocked with an approval request when your tenant does not allow user consent.

Step 5: Create App Roles

  1. Back in App registrations > your app > Manage > App roles
  2. Create two roles:
Ensure “Do you want to enable this app role?” is checked for each.

Step 6: Assign Users

  1. Enterprise applications > your app > Manage > Properties
  2. Set Assignment required? to Yes, then Save
  3. Manage > Users and groups > Add user/group
    • Regular users: assign Member role
    • Admin users: assign Factory Admin role
For Entra ID deployments, admin access is granted exclusively through the Factory Admin App Role in Azure portal. Do NOT run factory:grant_admin — it writes to a database table that is not consulted for Entra ID users. The platform reads admin status from the JWT roles claim.

Complete values.yaml

Replace all <PLACEHOLDER> values before running helm install.
values.yaml
web.enableSslFromPuma: false is required. The chart default is true. The Gateway terminates TLS and forwards plain HTTP to backend pods. With the default true, Puma expects HTTPS connections but receives HTTP from the Gateway, and every request fails.
CREW_IMAGE_REGISTRY_OVERRIDE must not include /crewai-enterprise. The platform appends this suffix automatically. If your ACR image path is myregistry.azurecr.io/production/crewai-enterprise, set only myregistry.azurecr.io/production. Including the suffix causes push failures to a double-suffixed path.
POSTGRES_OAUTH_DB must be set explicitly. The chart default is oauth_db. If you do not override it to crewai_plus_oauth_production, the OAuth service will attempt to connect to a database that does not exist and fail on startup.
If you prefer to authenticate to Azure Blob Storage using a static storage account key instead of Workload Identity, remove the serviceAccount.annotations block and add AZURE_STORAGE_ACCESS_KEY: "<storage-account-key>" under secrets: instead. Workload Identity is strongly preferred for production deployments.

Install

Wait for all pods to reach Running:

Post-Install

Required Initialization

These commands must be completed before any user can log in. Run them in the order shown.
Do NOT run factory:grant_admin for Entra ID deployments. Admin panel access is controlled by the factory-admin App Role in Azure portal. The factory:grant_admin command writes to a database table that Entra ID authentication does not consult — it has no effect on Entra ID users and will not grant admin access.
For Entra ID, the user record is created in the database automatically on first login. The factory:add_owner command above can be run before or after the user’s first login.

Studio V2 Setup

Studio V2 cannot be configured in values.yaml. Adding studioV2.enabled or STUDIO_V2_ENABLED has no effect — Helm silently ignores unknown keys. Setup requires the platform to be fully running and accessible. Step 1: Create the LLM Connection (UI)
  1. Log in to the CrewAI web UI as an admin
  2. Navigate to Settings → LLM Connections
  3. Click New Connection
  4. Set the name to exactly studio-v2 (lowercase, no spaces)
  5. Select your LLM provider, enter the model name and API key
  6. Click Save
The connection name must be exactly studio-v2. The install commands in Step 3 look up this name specifically — a different name or capitalization causes them to fail silently.
Step 2: Set as Default Connection (UI)
  1. Navigate to Settings → Crew Studio
  2. Under Default Connection, select studio-v2
  3. Click Save
Step 3: Run Install Commands (kubectl) Run these commands in order. Each must complete successfully before running the next.
studio:agent:install will fail if the studio-v2 LLM Connection does not already exist in the UI. Complete Steps 1 and 2 before running any of these commands.

Verify

Platform Health

Gateway

Point an A record for <YOUR_DOMAIN> at that address. Then check that the routes are attached:
Check cert-manager certificate status:
If the certificate is stuck in a non-Ready state, verify that <YOUR_DOMAIN> resolves to the Gateway address and that port 80 is reachable from the internet (Let’s Encrypt requires HTTP-01 challenge access through the Gateway’s HTTP listener).

Authentication

  1. Navigate to https://<YOUR_DOMAIN>
  2. Click Sign in with Microsoft
  3. Authenticate with a user assigned a role in Azure portal
  4. Verify the user lands on the dashboard without error
If login fails with a redirect URI mismatch or authentication error, verify the redirect URI in Azure matches https://<YOUR_DOMAIN>/auth/entra_id/callback exactly.

Wharf Trace Collection

Wharf connects to the wharf database on the same PostgreSQL Flexible Server as the main application. If the pod is in CrashLoopBackOff, verify the wharf database exists and the crewai user has access.

Studio V2

Factory Health Endpoint

All components should report "status": "ok".