Push work pools are a special type of work pool. They allow Prefect Cloud to submit flow runs for execution to serverless computing infrastructure without requiring you to run a worker. Push work pools currently support execution in AWS ECS tasks, Azure Container Instances, Google Cloud Run jobs, and Modal.

In this guide you will:

  • Create a push work pool that sends work to Amazon Elastic Container Service (AWS ECS), Azure Container Instances (ACI), Google Cloud Run, or Modal
  • Deploy a flow to that work pool
  • Execute a flow without having to run a worker process to poll for flow runs

You can automatically provision infrastructure and create your push work pool using the prefect work-pool create CLI command with the --provision-infra flag. This approach greatly simplifies the setup process.

First, you will set up automatic infrastructure provisioning for push work pools. Then you will learn how to manually set up your push work pool.

​
Automatic infrastructure provisioning

With Perfect Cloud you can provision infrastructure for use with an AWS ECS, Google Cloud Run, ACI push work pool. Push work pools in Prefect Cloud simplify the setup and management of the infrastructure necessary to run your flows. However, setting up infrastructure on your cloud provider can still be a time-consuming process. Prefect dramatically simplifies this process by automatically provisioning the necessary infrastructure for you.

We’ll use the prefect work-pool create CLI command with the --provision-infra flag to automatically provision your serverless cloud resources and set up your Prefect workspace to use a new push pool.

​
Prerequisites

To use automatic infrastructure provisioning, you need:

  • the relevant cloud CLI library installed
  • to be authenticated with your cloud provider

Install the AWS CLI, authenticate with your AWS account, and set a default region.

If you already have the AWS CLI installed, be sure to update to the latest version.

You will need the following permissions in your authenticated AWS account:

IAM Permissions:

  • iam:CreatePolicy
  • iam:GetPolicy
  • iam:ListPolicies
  • iam:CreateUser
  • iam:GetUser
  • iam:AttachUserPolicy
  • iam:CreateRole
  • iam:GetRole
  • iam:AttachRolePolicy
  • iam:ListRoles
  • iam:PassRole

Amazon ECS Permissions:

  • ecs:CreateCluster
  • ecs:DescribeClusters

Amazon EC2 Permissions:

  • ec2:CreateVpc
  • ec2:DescribeVpcs
  • ec2:CreateInternetGateway
  • ec2:AttachInternetGateway
  • ec2:CreateRouteTable
  • ec2:CreateRoute
  • ec2:CreateSecurityGroup
  • ec2:DescribeSubnets
  • ec2:CreateSubnet
  • ec2:DescribeAvailabilityZones
  • ec2:AuthorizeSecurityGroupIngress
  • ec2:AuthorizeSecurityGroupEgress

Amazon ECR Permissions:

  • ecr:CreateRepository
  • ecr:DescribeRepositories
  • ecr:GetAuthorizationToken

If you want to use AWS managed policies, you can use the following:

  • AmazonECS_FullAccess
  • AmazonEC2FullAccess
  • IAMFullAccess
  • AmazonEC2ContainerRegistryFullAccess

The above policies give you all the permissions needed, but are more permissive than necessary.

Docker is also required to build and push images to your registry.

​
Automatically create a new push work pool and provision infrastructure

To create a new push work pool and configure the necessary infrastructure, run this command for your particular cloud provider:

prefect work-pool create --type ecs:push --provision-infra my-ecs-pool

The --provision-infra flag automatically sets up your default AWS account to execute flows with ECS tasks. In your AWS account, this command creates a new IAM user, IAM policy, and ECS cluster that uses AWS Fargate, VPC, and ECR repository (if they don’t already exist). In your Prefect workspace, this command creates an AWSCredentials block for storing the generated credentials.

Here’s an abbreviated example output from running the command:

_____________________________________________________________________________________________
| Provisioning infrastructure for your work pool my-ecs-pool will require:                   |
|                                                                                            |
|          - Creating an IAM user for managing ECS tasks: prefect-ecs-user                   |
|          - Creating and attaching an IAM policy for managing ECS tasks: prefect-ecs-policy |
|          - Storing generated AWS credentials in a block                                    |
|          - Creating an ECS cluster for running Prefect flows: prefect-ecs-cluster          |
|          - Creating a VPC with CIDR 172.31.0.0/16 for running ECS tasks: prefect-ecs-vpc   |
|          - Creating an ECR repository for storing Prefect images: prefect-flows            |
_____________________________________________________________________________________________
Proceed with infrastructure provisioning? [y/n]: y
Provisioning IAM user
Creating IAM policy
Generating AWS credentials
Creating AWS credentials block
Provisioning ECS cluster
Provisioning VPC
Creating internet gateway
Setting up subnets
Setting up security group
Provisioning ECR repository
Authenticating with ECR
Setting default Docker build namespace
Provisioning Infrastructure ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Infrastructure successfully provisioned!
Created work pool 'my-ecs-pool'!

Default Docker build namespace

After infrastructure provisioning completes, you will be logged into your new ECR repository and the default Docker build namespace will be set to the URL of the registry.

While the default namespace is set, you do not need to provide the registry URL when building images as part of your deployment process.

To take advantage of this, you can write your deploy scripts like this:

example_deploy_script.py
from prefect import flow
from prefect.docker import DockerImage

@flow(log_prints=True)            
def my_flow(name: str = "world"):                          
    print(f"Hello {name}! I'm a flow running in a ECS task!") 


