Migrate from BuildKit to No-Build

CrewAI Platform supports two crew deployment providers, selected with envVars.PROVIDER:

BUILDKIT_KUBERNETES (legacy): builds a container image for each crew inside the cluster with BuildKit and pushes it to the registry configured in envVars.CREW_IMAGE_REGISTRY_OVERRIDE.
KUBERNETES_V3 (no-build, default): runs every crew on a shared, pre-scanned runtime image. The crew’s source code and Python dependencies are installed when the crew pod starts. BuildKit is not used.

This guide is for installations that already run crews on BuildKit and want to move them to the no-build provider. New installations use the no-build provider by default and do not need this guide.

Chart versions after 0.11.0 default envVars.PROVIDER to KUBERNETES_V3. If your values file does not set envVars.PROVIDER, upgrading the chart switches the provider. Use chart version 0.12.0 or later for the no-build provider, and follow Step 1 to control when the switch happens.

How the Migration Works

Changing the provider only affects future deploys. Crews that are already running keep running on BuildKit, unchanged, until they are redeployed.
Each crew moves to no-build on its next redeploy. Any action that redeploys the crew counts: Redeploy, or saving the crew’s environment variables or settings.
The platform checks the no-build prerequisites before touching the BuildKit crew. It verifies that the runtime image registry resolves, that the image pull secret and platform secret exist in the crews namespace, that the Python package index is configured, and that namespace isolation is disabled. If any check fails, the deploy fails and the BuildKit crew keeps running.
If the checks pass, the platform removes the crew’s BuildKit resources and then starts the crew on no-build. The crew is unavailable between these two steps, until its new pods finish installing dependencies and become ready.
The move is one-way for each crew. Setting envVars.PROVIDER back to BUILDKIT_KUBERNETES only affects crews that have not been migrated yet and crews created afterwards. Migrated crews stay on no-build.

What Changes for a Crew

	BuildKit (`BUILDKIT_KUBERNETES`)	No-build (`KUBERNETES_V3`)
Container image	Built per crew, pushed to `CREW_IMAGE_REGISTRY_OVERRIDE`	Shared runtime image from `envVars.AUTOMATION_IMAGE_REFERENCE`
Python dependencies	Installed once, at build time	Installed every time a crew pod starts
Network access at pod start	Image registry only	Image registry and the Python package indexes
ServiceAccount in the crews namespace	`default`	`automation-sa`
Kubernetes resource names	`org-<org-id>-crew-<crew-id>-<slug>-web`, `-worker`, `-redis`	`org-<org-id>-autom-<crew-id>`, `-worker`, `-redis`
BuildKit service	Required	Not used

The commands in this guide use crewai-crews, the default crews namespace. Replace it with your crewNamespace value if you changed it.

Before You Begin

Check each item below before switching the provider. Most migration failures come from one of them.

Namespace Isolation Must Be Disabled

The no-build provider does not support rbac.namespaceIsolation. The chart preflight blocks the combination, and the platform refuses to migrate a crew while isolation is enabled. If you need namespace isolation, stay on BUILDKIT_KUBERNETES. See Preflight Check Failures.

The Python Package Index Must Be Configured

Crew pods install packages from the index in secrets.UV_DEFAULT_INDEX.

Replicated KOTS installs: generated automatically from your license.
Direct Helm CLI and ArgoCD installs: set secrets.UV_DEFAULT_INDEX explicitly.
Air-gapped installs: point it at your mirror. See Private PyPI Registry Mirror.

Crew Pods Need Network Access to the Package Indexes

With BuildKit, dependencies were downloaded once, during the build. With no-build, every crew pod downloads them when it starts, including after restarts and rescheduling. Firewalls, egress gateways, and network policies that apply to the crews namespace must allow HTTPS to:

the host in UV_DEFAULT_INDEX (pypi.crewaifactory.com by default)
pypi.org and files.pythonhosted.org, for public packages
any additional indexes or Git hosts your crews declare in their pyproject.toml

See the Network Allowlist.

Dependency installation in crew pods does not use HTTP_PROXY / HTTPS_PROXY settings. If your cluster reaches the internet only through an HTTP proxy, provide a package mirror that crew pods can reach directly and set it as UV_DEFAULT_INDEX (see Private PyPI Registry Mirror).

The Runtime Image Must Be Pullable

Crew pods run the image in envVars.AUTOMATION_IMAGE_REFERENCE. By default it is pulled from images.crewai.com, under the proxy/crewai/no-build/ path.

