Learn how to use deployments to trigger flow runs remotely.
name
.
This value becomes the deployment name.
A work_pool_name
is also required.
Your flow code location can be specified in a few ways:
image
argument in the deploy
method.from_source
on a flow and specify one of the following:
serve
method
of the Flow
object or the serve
utility
is a great option for managing multiple flows simultaneously.
Once you have authored your flow and decided on its deployment settings, run this long-running
process in a location of your choosing.
The process stays in communication with the Prefect API, monitoring for work and submitting each run
within an individual subprocess.
Because runs are submitted to subprocesses, any external infrastructure configuration
must be set up beforehand and kept associated with this process.
Benefits to this approach include:
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}
.
You can trigger deployment runs in multiple ways. For a complete guide, see Run deployments.
Quick examples:
From the CLI:
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
).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
.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.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 and choosing human-readable version strings.
If left unset, the version field will be automatically populated in one of two ways:
version
will be the first eight characters of your commit hash.version
will be your flow’s version, which if not assigned in the flow decorator (@flow(version="my-version")
) will be a hash of the file the flow is defined in.version_type
: When a deployment is created or updated, Prefect will attempt to infer version information from your environment.
Providing a version_type
instructs Prefect to only attempt version information collection from an environment of that type.
The following version types are available: vcs:github
, vcs:gitlab
, vcs:bitbucket
, vcs:azuredevops
, vcs:git
, or prefect:simple
.
vcs:git
offers similar versioning detail to officially supported version control platforms, but does not support direct linking to commits from the Prefect Cloud UI.
It is meant as a fallback option in case your version control platform is not supported.
prefect:simple
is for any deployment version created where no Git context is available.
If left unset, Prefect will automatically select the appropriate version_type
based on the detected environment.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.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.