Upgrade Guide

Each release of Prefect Cloud is associated with a specific helm chart revision, which introduces new or updated services to your infrastructure. As such, when upgrading 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

Upgrade from 0.8.x to 1.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:

auth:
  sso:
    provider: "okta"
    # ... other provider settings

After:

auth:
  sso:
    providers:
      - name: "okta"
        # ... provider settings

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