Mirrored registries: set envVars.AUTOMATION_BASE_IMAGE_REGISTRY_OVERRIDE and envVars.AUTOMATION_BASE_IMAGE_REPOSITORY_PREFIX. If nodes pull the image with cloud IAM instead of the Replicated pull secret, also set envVars.REPLICATED_DISABLED to "true".
Pinned versions: if you pin AUTOMATION_IMAGE_REFERENCE, use version 0.12.0 or later, or remove the pin so the chart default applies. Older versions fail the Automation Image Version Floor preflight.

Keep `CREW_IMAGE_REGISTRY_OVERRIDE` Set

The chart still requires envVars.CREW_IMAGE_REGISTRY_OVERRIDE with the no-build provider. Do not remove it from your values file.

Crews That Call Cloud APIs With Workload Identity

On BuildKit, crew pods run as the default ServiceAccount of the crews namespace. On no-build, they run as automation-sa. If your crews call cloud APIs (for example Amazon Bedrock or S3) using an identity attached to the crews namespace default ServiceAccount, they lose those credentials when they are migrated.

AWS (IRSA): configure automation-sa before migrating these crews. See Crew Runtime AWS Access (No-Build Provider).
GCP Workload Identity, Azure Workload Identity, or EKS Pod Identity: contact CrewAI Support before migrating these crews.

Crews that receive credentials through their own environment variables in the platform are not affected.

Git Projects Must Package to Less Than 50 MB

On no-build, the platform packages each crew’s source into an archive that the crew pod downloads at startup. The archive must be smaller than 50 MB, or the crew fails to start with a validation error that mentions source_code_url. Hidden files and directories (such as .git) are not included. To estimate the size, run this from the root of the crew repository:

zip -qr /tmp/crew-size-check.zip . -x '.*' '*/.*' && ls -lh /tmp/crew-size-check.zip

If the archive is too large, remove committed virtual environments, node_modules, build artifacts, and large binary assets from the repository.

Crews With Large Dependency Trees

Because dependencies are installed every time a crew pod starts, crews with very large dependency trees (for example PyTorch with CUDA libraries) take longer to start, and can exceed the startup time limit, in which case the deploy fails. Migrate one of these crews as a test before you migrate the rest.

Step 1: Upgrade the Chart and Stay on BuildKit

Upgrade to a chart version that supports the no-build provider while keeping BuildKit as the active provider. This separates the chart upgrade from the provider switch.

Helm CLI / ArgoCD
KOTS Admin Console

Set the provider explicitly in your values file:

envVars:
  PROVIDER: "BUILDKIT_KUBERNETES"

buildkit:
  enabled: true

Then upgrade:

helm upgrade crewai-platform \
  oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml

Confirm the active provider:

kubectl exec deploy/crewai-web -- printenv PROVIDER
# BUILDKIT_KUBERNETES

Replace deploy/crewai-web with your web deployment name if you changed global.fullnameOverride, and add -n <platform-namespace> if the platform does not run in your current namespace.

Step 2: Prepare Cloud Credentials for Crews

If any crew calls cloud APIs using workload identity, complete the setup in Crews That Call Cloud APIs With Workload Identity now. Otherwise, skip this step.

Step 3: Switch the Provider to No-Build

Keep buildkit.enabled: true for now. Crews that have not been migrated yet still need BuildKit if you roll them back.

Helm CLI / ArgoCD
KOTS Admin Console

envVars:
  PROVIDER: "KUBERNETES_V3"

buildkit:
  enabled: true

helm upgrade crewai-platform \
  oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml

Confirm that printenv PROVIDER now returns KUBERNETES_V3. Running crews are not affected by this step.

Step 4: Migrate One Crew and Verify

Start with a simple crew that does not call cloud APIs and has a small dependency tree.

Open the crew in the platform and click Redeploy.
Wait for the deploy to finish. Crew pods install dependencies when they start, so the crew becomes ready only after that installation completes.

Check the crew’s Kubernetes resources. Replace <CREW_ID> with the crew’s numeric ID, which appears in the crew’s URL in the platform:

# Only org-<org-id>-autom-<CREW_ID> resources should remain for this crew
kubectl get deploy -n crewai-crews -o name | grep -E -- "-(crew|autom)-<CREW_ID>(-|$)"

# The crew's pods run as automation-sa
kubectl get pods -n crewai-crews \
  -o custom-columns=NAME:.metadata.name,SERVICE_ACCOUNT:.spec.serviceAccountName \
  | grep -- "-autom-<CREW_ID>"

Run the crew end to end and confirm the result, including any calls to external services.

If the deploy fails a prerequisite check, the BuildKit crew keeps running. Fix the reported issue and redeploy.

Step 5: Migrate the Remaining Crews

Redeploy the remaining crews one at a time or in small batches.

