Deploy overview

Use deployments to orchestrate flow runs remotely.

A deployment is a server-side store of metadata that enables remote orchestration. It defines when, where, and how a workflow should run.

Key features of deployments include:

• scheduling: You can set deployments to run manually, on a schedule, or in response events.
• Remote management: Deployments expose an API and UI that allow you to trigger new runs, cancel active runs, pause scheduled runs, and customize parameters remotely.
• Infrastructure configuration: Deployments inherit infrastructure settings from work pools, which can be overridden at creation or runtime.
• Metadata storage: They store important information about the flow, enabling remote orchestration and management.

Deployment concepts and architecture

One of the core use cases for creating a deployment is to run flows on a schedule. However, deployments do not create or schedule flow runs. If a deployment specifies a schedule, a Prefect server (or Prefect Cloud) creates and schedules flow runs. A lightweight polling process called a worker polls the server for scheduled runs and submits those flow runs to your infrastructure.

Workers submit additional information to infrastructure with default values specified by a required job configuration, called a work pool. Work pools have a 1:1 relationship with workers, and are the primary concept used to describe a deployment’s relationship to infrastructure. Deployments can override the work pool’s default values as needed. By default, each work pool has a single work queue that controls priority and concurrency of run execution. Create one or more work queues if you need more precise control.

Choose where to deploy your workflows

First, determine whether you want your flows to run on Prefect Cloud’s serverless infrastructure, on your own horizontally scalable infrastructure (e.g., Kubernetes or AWS Elastic Container Service), or in a process work pool on long-lived infrastructure.

The best choice depends on your use case. If you already have long-lived infrastructure, or want to prototype quickly, consider a local process deployment. If you have flows with variable infrastructure needs, consider an infrastructure-specific deployment. Prefect Cloud users who value simplicity should consider a serverless option.

Serverless

Prefect Cloud offers two approaches that don’t require you to self-host workers. With Push work pools, Prefect will submit jobs to your infrastructure, without a worker. If you have specific infrastructure requirements but do not need to run your own worker, use this approach.

With Managed work pools, Prefect will submit and run flows on Prefect’s infrastructure. This is the easiest way to get your flow code running remotely.

Prototyping and local processes

To run flows in a local process, there are two options. The .serve() method can be useful for prototyping quickly; it couples the creation of a deployment and the creation of a process worker. Use a worker with a process work pool on long-lived remote infrastructure, such as a VM or EC2 instance.

Scalable infrastructure

Prefect offers different worker types with infrastructure-specific configuration. For example, if you want to run your worker on an AWS ECS service, you might need to specify an Execution Role ARN.

These are known as “hybrid” work pools because there is a boundary between your proprietary assets, such as your flow code, and the Prefect backend (including Prefect Cloud).

You don’t have to commit to one approach

You can mix and match approaches based on the needs of each flow. You can also change the deployment approach for a particular flow as its needs evolve. For example, you might use workers for your expensive machine learning pipelines, but use the serve mechanics for smaller, more frequent file-processing pipelines.

Key concepts summary

Concept	Description
Deployment	Metadata and configuration for workflows
Worker	A lightweight polling process that submits jobs to infrastructure
Work pool	Default infrastructure-specific job specifications for flow runs
Hybrid work pool	A work pool that requires a self-hosted worker
Push work pool	A work pool that does not require a runner. Prefect Cloud submits jobs to your infrastructure
Managed work pool	a serverless work pool that submits your jobs to Prefect Cloud’s compute
Work queue	A specification to control runs’ priority and concurrency

Manage the deployment lifecycle

Deployment lifecycle management in Prefect involves three main actions: build, push, and pull.

• Build: This action prepares your deployment for execution. It can include steps like building Docker images or running shell scripts to set up the environment.
• Push: This action is used to upload or publish your deployment artifacts.
• Pull: This is the only required action. It defines how Prefect retrieves your deployment in remote execution environments.

Each action consists of a list of steps executed in sequence. Steps can include utility functions like run_shell_script for executing shell commands or specific steps like build_docker_image for Docker-based deployments. Deployments can retrieve code from remote storage at runtime.

Choose how to deploy your workflows

There are a variety of ways to create and manage deployments.

• Prefect.yaml
• The Python SDK
• The Prefect Terraform provider
• The REST API

prefect.yaml currently allows for more customization, especially in terms of build, push, and pull steps. It’s particularly useful when you need fine-grained control over these processes. The Python SDK is more programmatic and might be preferred if you want to integrate deployment creation into your existing Python scripts or applications.

Choose prefect.yaml when:

• You need more control over build, push, and pull steps
• You want to version control your deployment configurations
• You prefer a declarative approach to deployment definition

Choose the Python SDK when:

• You want to programmatically create deployments
• You’re integrating deployment creation into existing Python scripts
• You prefer an imperative approach to defining deployments

Only the Python SDK supports the .serve() method. While deployments cannot be created via the UI, they can be edited, or deleted. Prefect.

See this CI/CD Guide for a recommended approach managing deployments via CI/CD.

Breaking down the deployment schema

