Why use ACI for flow run execution?
ACI (Azure Container Instances) is a fully managed compute platform that streamlines running your Prefect flows on scalable, on-demand infrastructure on Azure.Prerequisites
Before starting this guide, make sure you have:- An Azure account and user permissions for provisioning resource groups and container instances.
- The
azure
CLI installed on your local machine. You can follow Microsoft’s installation guide. - Docker installed on your local machine.
Step 1. Create a resource group
Azure resource groups serve as containers for managing groupings of Azure resources. Replace<resource-group-name>
with the name of your choosing, and <location>
with a valid Azure location name, such aseastus
.
echo $RG_SCOPE
in your terminal. It should be formatted as follows:
Step 2. Prepare ACI permissions
In order for the worker to create, monitor, and delete the other container instances in which flows will run, we’ll need to create a custom role and an identity, and then affiliate that role to the identity with a role assignment. When we start our worker, we’ll assign that identity to the container instance it’s running in.1. Create a role
The customContainer Instances Contributor
role has all the permissions your worker will need to run flows in other container instances. Create it by running the following command:
2. Create an identity
Create a user-managed identity with the following command, replacing<identity-name>
with the name you’d like to use for the identity:
3. Assign roles to the identity
Now let’s assign theContainer Instances Contributor
role we created earlier to the new identity:
AcrPull
role to the identity:
Step 3. Create the worker container instance
Before running this command, set yourPREFECT_API_URL
and PREFECT_API_KEY
as environment variables:
<work-pool-name>
with the name of the ACI work pool you want to create in Prefect. Here we’re using the work pool name as the name of the container instance in Azure as well, but you may name it something else if you prefer.
az container create
CLI reference.
Step 4. Create an ACR registry
In order to build and push images containing flow code to Azure, we’ll need a container registry. Create one with the following command, replacing<registry-name>
with the registry name of your choosing:
Step 5. Update your ACI work pool configuration
Once your work pool is created, navigate to the Edit page of your ACI work pool. You will need to update the following fields:Identities
This will be yourIDENTITY_ID
. You can get it from your terminal by running echo $IDENTITY_ID
. When adding it to your work pool, it should be formatted as a JSON array:

ACRManagedIdentity
ACRManagedIdentity is required for your flow code containers to be pulled from ACR. It consists of the following:- Identity: the same
IDENTITY_ID
as above, as a string
- Registry URL: your
<registry-name>
, followed by.azurecr.io

Subscription ID and resource group name
Both the subscription ID and resource group name can be found in theRG_SCOPE
environment variable created earlier in the guide. View their values by running echo $RG_SCOPE
:

Step 6. Pick up a flow run with your new worker
This guide uses ACR to store a Docker image containing your flow code. Write a flow, then deploy it usingflow.deploy()
, which will copy flow code into a Docker image and push that image to an ACR registry.
1. Log in to ACR
Use the following commands to log in to ACR:2. Write and deploy a simple test flow
Create and run the following script to deploy your flow. Be sure to replace<registry-name>
and <work-pool-name>
with the appropriate values.
my_flow.py