Each crew is briefly unavailable while it is migrated. Avoid the times when its schedules or triggers run.
Migrate crews that call cloud APIs only after Step 2.
Migrate crews with large dependency trees or large repositories separately, and verify each one.

List the crews that are still on BuildKit:

kubectl get deploy -n crewai-crews -o name | grep -E "^deployment.apps/org-[0-9]+-crew-"

Step 6: Disable BuildKit (Optional)

When the command above returns nothing, no crew depends on BuildKit any more. You can disable the BuildKit service to free cluster resources:

buildkit:
  enabled: false

Then run helm upgrade (or deploy from the Admin Console) again. Keep envVars.CREW_IMAGE_REGISTRY_OVERRIDE set, because the chart still requires it. Crew images that BuildKit pushed to your registry are no longer used once every crew is migrated. You can remove them according to your registry’s retention practices.

Rolling Back

Crews not yet migrated: set envVars.PROVIDER back to BUILDKIT_KUBERNETES (or select BuildKit (legacy) in the Admin Console) with buildkit.enabled: true. These crews, and crews created afterwards, deploy with BuildKit again.
Crews already migrated: they stay on no-build, even after the provider setting is changed back. Contact CrewAI Support if you need to move a migrated crew back to BuildKit.

Troubleshooting

Symptom	Likely cause	What to do
The redeploy fails and the BuildKit crew is still running	A no-build prerequisite check failed	See Before You Begin and Preflight Check Failures, fix the issue, and redeploy
Crew pods restart during startup; logs show package download timeouts or retries	Crew pods cannot reach the package indexes	See Crew Pods Need Network Access to the Package Indexes
The crew fails to start with a validation error that mentions `source_code_url`	The project archive is 50 MB or larger	See Git Projects Must Package to Less Than 50 MB
AWS SDK calls in the crew fail with `Unable to locate credentials`	The crew relied on IRSA through the crews namespace `default` ServiceAccount	See Crew Runtime AWS Access (No-Build Provider)
The deploy of a crew with heavy dependencies times out	Dependency installation exceeds the startup time limit	See Crews With Large Dependency Trees and contact CrewAI Support

Before You Install

Install

Provision Infrastructure

How the Migration Works

What Changes for a Crew

Before You Begin

Namespace Isolation Must Be Disabled

The Python Package Index Must Be Configured

Crew Pods Need Network Access to the Package Indexes

The Runtime Image Must Be Pullable

Keep `CREW_IMAGE_REGISTRY_OVERRIDE` Set

Crews That Call Cloud APIs With Workload Identity

Git Projects Must Package to Less Than 50 MB

Crews With Large Dependency Trees

Step 1: Upgrade the Chart and Stay on BuildKit

Step 2: Prepare Cloud Credentials for Crews

Step 3: Switch the Provider to No-Build

Step 4: Migrate One Crew and Verify

Step 5: Migrate the Remaining Crews

Step 6: Disable BuildKit (Optional)

Rolling Back

Troubleshooting

​How the Migration Works

​What Changes for a Crew

​Before You Begin

​Namespace Isolation Must Be Disabled

​The Python Package Index Must Be Configured

​Crew Pods Need Network Access to the Package Indexes

​The Runtime Image Must Be Pullable

​Keep CREW_IMAGE_REGISTRY_OVERRIDE Set

​Crews That Call Cloud APIs With Workload Identity

​Git Projects Must Package to Less Than 50 MB

​Crews With Large Dependency Trees

​Step 1: Upgrade the Chart and Stay on BuildKit

​Step 2: Prepare Cloud Credentials for Crews

​Step 3: Switch the Provider to No-Build

​Step 4: Migrate One Crew and Verify

​Step 5: Migrate the Remaining Crews

​Step 6: Disable BuildKit (Optional)

​Rolling Back

​Troubleshooting

How the Migration Works

What Changes for a Crew

Before You Begin

Namespace Isolation Must Be Disabled

The Python Package Index Must Be Configured

Crew Pods Need Network Access to the Package Indexes

The Runtime Image Must Be Pullable

Keep `CREW_IMAGE_REGISTRY_OVERRIDE` Set

Crews That Call Cloud APIs With Workload Identity

Git Projects Must Package to Less Than 50 MB

Crews With Large Dependency Trees

Step 1: Upgrade the Chart and Stay on BuildKit

Step 2: Prepare Cloud Credentials for Crews

Step 3: Switch the Provider to No-Build

Step 4: Migrate One Crew and Verify

Step 5: Migrate the Remaining Crews

Step 6: Disable BuildKit (Optional)

Rolling Back

Troubleshooting