`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.

​prefect_docker.deployments.steps

​Functions

​cacheable

​build_docker_image

​push_docker_image

​Classes

​BuildDockerImageResult

​PushDockerImageResult