ZenML Local Image Builder 完全指南用本机 Docker 与 Podman 构建流水线容器镜像【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml本指南围绕 ZenML 内置的 Local Image Builder本地镜像构建器展开它是 ZenML 开箱即用的 image builder 组件之一负责在客户端机器上利用本机容器引擎Docker 或 Podman构建并推送流水线运行所需的容器镜像。读完本文你将掌握容器引擎的自动选择与强制指定机制、Local Image Builder 的注册与堆栈接入方法、subprocess子进程构建模式的适用场景与参数映射规则以及镜像推送凭据的正确配置方式。什么是 Local Image Builder在 ZenML 中当流水线运行在远程 orchestrator编排器或 step operator步骤算子上时ZenML 会在运行时动态生成 Dockerfile 并构建 Docker 镜像以便在隔离的、定义良好的环境中执行流水线步骤。负责构建镜像这一动作的组件就是image builder它是 ZenML 堆栈stack中的一种特殊组件类型StackComponentType.IMAGE_BUILDER。Local Image Builder是随 ZenML 内置的 image builder flavor其 flavor 名称为local。它的特点非常直接在客户端机器client machine上使用你本机可用的容器引擎来构建和推送镜像无需为它额外配置任何远程基础设施。从源码角度可以清晰地看到这一特性——LocalImageBuilder.is_building_locally属性恒返回True见 local_image_builder.pyproperty def is_building_locally(self) - bool: Whether the image builder builds the images on the client machine. return True即便你的堆栈中没有显式配置任何 image builderZenML 也会默认使用 Local Image Builder 来保持所有构建行为的一致性。此时镜像构建环境就是你的客户端环境本身。因此Local Image Builder 是整个 ZenML 容器化链路中最基础、最常用的一环也是理解 ZenML 容器化整体流程 的起点。容器引擎选择自动探测与全局配置Local Image Builder 本身并不绑定某个具体的容器实现而是委托给一个抽象层Container Engine容器引擎。ZenML 当前支持两种引擎Docker与Podman分别由DockerContainerEngine与PodmanContainerEngine实现见 container_engines 目录。容器引擎是ZenML 客户端的全局设置其选择逻辑位于 factory.py 的get_container_engine()函数中规则如下什么都不做自动探测ZenML 按DOCKER → PODMAN的顺序依次检查引擎可用性返回第一个可用的引擎。DockerContainerEngine.check_availability()会先检查dockerCLI 是否在 PATH 中再通过 docker-py 客户端对 Docker daemon 执行ping探测PodmanContainerEngine.check_availability()则检查podmanCLI 是否存在并执行podman info验证守护进程可访问。强制指定引擎设置环境变量ZENML_CONTAINER_ENGINE为docker或podman。设置后ZenML 只会尝试你指定的引擎若该引擎不可用会抛出RuntimeError并附带具体不可用原因。典型开发者笔记本上装有 Docker Desktop因此默认情况下会直接使用 Docker无需任何额外配置。若希望机器上的所有本地构建都走 Podman可以这样固定引擎export ZENML_CONTAINER_ENGINEpodman需要注意这个全局设置只影响本地镜像构建/推送以及客户端侧的准备镜像等环节不改变那些必须依赖 Docker daemon API 的功能例如本地 Docker orchestrator。什么时候应该使用 Local Image BuilderLocal Image Builder 适合以下场景你可以在执行流水线的机器上运行Docker或Podman你需要使用要求容器化的远程组件如远程 orchestrator、step operator但不想为容器镜像构建再额外配置一套基础设施。换句话说只要你的开发机具备可用的容器引擎Local Image Builder 就是成本最低的默认选择——它随 ZenML 一起交付无需任何额外安装与部署步骤注册即用。如何部署 Local Image Builder部署成本为零。Local Image Builder 内置于 ZenML 中直接可用不需要安装额外的 integration、不需要启动远程服务、也不需要任何基础设施前置条件。这正是它与其他云托管型 image builder如 kaniko、AWS/GCP 构建服务最大的区别。如何注册并使用 Local Image Builder前置条件使用 Local Image Builder 需要满足两点本机已安装并可运行 Docker 或 Podman具体选择方式见上文容器引擎选择一节你的用户已认证到堆栈中的容器注册中心container registry认证方式可以是命令行登录docker login或podman login或通过堆栈中的 container registry 组件 / service connector 提供凭据ZenML 会在每次构建推送操作时自动应用这些凭据。注册与接入堆栈注册 Local Image Builder 并将其接入堆栈的命令如下zenml image-builder register NAME --flavorlocal # 注册并激活一个包含该 image builder 的新堆栈 zenml stack register STACK_NAME -i NAME ... --set其中-i即 image-builder 缩写参数。注册完成后只要该 image builder 位于你的 active stack 中任何需要构建容器镜像的组件如远程 orchestrator、step operator都会自动使用它无需在代码中直接与其交互。从源码结构看LocalImageBuilderFlavorlocal_image_builder.py通过config_class指向LocalImageBuilderConfig、implementation_class指向LocalImageBuilder并声明 flavor 名为local同时提供默认的文档 URL 与 SDK 文档 URL供 Dashboard 展示和跳转使用。镜像构建与推送的内部流程理解 Local Image Builder 的build()方法local_image_builder.py有助于掌握其行为engine get_container_engine() if container_registry: self._check_registry_image(image_name, container_registry) engine.build( image_nameimage_name, build_contextbuild_context, docker_build_optionsdocker_build_options, container_registrycontainer_registry, use_subprocessself.config.use_subprocess_call, ) if container_registry: return engine.push_image(image_name, container_registry) return image_name整个流程分四步解析引擎调用get_container_engine()按全局设置或自动探测得到当前引擎校验镜像归属若提供了 container registry先通过container_registry.is_valid_image_name_for_registry(image_name)校验镜像名是否属于该 registry否则抛出ValueError构建将构建任务委托给引擎的build()方法并把配置项use_subprocess_call透传下去推送若堆栈中包含 container registry构建完成后调用引擎的push_image()将镜像推送到远端并返回镜像的 repo digest否则直接返回本地镜像名。凭据与推送的引擎差异Docker 引擎实现见 docker_engine.py构建默认走Docker APIdocker-py SDK通过DockerClient.from_env()连接 daemon镜像推送也走 API 流式推送并解析 repo digest推送时的 registry 凭据通常来自$HOME/.docker/config.json如果你的 Docker 配置文件位于其他位置请设置DOCKER_CONFIG环境变量指向包含config.json的目录若通过堆栈的 container registry 组件提供了凭据ZenML 会在每次操作时用这些凭据执行登录login_client通过 docker-py 登录必要时还会调用login_cli执行docker login并安装一个基于内存 auths 的凭据辅助器使显式登录的凭据优先于系统 Docker 凭据存储中的配置。Podman 引擎实现见 podman_engine.py构建与推送始终使用 Podman CLIpodman build -/podman push不经过 Docker APIregistry 登录通过podman login完成或由堆栈中 container registry 组件提供的凭据按操作自动应用需要注意Podman 无法可靠报告远程 manifest digest见 podman_engine.py 中对 podman issue #14779 的处理注释因此push_image()会推送一个带唯一 tag 的镜像并返回该引用作为稳定的替代标识surrogate而get_image_repo_digest()恒返回None。Subprocess 模式通过 Docker CLI 构建镜像当激活的容器引擎是Docker时构建默认走 Docker API。你可以配置 Local Image Builder 改为通过子进程调用docker build命令来构建镜像这在需要使用Docker BuildKit中尚未通过 Python SDK 暴露的选项时非常有用。当激活的引擎是Podman时构建本来就始终使用 Podman CLI因此use_subprocess_call设置对该引擎没有效果Podman 引擎会忽略该参数。启用 Subprocess 模式在注册或更新组件时启用该模式# 注册时启用 subprocess 模式 zenml image-builder register NAME --flavorlocal --use_subprocess_calltrue # 更新已有的 local image builder zenml image-builder update NAME --use_subprocess_calltrue从配置类源码local_image_builder.py可以看到use_subprocess_call是LocalImageBuilderConfig中唯一可配置的字段class LocalImageBuilderConfig(BaseImageBuilderConfig): Local image builder configuration. use_subprocess_call: bool Field( defaultFalse, descriptionWhether to use a subprocess docker build call to build the image instead of using the Docker python SDK. Ignored when the active container engine is Podman (Podman always uses the CLI)., )默认值为False即默认走 Docker API。Subprocess 模式下构建选项的映射规则在 subprocess 模式下通过DockerSettings传入的构建选项DockerBuildOptions会被转换为docker build的 CLI 参数。具体的转换逻辑实现在 docker_settings.py 的to_docker_cli_options()方法中规则如下buildargs、labels两个字典会分别被展开为多个--build-arg KEYVALUE与--label KEYVALUE参数列表类型的值会以相同的参数名重复传递多次每个元素一个参数例如cache_from中的每个镜像都会生成一个--cache-from value值为True的布尔参数将不带值传递如--pull、--no-cache其他所有值会被转换为字符串并以--KEY VALUE的形式传递额外传入的未命名参数model_extra因为DockerBuildOptions使用extraallow接受任意附加选项也会按同样的规则转换字典展开为多个--key kv列表重复传参True/None只传参数名False则跳过。以DockerSettings指定构建参数为例完整配置方式见 containerization.mdfrom zenml import pipeline from zenml.config import DockerSettings docker_settings DockerSettings( build_config{build_options: {buildargs: {MY_ARG: value}}} ) pipeline(settings{docker: docker_settings}) def my_pipeline(...): ...在 Docker 引擎的 subprocess 模式下上述配置会被转换成docker build - -t image --build-arg MY_ARGvalue在 Podman 引擎下构建始终走 CLI遵循完全相同的映射规则Podman 构建兼容 Docker CLI 参数。值得一提的是DockerBuildOptions还支持若干显式转换字段pull、rm、no_cache、shm_size、labels、build_args、cache_from它们在不同命名空间CLI 与 Python SDK间会做名称迁移如 SDK 参数buildargs↔ 属性build_args确保两种构建路径的参数语义一致。与 DockerSettings 的协同使用Local Image Builder 只是构建执行者真正决定构建什么的是流水线/步骤上的DockerSettings。两者的分工是DockerSettings决定父镜像、依赖、环境变量、源码文件、构建选项等镜像内容详见 containerization.md 中的完整配置项说明Local Image Builder 负责在客户端机器上把上述内容真正构建为镜像并推送到 registry。因此常见的组合用法是在堆栈中注册localflavor 的 image builder同时在流水线代码中通过DockerSettings精细控制镜像内容。对绝大多数本地开发与中等规模团队来说这套组合即可满足需求无需引入额外的远程镜像构建基础设施。最佳实践小结保持默认即可大多数装有 Docker 的开发机无需任何配置Local Image Builder 会自动选择 Docker 引擎固定引擎用环境变量需要统一团队行为或强制使用 Podman 时通过ZENML_CONTAINER_ENGINE固定引擎需要 BuildKit 高级选项时启用 subprocess 模式仅对 Docker 引擎生效Podman 引擎不受影响提前配置 registry 凭据通过docker login/podman login或堆栈中 container registry 组件 / service connector 提供凭据否则推送阶段会失败Docker 自定义配置目录记得设置DOCKER_CONFIG善用构建复用结合 DockerSettings 的构建复用与优化能力可显著减少重复构建时间。相关参考image builder 组件总览见 image-builders/README.md容器引擎选择的完整说明见 containerization.md源码实现见 local_image_builder.py 与 container_engines 目录。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考