Skip to main content

​
prefect_docker.deployments.steps

Prefect deployment steps for building and pushing Docker images. These steps can be used in a prefect.yaml file to define the default build steps for a group of deployments, or they can be used to define the build step for a specific deployment. !!! example Build a Docker image before deploying a flow: 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        id: build-image
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev

push:
    - prefect_docker.deployments.steps.push_docker_image:
        requires: prefect-docker
        image_name: "{{ build-image.image_name }}"
        tag: "{{ build-image.tag }}"

​
Functions

​
cacheable 

cacheable(func: Callable[P, T]) -> Callable[P, T]

​
build_docker_image 

build_docker_image(image_name: str, dockerfile: str = 'Dockerfile', tag: str | None = None, additional_tags: list[str] | None = None, ignore_cache: bool = False, persist_dockerfile: bool = False, dockerfile_output_path: str = 'Dockerfile.generated', build_backend: str = 'docker-py', **build_kwargs: Any) -> BuildDockerImageResult
Builds a Docker image for a Prefect deployment. Can be used within a prefect.yaml file to build a Docker image prior to creating or updating a deployment. Args:
  • image_name: The name of the Docker image to build, including the registry and repository.
  • dockerfile: The path to the Dockerfile used to build the image. If “auto” is passed, a temporary Dockerfile will be created to build the image.
  • tag: The tag to apply to the built image.
  • additional_tags: Additional tags on the image, in addition to tag, to apply to the built image.
  • persist_dockerfile: If True and dockerfile=“auto”, the generated Dockerfile will be saved instead of deleted after the build.
  • dockerfile_output_path: Optional path where the auto-generated Dockerfile should be saved (e.g., “Dockerfile.generated”). Only used if persist_dockerfile is True.
  • build_backend: The backend to use for building images. "docker-py" (default) uses the docker-py library. "buildx" uses python-on-whales for BuildKit/buildx support, enabling features like build secrets, SSH forwarding, and multi-platform builds.
  • **build_kwargs: Additional keyword arguments to pass to the build backend. When build_backend="docker-py", these are forwarded to docker-py’s client.api.build(). When build_backend="buildx", these are forwarded to python_on_whales.docker.buildx.build() and may include secrets, ssh, cache_from, cache_to, platforms, and push.
Returns: A dictionary containing the image name and tag of the built image. Example: Build a Docker image prior to creating a deployment: 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev
Build a Docker image with multiple tags: 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev
        additional_tags:
            - v0.1.0,
            - dac9ccccedaa55a17916eef14f95cc7bdd3c8199
Build a Docker image using an auto-generated Dockerfile: 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev
        dockerfile: auto
Build a Docker image for a different platform: 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev
        dockerfile: Dockerfile
        platform: amd64
Save the auto-generated Dockerfile to disk: 
build:
  - prefect_docker.deployments.steps.build_docker_image:
      requires: prefect-docker
      image_name: repo-name/image-name
      tag: dev
      dockerfile: auto
      persist_dockerfile: true
      dockerfile_output_path: Dockerfile.generated

​
push_docker_image 

push_docker_image(image_name: str, tag: str | None = None, credentials: dict[str, Any] | None = None, additional_tags: list[str] | None = None, ignore_cache: bool = False, build_backend: str = 'docker-py') -> PushDockerImageResult
Push a Docker image to a remote registry. Args:
  • image_name: The name of the Docker image to push, including the registry and repository.
  • tag: The tag of the Docker image to push.
  • credentials: A dictionary containing the username, password, and URL for the registry to push the image to.
  • additional_tags: Additional tags on the image, in addition to tag, to apply to the built image.
  • build_backend: The backend to use for pushing images. "docker-py" (default) uses docker-py. "buildx" uses python-on-whales.
Returns: A dictionary containing the image name and tag of the pushed image. Examples: Build and push a Docker image to a private repository: 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        id: build-image
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev
        dockerfile: auto
push:
    - prefect_docker.deployments.steps.push_docker_image:
        requires: prefect-docker
        image_name: "{{ build-image.image_name }}"
        tag: "{{ build-image.tag }}"
        credentials: "{{ prefect.blocks.docker-registry-credentials.dev-registry }}"
Build and push a Docker image to a private repository with multiple tags 
build:
    - prefect_docker.deployments.steps.build_docker_image:
        id: build-image
        requires: prefect-docker
        image_name: repo-name/image-name
        tag: dev
        dockerfile: auto
        additional_tags: [
            v0.1.0,
            dac9ccccedaa55a17916eef14f95cc7bdd3c8199
        ]
push:
    - prefect_docker.deployments.steps.push_docker_image:
        requires: prefect-docker
        image_name: "{{ build-image.image_name }}"
        tag: "{{ build-image.tag }}"
        credentials: "{{ prefect.blocks.docker-registry-credentials.dev-registry }}"
        additional_tags: "{{ build-image.additional_tags }}"

​
Classes

​
BuildDockerImageResult

The result of a build_docker_image step. Attributes:
  • image_name: The name of the built image.
  • tag: The tag of the built image.
  • image: The name and tag of the built image.
  • image_id: The ID of the built image.
  • additional_tags: The additional tags on the image, in addition to tag.

​
PushDockerImageResult

The result of a push_docker_image step. Attributes:
  • image_name: The name of the pushed image.
  • tag: The tag of the pushed image.
  • image: The name and tag of the pushed image.
  • additional_tags: The additional tags on the image, in addition to tag.