ImageSpec#

During the development cycle you will want to be able to run your workflows both locally on your machine and remotely on Union, so you will need to ensure that the required dependencies are installed in both environments.

Here we will explain how to set up the dependencies for your workflow to run remotely on Union. For information on how to make your dependencies available locally, see Local dependencies.

ImageSpec#

When a workflow is deployed to Union, each task is set up to run in its own container in the Kubernetes cluster. You specify the dependencies as part of the definition of the container image to be used for each task using the ImageSpec class. For example::

import union

image_spec = union.ImageSpec(
    name="say-hello-image",
    requirements="uv.lock",
)

@union.task(container_image=image_spec)
def say_hello(name: str) -> str:
    return f"Hello, {name}!"

@union.workflow
def hello_world_wf(name: str = "world") -> str:
    greeting = say_hello(name=name)
    return greeting

Here, the ImageSpec class is used to specify the container image to be used for the say_hello task.

  • The name parameter specifies the name of the image. This name will be used to identify the image in the container registry.

  • The requirements parameter specifies the path to a file (relative to the directory in which the union run or union register command is invoked) that specifies the dependencies to be installed in the image. The file may be:

    • A requirements.txt file.

    • A uv.lock file generated by the uv sync command.

    • A poetry.lock file generated by the poetry install command.

    • A pyproject.toml file.

When you execute the union run or union register command, Union will build the container image defined in ImageSpec block (as well as registering the tasks and workflows defined in your code).

Union cloud image builder#

Union Serverless will build the image using its ImageBuilder service in the cloud and registered the image in Union’s own container registry. From there it will be pulled and installed in the task container when it spins up. All this is done transparently and does not require any set up by the user.

Local image build in BYOC

In Union Serverless images defined by ImageSpec are always built using the Union cloud image builder. In Union BYOC, you can optionally build images from the ImageSpec on your local machine by specifying builder="envd" in the ImageSpec. See Local image builder in the BYOC documentation for more details.