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)
Prerequisites Checklist
Complete every item before runninghelm install.
Azure Infrastructure
Microsoft Entra ID
Tools
kubectlconnected to your AKS clusterhelm3.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: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
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.Entra ID: Azure Portal Setup
Step 1: App Registration
- Go to portal.azure.com > Microsoft Entra ID > App registrations > New registration
- Name:
CrewAI(or your preferred name) - Supported account types: Accounts in this organizational directory only
- Redirect URI: Web platform —
https://<YOUR_DOMAIN>/auth/entra_id/callback - Click Register
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
- Left sidebar > Manage > Certificates & secrets
- New client secret — enter a description, choose expiration
- Copy the Value immediately — it is not shown again
→
ENTRA_ID_CLIENT_SECRET
Step 4: Grant Admin Consent
- App registrations > select your app > API permissions > Add a permission > Microsoft Graph > Delegated permissions
- Under OpenId permissions, select email, openid and profile, then Add permissions
- Enterprise applications > select your app
- Security > Permissions > Grant admin consent
- 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
- Back in App registrations > your app > Manage > App roles
- Create two roles:
Ensure “Do you want to enable this app role?” is checked for each.
Step 6: Assign Users
- Enterprise applications > your app > Manage > Properties
- Set Assignment required? to Yes, then Save
- Manage > Users and groups > Add user/group
- Regular users: assign Member role
- Admin users: assign Factory Admin role
Complete values.yaml
Replace all<PLACEHOLDER> values before running helm install.
values.yaml
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
Running:
Post-Install
Required Initialization
These commands must be completed before any user can log in. Run them in the order shown.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 invalues.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)
- Log in to the CrewAI web UI as an admin
- Navigate to Settings → LLM Connections
- Click New Connection
- Set the name to exactly
studio-v2(lowercase, no spaces) - Select your LLM provider, enter the model name and API key
- Click Save
- Navigate to Settings → Crew Studio
- Under Default Connection, select
studio-v2 - Click Save
Verify
Platform Health
Gateway
A record for <YOUR_DOMAIN> at that address. Then check that the routes are attached:
<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
- Navigate to
https://<YOUR_DOMAIN> - Click Sign in with Microsoft
- Authenticate with a user assigned a role in Azure portal
- Verify the user lands on the dashboard without error
https://<YOUR_DOMAIN>/auth/entra_id/callback exactly.
Wharf Trace Collection
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
"status": "ok".