Release Notes

For any questions or concerns, please reach out to support@prefect.io.

December 2, 2025 Customer-Managed Release Notes

This release adjusts the base image for our server and ui images to use the Red Hat Universal Base Image (UBI). This base image provides enhanced security and is a requirement for certain customers.

Specifically, the base image has changed from python:3.12.11-slim to redhat/ubi8:8.10-1763613534.

For more information, see Red Hat's documentation.

There are new tags available that include this change:

server: 2025.10.202512022007
ui: 2025.1202.201742

November 2025 Customer-Managed Helm Chart Release Notes

Ad-hoc release of our Helm charts with important updates and standardization of resources.

The Customer-Managed Helm chart has graduated to its first major version after internal QA.
The Istio Helm chart has graduated to its first major version after internal QA.

Versions

Please see below for the list of tags to pull the latest Helm charts and container images from Google Artifact Registry.

Latest Server Image: 2025.10.202512022007
Latest UI Image: 2025.1202.201742
Latest Prefect Istio Chart: 1.0.0
Latest Customer-Managed Cloud Chart: 1.0.0
Latest 2.x Client Supported: 2.20.22
Latest 3.x Client Supported: 3.4.21
Next Scheduled Release: 2026-01

Breaking Changes

Customer-Managed Helm Chart

backendUrl and frontendUrl value location change
- Breaking Change: backendUrl & frontendUrl are now maintained under the global section.
- Action Required: Update your values override to comply with the new format. Required change shown below.
  
  Before:
```
frontendUrl: <URL>
backendUrl: <URL>
```
  After:
```
global:
  frontendUrl: <URL>
  backendUrl: <URL>
```
Kubernetes ingress resource naming
- Breaking Change: The default ingress resource name has changed from self-managed-prefect-cloud to customer-managed-prefect-cloud.
- Action Required: 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
```

Istio Helm Chart

No breaking changes found.

Fixes

Customer-Managed Helm Chart

concurrency-lease-reaper now properly establishes a connection with the orion database.
concurrency-lease-reaper, foreman, and partman are provided appropriate resource requests and limits by default.

Istio Helm Chart

Bump to stable release of Istio 1.25.5 by default.

October 2025 Prefect Customer-Managed Release Notes

Note that the terminology we use for this product has changed from self-managed to customer-managed.

The Google Artifact Registry path has been updated to match this change:

Previous path: us-docker.pkg.dev/prefect-prd-self-managed/cloud/
New path: us-docker.pkg.dev/prefect-prd-customer-managed/cloud/
Example: us-docker.pkg.dev/prefect-prd-customer-managed/cloud/ui:2025.1002.161850

This requires authenticating with a new service account, which should have been sent alongside this release.

Also note that the server image tag format has changed slightly:

Previous tag format: <year>.<month><date>.<timestamp> (example: 2025.0715.155226)
Current tag: <release-year>.<month>.<timestamp> (example: 2025.10.202510021558)

This enables the tag to clearly indicate which quarterly release it belongs to, while still including a timestamp to indicate the release order.

Versions

Please see below for the list of tags to pull the latest Helm charts and container images from Google Artifact Registry.

Latest Server Image: 2025.10.202511042343
Latest UI Image: 2025.1002.161850
Latest Prefect Istio Chart: 0.1.3
Latest Customer-Managed Cloud Chart: 0.8.1
Latest 2.x Client Supported: 2.20.22
Latest 3.x Client Supported: 3.4.21
Next Scheduled Release: 12/2025

Breaking Changes

Deployment Concurrency Flag Removal: The ENABLE_DEPLOYMENT_CONCURRENCY_ORCHESTRATION flag has been removed as lease-based concurrency is now the default behavior for improved reliability

Features

Deployment Concurrency Lease Management - Implemented lease-based deployment concurrency system to prevent slots from being held indefinitely, ensuring proper resource allocation and preventing deadlocks.
Enhanced Audit Log Visibility - Actor information now displayed in audit log table for both user and service account events, replacing the previous User column for better visibility and accountability.
Delayed Execution for RunDeployment Actions - Backports delayed execution functionality from Prefect Cloud and OSS to maintain API compatibility across all Prefect deployments. The RunDeployment action now accepts a schedule_after field that delays deployment execution by the specified duration, enabling opt-out workflow patterns where automated deployments can be cancelled before execution.

Maintenance

Artifact Partition Schema Permissions - Added missing artifact partition schema permissions for orion users to ensure proper data access and security.
Docket Logging Configuration - Enhanced logging support for docket-based services including the concurrency lease reaper for improved monitoring and debugging capabilities.
Integration Tests Deployment Handling - Updated deployment scripts to properly handle integration tests deployment processes.
Set plan_cache_mode to force_custom_plan for Orion connections. We were already setting this for the Events DB, but it was missing from Orion connections. This setting prevents plan cache hangs on partitioned tables (flow_run, task_run, artifact). Without this, the planner cache can hang for seconds evaluating every combination of parameters against all partitions and their indices.
Fixed a bug where event filters had labels with empty value arrays (like {"hello": []}), the PostgreSQL query generation wasn't handling them correctly - instead of returning no results, it would return all results due to missing filter clauses.
Removed unused sprinkler service - This service was no longer needed and has been removed to simplify the deployment.
Applied various security vulnerability fixes.
Helm chart: changed the default global log level setting (under global.backend.extraEnv as PREFECT_CLOUD_LOGGING_LEVEL) from DEBUG to INFO.
Helm chart: added the concurrency-lease-reaper service now that we have updated deployment concurrency to use lease-based management.
Helm chart: added cache and concurrency-leases Redis environment variables to orion-db-migrations (to support an update to tag-based concurrency limits to be backed by global concurrency limits).
Helm chart: added documentation to the README.md explaining how to adjust livenessProbes and readinessProbes when necessary.

June 2025 Prefect Customer-Managed Release Notes

Versions

Please see below the tags to pull the latest helm charts and images from Google Artifact Registry.

Latest Server Image: 2025.0715.155226
Latest UI Image: 2025.0725.162824
Latest Prefect Istio Chart: 0.1.3
Latest Customer-Managed Cloud Chart: 0.7.3
Latest 2.x Client Supported: 2.20.16
Latest 3.x Client Supported: 3.4.6
Next Scheduled Release: 09/2025

Features

Schedule Parameters and Slug Support - Enhanced scheduling capabilities with parameter support and slug-based references backported from Nebula
Work Pool Storage Configuration - Comprehensive storage configuration options for work pools with deployment parameter schema updates
ANDed Related Resources in Event Queries - Support for AND operations in event queries for more precise filtering
Work Pool/Queue/Job Variables in Flow Run Creation - Enhanced FlowRunCreate with support for work pool, queue, and job variable fields
Updateable Pull Steps for Deployments - Pull steps can now be modified post-deployment creation
Admin API Access for Owners/Admins - Direct admin API access for account owners and administrators
Persistent Tracing Filters - UI tracing filters now saved to local storage
Deployment versioning - deployment versions from later client versions will show in the UI but this release does not cover full deployment version rollback

Maintenance

Fixed TaskRunPolicy Retry Delays - Proper float value support for retry_delay configurations
Enabled Autocommit Mode for Automations - Improved transaction handling for automation workflows
Removed Cloud-Specific Features - Removed rate limiting, billing, managed execution, and incident management features for optimized Customer-Managed experience

Upgrading Customer-Managed Cloud

Upgrade Guidelines

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.

Below we will provide important information on changes between Helm chart releases to make note of as you migrate from each minor version.

Note You must update Prefect versions one release (and subsequently chart minor release) at a time. (i.e 0.4.2 -> 0.5.2 -> 0.6.1 -> 0.7.0)

Upgrade from 0.6.x - 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. Enabling:

serviceMesh:
  maintenanceMode:
    enabled: true

Disabling:

serviceMesh:
  maintenanceMode:
    enabled: false

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 the 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 - 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 off external metrics and autoscaling behavior

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 - 0.5.x

Breaking Values file updates

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 max and min replicas for each service if autoscaling is enabled.

backend:
  autoscaling:
    actions:
      minReplicas: 1
      maxReplicas: 2