class Deployment:
    """
    Structure of the schema defining a deployment
    """

    # required defining data
    name: str
    flow_id: UUID
    entrypoint: str
    path: Optional[str] = None

    # workflow scheduling and parametrization
    parameters: Optional[Dict[str, Any]] = None
    parameter_openapi_schema: Optional[Dict[str, Any]] = None
    schedules: list[Schedule] = None
    paused: bool = False
    trigger: Trigger = None

    # concurrency limiting
    concurrency_limit: Optional[int] = None
    concurrency_options: Optional[
        ConcurrencyOptions(collision_strategy=Literal['ENQUEUE', 'CANCEL_NEW'])
    ] = None

    # metadata for bookkeeping
    version: Optional[str] = None
    description: Optional[str] = None
    tags: Optional[list] = None

    # worker-specific fields
    work_pool_name: Optional[str] = None
    work_queue_name: Optional[str] = None
    job_variables: Optional[Dict[str, Any]] = None
    pull_steps: Optional[Dict[str, Any]] = None

All methods for creating Prefect deployments are interfaces for populating this schema.

Required defining data

Deployments require a name and a reference to an underlying Flow.

The deployment name is not required to be unique across all deployments, but is required to be unique for a given flow ID. This means you will often see references to the deployment’s unique identifying name {FLOW_NAME}/{DEPLOYMENT_NAME}.

For example, to trigger a deployment run from the Prefect CLI:

prefect deployment run my-first-flow/my-first-deployment

or from the Python SDK with run_deployment:

from prefect.deployments import run_deployment


run_deployment(
    name="my-first-flow/my-first-deployment",
    parameters={"my_param": "42"},
    job_variables={"env": {"MY_ENV_VAR": "staging"}},
    timeout=0, # don't wait for the run to finish
)

The other two fields are:

• path: think of the path as the runtime working directory for the flow. For example, if a deployment references a workflow defined within a Docker image, the path is the absolute path to the parent directory where that workflow will run anytime the deployment is triggered. This interpretation is more subtle in the case of flows defined in remote filesystems.
• entrypoint: the entrypoint of a deployment is a relative reference to a function decorated as a flow that exists on some filesystem. It is always specified relative to the path. Entrypoints use Python’s standard path-to-object syntax (for example, path/to/file.py:function_name or simply path:object).

The entrypoint must reference the same flow as the flow ID.

Prefect requires that deployments reference flows defined within Python files. Flows defined within interactive REPLs or notebooks cannot currently be deployed as such. They are still valid flows that will be monitored by the API and observable in the UI whenever they are run, but Prefect cannot trigger them.

Workflow scheduling and parametrization

One of the primary motivations for creating deployments of flows is to remotely schedule and trigger them. Just as you can call flows as functions with different input values, deployments can be triggered or scheduled with different values through parameters.

These are the fields to capture the required metadata for those actions:

• schedules: a list of schedule objects. Most of the convenient interfaces for creating deployments allow users to avoid creating this object themselves. For example, when updating a deployment schedule in the UI basic information such as a cron string or interval is all that’s required.
• parameter_openapi_schema: an OpenAPI compatible schema that defines the types and defaults for the flow’s parameters. This is used by the UI and the backend to expose options for creating manual runs as well as type validation.
• parameters: default values of flow parameters that this deployment will pass on each run. These can be overwritten through a trigger or when manually creating a custom run.
• enforce_parameter_schema: a boolean flag that determines whether the API should validate the parameters passed to a flow run against the schema defined by parameter_openapi_schema.

Scheduling is asynchronous and decoupled

Pausing a schedule, updating your deployment, and other actions reset your auto-scheduled runs.

Concurrency limiting

Prefect supports managing concurrency at the deployment level to enable limiting how many runs of a deployment can be active at once. To enable this behavior, deployments have the following fields:

• concurrency_limit: an integer that sets the maximum number of concurrent flow runs for the deployment.
• collision_strategy: configure the behavior for runs once the concurrency limit is reached. Falls back to ENQUEUE if unset.
  • ENQUEUE: new runs transition to AwaitingConcurrencySlot and execute as slots become available.
  • CANCEL_NEW: new runs are canceled until a slot becomes available.

prefect deploy

prefect deploy ... --concurrency-limit 3 --collision-strategy ENQUEUE

Metadata for bookkeeping

Important information for the versions, descriptions, and tags fields:

• version: versions are always set by the client and can be any arbitrary string. We recommend tightly coupling this field on your deployments to your software development lifecycle. For example if you leverage git to manage code changes, use either a tag or commit hash in this field. If you don’t set a value for the version, Prefect will compute a hash.
• description: provide reference material such as intended use and parameter documentation. Markdown is accepted. The docstring of your flow function is the default value.
• tags: group related work together across a diverse set of objects. Tags set on a deployment are inherited by that deployment’s flow runs. Filter, customize views, and searching by tag.

Everything has a version

Deployments have a version attached; and flows and tasks also have versions set through their respective decorators. These versions are sent to the API anytime the flow or task runs, allowing you to audit changes.

Worker-specific fields

Work pools and workers are an advanced deployment pattern that allow you to dynamically provision infrastructure for each flow run. The work pool job template interface allows users to create and govern opinionated interfaces to their workflow infrastructure. To do this, a deployment using workers needs the following fields:

• work_pool_name: the name of the work pool this deployment is associated with. Work pool types mirror infrastructure types, which means this field impacts the options available for the other fields.
• work_queue_name: if you are using work queues to either manage priority or concurrency, you can associate a deployment with a specific queue within a work pool using this field.
• job_variables: this field allows deployment authors to customize whatever infrastructure options have been exposed on this work pool. This field is often used for Docker image names, Kubernetes annotations and limits, and environment variables.
• pull_steps: a JSON description of steps that retrieves flow code or configuration, and prepares the runtime environment for workflow execution.

Pull steps allow users to highly decouple their workflow architecture. For example, a common use of pull steps is to dynamically pull code from remote filesystems such as GitHub with each run of their deployment.