if __name__ == "__main__":
    my_flow.deploy(
        name="my-deployment", 
        work_pool_name="my-work-pool",
        image=DockerImage(                                                 
            name="my-repository:latest",
            platform="linux/amd64",
        )                                                                      
    )

This builds an image with the tag <ecr-registry-url>/my-image:latest and push it to the registry.

Your image name needs to match the name of the repository created with your work pool. You can create new repositories in the ECR console.

You’re ready to create and schedule deployments that use your new push work pool. Reminder that no worker is required to run flows with a push work pool.

​
Use existing resources with automatic infrastructure provisioning

If you already have the necessary infrastructure set up, Prefect detects that at work pool creation and the infrastructure provisioning for that resource is skipped.

For example, here’s how prefect work-pool create my-work-pool --provision-infra looks when existing Azure resources are detected:

Proceed with infrastructure provisioning? [y/n]: y
Creating resource group
Resource group 'prefect-aci-push-pool-rg' already exists in location 'eastus'.
Creating app registration
App registration 'prefect-aci-push-pool-app' already exists.
Generating secret for app registration
Provisioning infrastructure
ACI credentials block 'bb-push-pool-credentials' created
Assigning Contributor role to service account...
Service principal with object ID '4be6fed7-...' already has the 'Contributor' role assigned in 
'/subscriptions/.../'
Creating Azure Container Instance
Container instance 'prefect-aci-push-pool-container' already exists.
Creating Azure Container Instance credentials block
Provisioning infrastructure... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Infrastructure successfully provisioned!
Created work pool 'my-work-pool'!

​
Provision infrastructure for an existing push work pool

If you already have a push work pool set up, but haven’t configured the necessary infrastructure, you can use the provision-infra sub-command to provision the infrastructure for that work pool. For example, you can run the following command if you have a work pool named “my-work-pool”.

prefect work-pool provision-infra my-work-pool

Prefect creates the necessary infrastructure for the my-work-pool work pool and provides you with a summary of the changes:

__________________________________________________________________________________________________________________
| Provisioning infrastructure for your work pool my-work-pool will require:                                      |
|                                                                                                                |
|     Updates in subscription Azure subscription 1                                                               |
|                                                                                                                |
|         - Create a resource group in location eastus                                                           |
|         - Create an app registration in Azure AD prefect-aci-push-pool-app                                     |
|         - Create/use a service principal for app registration                                                  |
|         - Generate a secret for app registration                                                               |
|         - Assign Contributor role to service account                                                           |
|         - Create Azure Container Instance 'aci-push-pool-container' in resource group prefect-aci-push-pool-rg |
|                                                                                                                |
|     Updates in Prefect workspace                                                                               |
|                                                                                                                |
|         - Create Azure Container Instance credentials block aci-push-pool-credentials                          |
|                                                                                                                |
__________________________________________________________________________________________________________________
Proceed with infrastructure provisioning? [y/n]: y

This command speeds up your infrastructure setup process.

As with the examples above, you need to have the related cloud CLI library installed and to be authenticated with your cloud provider.

​
Manual infrastructure provisioning

If you prefer to set up your infrastructure manually, exclude the --provision-infra flag in the CLI command. In the examples below, you’ll create a push work pool through the Prefect Cloud UI.

To push work to ECS, AWS credentials are required.

Create a user and attach the AmazonECS_FullAccess permissions.

From that user’s page, create credentials and store them somewhere safe for use in the next section.

​
Work pool configuration

The push work pool stores information about what type of infrastructure the flow will run on, what default values to provide to compute jobs, and other important execution environment parameters. Because the push work pool needs to integrate securely with your serverless infrastructure, you need to store your credentials in Prefect Cloud by making a block.

​
Create a Credentials block

Navigate to the blocks page, click create new block, and select AWS Credentials for the type.

For use in a push work pool, set the region, access key, and access key secret.

Provide any other optional information and create your block.

​
Create a push work pool

Now navigate to the work pools page. Click Create to configure your push work pool by selecting a push option in the infrastructure type step.

Each step has several optional fields that are detailed in the work pools documentation. Select the block you created under the AWS Credentials field. This allows Prefect Cloud to securely interact with your ECS cluster.

Create your pool to be ready to deploy flows to your Push work pool.

​
Deployment

You need to configure your deployment to send flow runs to your push work pool. For example, if you create a deployment through the interactive command line experience, choose the work pool you just created. If you are deploying an existing prefect.yaml file, the deployment would contain:

  work_pool:
    name: my-push-pool

Deploying your flow to the my-push-pool work pool ensures that runs that are ready for execution are submitted immediately—without the need for a worker to poll for them.

Serverless infrastructure may require a certain image architecture

Serverless infrastructure may assume a certain Docker image architecture; for example, Google Cloud Run will fail to run images built with linux/arm64 architecture. If using Prefect to build your image, you can change the image architecture through the platform keyword (for example, platform="linux/amd64").

​
Putting it all together

With your deployment created, navigate to its detail page and create a new flow run. You’ll see the flow start running without polling the work pool, because Prefect Cloud securely connected to your serverless infrastructure, created a job, ran the job, and reported on its execution.

​
Usage Limits

Push work pool usage is unlimited. However push work pools limit flow runs to 24 hours.

​
Next steps

Learn more about work pools and workers.

Learn about installing dependencies at runtime or baking them into your Docker image in the Deploy to Docker guide.

Was this page helpful?

Run flows on Prefect Managed infrastructureRun flows in Docker containers