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 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