Skip to content

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.fullnameOverride and embeddedRedis.fullnameOverride. Service names are fixed at db-primary, db-read, and redis-master.
  • embeddedDB.auth.database. The database is always postgres.
  • embeddedRedis.replica.replicaCount. The application only connects to redis-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_delete and POST /api/flow_runs/bulk_set_state
  • POST /api/flows/bulk_delete
  • POST /api/work_pools/(.*)/concurrency_status and POST /api/work_queues/(.*)/concurrency_status
  • POST /api/ui/work_pools/count-flow-runs
  • GET /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-orion CLI command during the upgrade process.
  • Schema Cleanup - Drops unused tables (lenses) and columns (is_mex_pool, mex schema) 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-migrations job now requires cache and concurrency-leases Redis 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