> ## 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. # Migrate from BuildKit to No-Build > Move an existing installation and its crews from the BuildKit provider (BUILDKIT_KUBERNETES) to the no-build provider (KUBERNETES_V3) 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. > [!WARNING] > > 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](#step-1-upgrade-the-chart-and-stay-on-buildkit) 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--crew---web`, `-worker`, `-redis` | `org--autom-`, `-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`](https://enterprise-docs.crewai.com/reference/chart-values/service-account#param-rbac-namespace-isolation). 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](https://enterprise-docs.crewai.com/troubleshooting.md#preflight-check-failures). ### The Python Package Index Must Be Configured Crew pods install packages from the index in [`secrets.UV_DEFAULT_INDEX`](https://enterprise-docs.crewai.com/reference/chart-values/secrets#param-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](https://enterprise-docs.crewai.com/configuration/private-pypi-mirror.md). ### 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](https://enterprise-docs.crewai.com/installation/network-allowlist.md). > [!WARNING] > > 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](https://enterprise-docs.crewai.com/configuration/private-pypi-mirror.md)). ### The Runtime Image Must Be Pullable Crew pods run the image in [`envVars.AUTOMATION_IMAGE_REFERENCE`](https://enterprise-docs.crewai.com/reference/chart-values/environment-variables#param-env-vars-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`](https://enterprise-docs.crewai.com/reference/chart-values/environment-variables#param-env-vars-automation-base-image-registry-override) and [`envVars.AUTOMATION_BASE_IMAGE_REPOSITORY_PREFIX`](https://enterprise-docs.crewai.com/reference/chart-values/environment-variables#param-env-vars-automation-base-image-repository-prefix). If nodes pull the image with cloud IAM instead of the Replicated pull secret, also set [`envVars.REPLICATED_DISABLED`](https://enterprise-docs.crewai.com/reference/chart-values/environment-variables#param-env-vars-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](https://enterprise-docs.crewai.com/troubleshooting.md#automation-image-version-floor) preflight. ### Keep `CREW_IMAGE_REGISTRY_OVERRIDE` Set The chart still requires [`envVars.CREW_IMAGE_REGISTRY_OVERRIDE`](https://enterprise-docs.crewai.com/reference/chart-values/environment-variables#param-env-vars-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)](https://enterprise-docs.crewai.com/cloud-providers/aws.md#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: ```bash theme={null} 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. > [tab] Helm CLI / ArgoCD > > Set the provider explicitly in your values file: > > ```yaml theme={null} > envVars: > PROVIDER: "BUILDKIT_KUBERNETES" > > buildkit: > enabled: true > ``` > > Then upgrade: > > ```bash theme={null} > helm upgrade crewai-platform \ > oci://registry.crewai.com/crewai/stable/crewai-platform \ > --values my-values.yaml > ``` > [tab] KOTS Admin Console > > In the Admin Console, open **Config** → **Application Settings**, set **Crew Deployment Provider** to **BuildKit (legacy)**, save, and deploy the new version. Confirm the active provider: ```bash theme={null} 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 ` 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](#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. > [tab] Helm CLI / ArgoCD > > ```yaml theme={null} > envVars: > PROVIDER: "KUBERNETES_V3" > > buildkit: > enabled: true > ``` > > ```bash theme={null} > helm upgrade crewai-platform \ > oci://registry.crewai.com/crewai/stable/crewai-platform \ > --values my-values.yaml > ``` > [tab] KOTS Admin Console > > In **Config** → **Application Settings**, set **Crew Deployment Provider** to **No-build (recommended)**, save, and deploy. 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. 1. Open the crew in the platform and click **Redeploy**. 2. Wait for the deploy to finish. Crew pods install dependencies when they start, so the crew becomes ready only after that installation completes. 3. Check the crew's Kubernetes resources. Replace `` with the crew's numeric ID, which appears in the crew's URL in the platform: ```bash theme={null} # Only org--autom- resources should remain for this crew kubectl get deploy -n crewai-crews -o name | grep -E -- "-(crew|autom)-(-|$)" # 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-" ``` 4. 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](#step-2-prepare-cloud-credentials-for-crews). * Migrate crews with large dependency trees or large repositories separately, and verify each one. List the crews that are still on BuildKit: ```bash theme={null} 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: ```yaml theme={null} 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](#before-you-begin) and [Preflight Check Failures](https://enterprise-docs.crewai.com/troubleshooting.md#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](#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](#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)](https://enterprise-docs.crewai.com/cloud-providers/aws.md#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](#crews-with-large-dependency-trees) and contact CrewAI Support | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.