Use YAML to schedule and trigger flow runs and manage your code and deployments.
prefect.yaml
file is a YAML file describing base settings for your deployments, procedural steps for preparing deployments,
and instructions for preparing the execution environment for a deployment run.
Initialize your deployment configuration, which creates the prefect.yaml
file, with the CLI command prefect init
in any directory or repository that stores your flow code.
prefect.yaml
file. Run prefect init
to be prompted with available recipes in your installation.
You can provide a recipe name in your initialization command with the --recipe
flag, otherwise Prefect will attempt to
guess an appropriate recipe based on the structure of your working directory (for example if you initialize within a git
repository, Prefect will use the git
recipe).prefect.yaml
file contains:
prefect deploy
CLI command when creating a deployment.
prefect.yaml
file flexibilityIn older versions of Prefect, this file must be in the root of your repository or project directory and named prefect.yaml
.
With Prefect 3, this file can be located in a directory outside the project or a subdirectory inside the project.
It can be named differently if the filename ends in .yaml
. You can have multiple prefect.yaml
files with the same name
in different directories.By default, prefect deploy
uses a prefect.yaml
file in the project’s root directory. To use a custom deployment
configuration file, supply the new --prefect-file
CLI argument when running the deploy
command from the root of your
project directory:prefect deploy --prefect-file path/to/my_file.yaml
prefect.yaml
looks like this:
prefect deploy
without altering the deployments
section of your
prefect.yaml
file. The prefect deploy
command helps in deployment creation through interactive prompts. The prefect.yaml
file facilitates version-controlling your deployment configuration and managing multiple deployments.
prefect.yaml
file control the lifecycle of the creation and execution of your deployments.
The three actions available are build
, push
, and pull
.
pull
is the only required deployment action. It defines how Prefect pulls your deployment in remote execution
environments.
Each action is defined as a list of steps executed in sequence. Each step has the following format:
requires
field. Prefect uses this to auto-install if the step is notid
to reference outputs in
future steps. The additional fields map directly to Python keyword arguments to the step function. Within a given section,
steps always run in their order within the prefect.yaml
file.
build
, push
, and pull
sections on a per-deployment basis; define build
, push
, and pull
fields within a deployment definition in the prefect.yaml
file.The prefect deploy
command uses any build
, push
, or pull
instructions from the deployment’s definition in the
prefect.yaml
file.This capability is useful for multiple deployments that require different deployment instructions.prefect.yaml
to specify setup steps or dependencies,
(like creating a Docker image), required to run your deployments.
If you initialize with the Docker recipe, you are prompted to provide
required information, such as image name and tag:
--field
to avoid the interactive experienceWe recommend that you only initialize a recipe when first creating your deployment structure. Then store
your configuration files within version control.
Sometimes you may need to initialize programmatically and avoid the interactive prompts.--field
flag:prefect.yaml
as template values.
We recommend using a templated {{ image }}
within prefect.yaml
(specifically in the work pool’s job_variables
section).
By avoiding hardcoded values, the build step and deployment specification won’t have mismatched values.
prefect-docker
package; in cases that deal with external services,
additional required packages are auto-installed for you.run_shell_script
step and feed the output into the build_docker_image
step:
id
field is used in the run_shell_script
step to reference its output in the next step.
s3
recipe:
prefect.yaml
file, you should find that the push
and pull
sections have been templated out
as follows:
--field
flag); note that the
folder
property of the push
step is a template—the pull_from_s3
step outputs both a bucket
value as well as a folder
value for the template downstream steps. This helps you keep your steps consistent across edits.
As discussed above, if you use blocks, you can template the credentials section with
a block reference for secure and dynamic credentials access:
prefect deploy
, this push
section executes upon successful completion of your build
section.
prefect.yaml
file. It contains instructions for preparing your
flows for a deployment run. These instructions execute each time a deployment in this folder is run through a worker.
There are three main types of steps that typically show up in a pull
section:
set_working_directory
: this step sets the working directory for the process prior to importing your flowgit_clone
: this step clones the provided repository on the provided branchpull_from_{cloud}
: this step pulls the working directory from a Cloud storage location (for example, S3)GitHubCredentials
block to clone a private GitHub repository:
BitBucketCredentials
or GitLabCredentials
block to clone from Bitbucket or GitLab. In
lieu of a credentials block, you can also provide a GitHub, GitLab, or Bitbucket token directly to the ‘access_token` field.
Use a Secret block to do this securely:
run_shell_script
allows for the execution of one or more shell commands in a subprocess, and returns the standard output
and standard error of the script.
This step is useful for scripts that require execution in a specific environment, or those which have specific input and output
requirements.expand_env_vars: true
in your run_shell_script
step. For example:expand_env_vars: true
, the above step returns a literal string $USER
instead of the current user.pip_install_requirements
installs dependencies from a requirements.txt
file within a specified directory.requirements.txt
file after cloning:
retrieve_secrets
is a custom python module packaged
into the default working directory of a Docker image (which is /opt/prefect by default).
main
is the function entry point, which returns an access token (for example, return {"access_token": access_token}
) like the
preceding example, but utilizing the Azure Python SDK for retrieval.
prefect.yaml
file can reference dynamic values in several different ways:
build
and push
produce named fields such as image_name
; you can reference these
fields within prefect.yaml
and prefect deploy
will populate them with each call. References must be enclosed in double
brackets and in "{{ field_name }}"
format{{ prefect.blocks.block_type.block_slug }}
syntax. It is highly recommended that you use block references for any sensitive
information (such as a GitHub access token or any credentials) to avoid hardcoding these values in plaintext{{ prefect.variables.variable_name }}
syntax. Use variables to reference non-sensitive, reusable pieces of information
such as a default image name or a default work pool name.{{ $MY_ENV_VAR }}
.
This is especially useful for referencing environment variables that are set at runtime.prefect.yaml
file as an example:
build
steps produce fields called image_name
and tag
, every time you deploy a new version of our deployment,
the {{ build-image.image }}
variable is dynamically populated with the relevant values.
prefect_docker.deployments.steps.build_docker_image
which produces both the image_name
and tag
fields.prefect.yaml
file can have multiple deployment configurations that control the behavior of several deployments.
You can manage these deployments independently of one another, allowing you to deploy the same flow with different
configurations in the same codebase.
prefect.yaml
file. This method of declaring multiple
deployments supports version control for all deployments through a single command.
Add new deployment declarations to the prefect.yaml
file with a new entry to the deployments
list.
Each deployment declaration must have a unique name
field to select deployment declarations when using the
prefect deploy
command.
prefect.yaml
file that is in another directory or differently named, the value for
the deployment entrypoint
must be relative to the root directory of the project.prefect.yaml
file:
name
field and can be deployed individually with the --name
flag when deploying.
For example, to deploy deployment-1
, run:
--name
flags:
--all
flag:
my-flow
dev
with a deployment named
my-deployment
dep
and ending in prod
.--no-prompt
flag to skip interactive prompts:
prefect deploy
command, any additional attributes provided are ignored.To provide overrides to a deployment through the CLI, you must deploy that deployment individually.prefect.yaml
file is a standard YAML file, you can use YAML aliases
to reuse configuration across deployments.
This capability allows multiple deployments to share the work pool configuration, deployment actions, or other
configurations.
Declare a YAML alias with the &{alias_name}
syntax and insert that alias elsewhere in the file with the *{alias_name}
syntax. When aliasing YAML maps, you can override specific fields of the aliased map with the <<: *{alias_name}
syntax and
adding additional fields below.
We recommend adding a definitions
section to your prefect.yaml
file at the same level as the deployments
section to store your
aliases.
For example:
deployment-1
and deployment-2
use the same work pool configurationdeployment-1
and deployment-3
use the same scheduledeployment-1
and deployment-2
use the same build deployment action, but deployment-2
overrides the dockerfile
field to use a custom DockerfileProperty | Description |
---|---|
name | The name to give to the created deployment. Used with the prefect deploy command to create or update specific deployments. |
version | An optional version for the deployment. |
tags | A list of strings to assign to the deployment as tags. |
description | An optional description for the deployment. |
schedule | An optional schedule to assign to the deployment. Fields for this section are documented in the Schedule Fields section. |
concurrency_limit | An optional deployment concurrency limit. Fields for this section are documented in the Concurrency Limit Fields section. |
triggers | An optional array of triggers to assign to the deployment |
entrypoint | Required path to the .py file containing the flow you want to deploy (relative to the root directory of your development folder) combined with the name of the flow function. In the format path/to/file.py:flow_function_name . |
parameters | Optional default values to provide for the parameters of the deployed flow. Should be an object with key/value pairs. |
enforce_parameter_schema | Boolean flag that determines whether the API should validate the parameters passed to a flow run against the parameter schema generated for the deployed flow. |
work_pool | Information of where to schedule flow runs for the deployment. Fields for this section are documented in the Work Pool Fields section. |
schedule
section.
Property | Description |
---|---|
interval | Number of seconds indicating the time between flow runs. Cannot use them in conjunction with cron or rrule . |
anchor_date | Datetime string indicating the starting or “anchor” date to begin the schedule. If no anchor_date is supplied, the current UTC time is used. Can only use with interval . |
timezone | String name of a time zone, used to enforce localization behaviors like DST boundaries. See the IANA Time Zone Database for valid time zones. |
cron | A valid cron string. Cannot use in conjunction with interval or rrule . |
day_or | Boolean indicating how croniter handles day and day_of_week entries. Must use with cron . Defaults to True . |
rrule | String representation of an RRule schedule. See the rrulestr examples for syntax. Cannot used them in conjunction with interval or cron . |
concurrency_limit
section.
Property | Description |
---|---|
limit | The maximum number of concurrent flow runs for the deployment. |
collision_strategy | Configure the behavior for runs once the concurrency limit is reached. Options are ENQUEUE , and CANCEL_NEW . Defaults to ENQUEUE . |
work_pool
section.
Property | Description |
---|---|
name | The name of the work pool to schedule flow runs in for the deployment. |
work_queue_name | The name of the work queue within the specified work pool to schedule flow runs in for the deployment. If not provided, the default queue for the specified work pool is used. |
job_variables | Values used to override the default values in the specified work pool’s base job template. Maps directly to a created deployments infra_overrides attribute. |
prefect deploy
in a directory that contains a prefect.yaml
file, the following actions take place in order:
prefect.yaml
file load. First, the build
section loads and all variable and block references resolve. The steps then run in the order provided.push
section loads and all variable and block references resolve; the steps within this section then run in the order provided.pull
section is templated with any step outputs but is not run. Block references are not hydrated for security purposes: they are always resolved at runtime.prefect deploy
CLI are then overlaid on the values loaded from the file.build
, push
, and pull
sections in deployment definitions take precedence over the corresponding sections above them in
prefect.yaml
.requires
keyword installs the necessary packages.prefect.yaml
file, and run prefect deploy
. Running just this command will prompt you to select a deployment interactively, or you may specify the deployment to update with --name your-deployment
.