Upgrade Guide¶
Each release of Customer-Managed Prefect is associated with a specific helm chart revision, which introduces new or updated services to your infrastructure. As such, when upgrading to the next Quarterly Prefect Server and UI versions, you must upgrade the helm chart as well. The relevant chart should be packaged with each quarterly release of Prefect Cloud.
Important
You must update Prefect versions one release (and subsequently chart minor release) at a time.
For example: 0.4.2 -> 0.5.2 -> 0.6.1 -> 0.7.0
Applying Configuration Changes During Upgrades¶
When upgrading your Customer-Managed instance, you'll typically need to apply your custom configuration using a values-override.yaml file. This ensures your instance maintains its custom settings (authentication, resource limits, URLs, etc.) through the upgrade process.
If you mirror Prefect images or charts through an internal/proxy repository, verify the target versions are synced in that repository before running helm upgrade. For pull and credential details, see the deployment guide.
Basic upgrade command:
helm upgrade customer-managed prefect-cloud-<version>.tgz \
-n customer-managed \
-f values-override.yaml
For Istio chart upgrades:
helm upgrade istiod prefect-istiod-<version>.tgz \
-n istio-system \
-f istio-values-override.yaml
Version Control Your Values
Keep your values-override.yaml in version control. Before each upgrade, review the breaking changes below and update your values file accordingly.
Upgrade from 1.5.x to 1.6.x¶
Breaking Changes¶
The chart no longer depends on the Bitnami postgresql and redis subcharts.
With global.db.use_embedded=true it runs PostgreSQL 17.12 from the official
postgres image. With global.redis.use_embedded=true it runs Valkey 9.0.8
from the valkey/valkey image. Deployments that use an external database and
Redis are unaffected.
The new StatefulSets keep the Bitnami names, selectors, and volume claim
templates, so helm upgrade reuses the data-db-primary-0, data-db-read-0,
and redis-data-redis-master-0 volumes in place. PostgreSQL stays on major
version 17, and Valkey reads the existing Redis append-only files. No data
migration or dump and restore is needed. Database and Redis passwords are not
changed.
Mirror the New Images¶
If you mirror images, sync docker.io/library/postgres:17.12-bookworm and
docker.io/valkey/valkey:9.0.8 before upgrading. The bitnami/postgresql,
bitnami/redis, bitnami/postgres-exporter, bitnami/redis-exporter, and
bitnami/os-shell images are no longer used.
Remove Bitnami Image Overrides¶
Remove any embeddedDB.image.repository or embeddedRedis.image.repository
override that points at a Bitnami image. The chart fails to render while one is
set. Keep embeddedDB.image.registry and embeddedRedis.image.registry if you
point them at a mirror. global.security.allowInsecureImages is no longer
needed.
Removed Values¶
The embeddedDB and embeddedRedis sections now accept only the settings listed
in the chart's values.yaml. These values were removed:
embeddedDB.fullnameOverrideandembeddedRedis.fullnameOverride. Service names are fixed atdb-primary,db-read, andredis-master.embeddedDB.auth.database. The database is alwayspostgres.embeddedRedis.replica.replicaCount. The application only connects toredis-master, so the Redis replica is no longer deployed.
Other Bitnami subchart settings in your overrides are ignored. Move PostgreSQL
server settings into embeddedDB.primary.extendedConfiguration and
embeddedDB.readReplicas.extendedConfiguration.
Delete the Redis Replica Volume¶
The upgrade deletes the redis-replicas StatefulSet but not its volume. Once
the upgrade is complete, delete it:
kubectl delete pvc redis-data-redis-replicas-0 -n <namespace>
Rolling Back¶
Valkey rewrites the Redis append-only files in a format that Redis 7.2 cannot
read. To roll back to a 1.5.x chart, delete the redis-data-redis-master-0
volume so Redis starts empty. Redis then loses its stored data, such as
concurrency leases and queued events. The 1.5.x chart's default Bitnami images
no longer pull from Docker Hub, so set embeddedDB.image.repository and
embeddedRedis.image.repository to the bitnamilegacy images or your mirror.
Upgrade from 1.4.x to 1.5.x (October 2026 Release)¶
Breaking Changes¶
No Customer-Managed chart values have been removed or renamed. Prefect Istio
Chart 1.4.0 moves to Istio 1.31.3, which changes where the Istio CNI image
is published. Review the item below before upgrading. Deployments running in
Traefik-only mode do not install the Prefect
Istio chart and are unaffected by it.
Istio CNI Image Registry Changed¶
If you enabled Istio CNI (istioCNI) in the prefect-istiod chart, the
install-cni image was pulled from registry.istio.io/release, which has no
Istio 1.31 images. Prefect Istio Chart 1.4.0 pins it to docker.io/istio, the
same registry as pilot and proxyv2. Mirror
docker.io/istio/install-cni:1.31.3 before upgrading. If you point Istio at an
internal registry with istioDiscovery.global.hub, set istioCNI.global.hub to
the same registry.
Non-Breaking Updates¶
Istio Control Plane and Gateway Updated¶
Prefect Istio Chart 1.4.0 bundles Istio 1.31.3, up from 1.30.3 in 1.3.0,
and the Customer-Managed chart's Istio gateway moves to 1.31.3 to match.
Upgrade the prefect-istiod chart alongside the Customer-Managed chart. If you
mirror Istio images, sync the 1.31.3 tags of pilot and proxyv2 from
docker.io/istio before upgrading.
Traefik Auth Proxy Image Updated¶
The default Traefik auth proxy image tag has moved from 3.7.8 to 3.7.16. No
values changes are required unless you pin
serviceMesh.routing.authProxy.image.tag yourself. If you mirror images, sync
traefik:3.7.16 before upgrading.
Upgrade from 1.3.x to 1.4.x (July 2026 Release)¶
Breaking Changes¶
There are no breaking changes in this release. No values have been removed or renamed, and no new configuration is required.
Non-Breaking Updates¶
Structured Logging Enabled by Default¶
PREFECT_CLOUD_DISABLE_LOGGING_CONFIG now defaults to "false", so services
that run uvicorn emit JSON access logs and single-event exception tracebacks
instead of plaintext. If your log collectors parse the previous format, review
them before upgrading. To keep the old format, override the variable via
global.backend.extraEnv; see the
July 2026 release notes for an example.
Nebula Memory Request Raised¶
The default memory request for the nebula service has been raised from
650Mi to 900Mi, so that it stays above nebula's startup baseline divided by
the HPA's 70% memory target. Below that threshold the HPA pins the deployment
at maxReplicas. Account for the additional request when planning cluster
capacity, or override nebula.cloud2.resources.requests.memory if you have
already tuned this value.
Traefik Auth Proxy Image Updated¶
The default Traefik auth proxy image tag has moved from 3.6.13 to 3.7.8. No
values changes are required unless you pin
serviceMesh.routing.authProxy.image.tag yourself.
Istio Control Plane Updated¶
Prefect Istio Chart 1.3.0 bundles Istio 1.30.3, up from 1.29.1 in 1.2.0.
Upgrade the prefect-istiod chart alongside the Customer-Managed chart.
Deployments running in Traefik-only mode do
not install this chart and are unaffected.
Upgrade from 1.2.x to 1.3.x (April 2026 Release)¶
Breaking Changes¶
There are no breaking changes for standard deployments in this release.
CloudSQL Proxy Support Removed¶
If you were using the global.backend.database.cloudsqlProxy values, this configuration block has been removed. All database connections must use direct connection mode. Remove any cloudsqlProxy configuration from your values override before upgrading:
# Remove this block if present
global:
backend:
database:
cloudsqlProxy:
enabled: true
# ...
Non-Breaking Updates¶
Auth Proxy Mode Fixes¶
Several bugs in Traefik auth proxy mode have been fixed. If you are using authorizationMode: proxy, upgrade to this chart version to resolve authentication failures that could occur in certain configurations.
New API Routes¶
Istio virtual service routing has been expanded to cover all endpoints introduced in this release, including:
POST /api/flow_runs/bulk_deleteandPOST /api/flow_runs/bulk_set_statePOST /api/flows/bulk_deletePOST /api/work_pools/(.*)/concurrency_statusandPOST /api/work_queues/(.*)/concurrency_statusPOST /api/ui/work_pools/count-flow-runsGET /api/version
No values changes are required. These routes are handled automatically by the updated chart templates.
Upgrade from 0.8.x to 1.2.x (January 2026 Release)¶
Database Migrations Required¶
This release includes database migrations that will run automatically when the server starts. The migrations include:
- Tag-Based Concurrency Limit Migration - Updates tag-based concurrency limits to be backed by global concurrency limits (GCLs). This migration requires Redis access and is handled via the
prefect-cloud self-managed update-orionCLI command during the upgrade process. - Schema Cleanup - Drops unused tables (
lenses) and columns (is_mex_pool,mexschema) from previous releases. - Catchup Migrations - Ensures schema consistency by applying any missing migrations.
Migration Prerequisites
- Ensure Redis is accessible to the Orion service during migration
- The
orion-db-migrationsjob now requirescacheandconcurrency-leasesRedis environment variables - Plan for extended migration time if you have a large number of tag-based concurrency limits
Breaking Changes¶
Frontend & Backend URL Configuration Change¶
The location of the backendUrl and frontendUrl values have been moved, which are now maintained under the global section. Update your values override to comply with the new format.
Before:
frontendUrl: <URL>
backendUrl: <URL>
After:
global:
frontendUrl: <URL>
backendUrl: <URL>
Ingress Resource Default Name Update¶
The default ingress resource name has changed from self-managed-prefect-cloud to customer-managed-prefect-cloud. If you have an existing ingress resource, you must explicitly set the ingress name to preserve the old name:
ingress:
enabled: true
name: self-managed-prefect-cloud # Preserves existing ingress resource
Authentication Configuration Change¶
If you're using SSO authentication, the configuration format has changed:
Before: (Up to Chart Version 1.0.0)
global:
authProvider:
type: okta
okta:
# ... provider settings
After (Chart version 1.1.2+):
global:
authProvider:
okta:
# ... provider settings i.e clientID
Non-Breaking Updates¶
Concurrency Lease Reaper Service¶
A new concurrency-lease-reaper service has been added to manage deployment concurrency leases. This service is automatically deployed with the chart. You can provide extra configuration:
concurrency-lease-reaper:
cloud2: {}
Log Level Default Change¶
The default global log level has changed from DEBUG to INFO. To override this setting:
global:
backend:
extraEnv:
- name: PREFECT_CLOUD_LOGGING_LEVEL
value: "DEBUG"
If you require debug-level logging, explicitly set this value in your configuration.
Upgrade from 0.7.x to 0.8.x¶
Breaking Values File Updates¶
N/A
Non-Breaking Values File Updates¶
N/A
Upgrade from 0.6.x to 0.7.x¶
Breaking Values File Updates¶
N/A
Non-Breaking Values File Updates¶
Specify Ingress Backend Service¶
You can now specify an existing service for the ingress backend(s) to point to. Defaults to the prefect-istio-gateway instance.
ingress:
frontend:
port: ""
targetServiceName: ""
ingress:
backend:
port: ""
targetServiceName: ""
Maintenance Mode¶
Starting in chart release 0.7.0 you can now enable maintenance mode for the application directly from the Helm Chart:
serviceMesh:
maintenanceMode:
enabled: true
Readiness Probes¶
Readiness probes have been adjusted to match what Prefect runs in Production. In many cases, this means removing the readiness probes from services that were previously using the ps aux test. This was not a very effective test, and it will no longer work starting in the server image tag 2025.0715.155226 because we have implemented multi-stage builds to reduce the image's attack surface. This change means ps is no longer available in the final image.
The chart still supports providing your own probes under <service>.cloud2.readinessProbe.
Upgrade from 0.5.x to 0.6.x¶
Breaking Values File Updates¶
N/A
Non-Breaking Values File Updates¶
Cloud Features¶
Enabling cloud features directly from the helm chart is now enabled.
cloudFeatures:
- disable-rate-limiting
- schemas-v2
Autoscaling Using External Metrics¶
It is now possible to configure outscaling based upon external metrics rather than the default CPU/Memory metrics and scaling behavior can be adjusted.
backend:
autoscaling:
actions:
minReplicas: 1
maxReplicas: 2
metrics:
- containerResource:
container: actions
name: memory
target:
averageUtilization: 95
type: Utilization
behavior:
scaleDown:
policies;
- periodSeconds: 120
type: Pods
value: 2
selectPolicy: Max
stabilizationWindowSeconds: 10
Readiness Probes¶
It is now possible to create readiness probes per application with defaults provided:
actions:
cloud2:
readinessProbe:
exec:
command:
- /bin/sh
- -c
- ps aux | grep "prefect" | grep -v grep
initialDelaySeconds: 15
periodSeconds: 10
timeoutSeconds: 3
failureThreshold: 3
Upgrade from 0.4.x to 0.5.x¶
Breaking Values File Updates¶
N/A
Frontend and Backend URL Migration¶
Before:
ingress:
frontend:
url: <URL> # Remove this line
path: "/"
After:
frontendUrl: <URL>
ingress:
frontend:
path: "/"
Before:
ingress:
backend:
url: <URL> # Remove this line
path: "/"
After:
backendUrl: <URL>
ingress:
backend:
path: "/"
Non-Breaking Values File Updates¶
Autoscaling¶
It is now possible to set maximum and minimum replicas for each service if autoscaling is enabled:
backend:
autoscaling:
actions:
minReplicas: 1
maxReplicas: 2