ZenML Azure Container Registry 集成指南从 ACR 部署、URI 定位到 Service Connector 认证【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlAzure Container RegistryACR是 ZenML 内置的容器注册表 flavor 之一用于在 ZenML 栈中统一管理容器镜像的拉取与推送。本文以仓库文档 docs/book/component-guide/container-registries/azure.md 为核心骨架完整讲解 ACR 的创建、URI 获取、zenml container-registry注册与栈绑定并深入对比本地认证与Azure Service Connector两条认证路径最后结合 azure_container_registry.py 与 azure_service_connector.py 源码说明其底层实现原理。读完本文你将能独立完成一个可移植、可复用的 ZenML Azure 容器注册表栈组件配置。何时使用 Azure Container Registry当你的 ZenML 栈满足以下任一条件时应当选用 Azure Container Registry flavor栈中有一个或多个组件需要拉取或推送容器镜像典型场景是远程 orchestrator、step operator 需要从 ACR 拉取运行镜像或者镜像构建器需要将镜像推送到 ACR你已经有可用的 Azure 云环境与订阅。如果你并未使用 Azure请查看仓库中 container-registries 组件指南 下提供的其他 flavorDocker Hub、GCP、GitHub 等对应实现分别位于 src/zenml/container_registries 目录下。部署 ACR创建你的容器注册表创建 Azure Container Registry 的完整过程在 Azure 门户中完成在 Azure 门户中进入创建 Container Registry 的入口依次选择订阅subscription、资源组resource group、位置location与注册表名称registry name点击Review Create完成创建。需要特别注意的是注册表名称最终会直接成为镜像仓库 URI 的组成部分因此建议使用与 ZenML 栈命名一致、便于识别的名称例如zenmlregistry。如果你希望跳过手动创建、直接部署一整套包含 ACR 的 ZenML 云端栈也可以参考仓库 docs/book/how-to/infrastructure-deployment 目录下的栈部署相关指南或使用 infra 目录中提供的 Terraform 模板一键创建并注册云端栈组件。获取注册表 URIREGISTRY_NAME.azurecr.ioZenML 通过 URI 定位容器注册表Azure Container Registry 的 URI 遵循固定格式REGISTRY_NAME.azurecr.io # 示例 zenmlregistry.azurecr.io myregistry.azurecr.io获取你专属 URI 的步骤登录 Azure 门户在搜索栏输入container registries选择你要使用的注册表如果还没有任何注册表请先按上文部署 ACR一节创建用该注册表的名称填充模板REGISTRY_NAME.azurecr.io即得到完整 URI。注意URI 中不要携带https://前缀ZenML 侧的 URI 校验会自动去除尾部的斜杠见下文源码解析部分对uri字段验证器的说明。注册容器注册表并加入活跃栈使用 ACR 需要两个前置条件Docker已安装并处于运行状态已获取注册表 URI见上一节。随后执行注册命令并把它更新到当前活跃栈中zenml container-registry register NAME \ --flavorazure \ --uriREGISTRY_URI # 将容器注册表加入活跃栈 zenml stack update -c NAME其中-c是--container-registry的简写。完成注册后还必须配置访问 ACR 所需的认证否则流水线运行阶段镜像推拉会失败——认证方式正是下文的核心内容。认证方法两条路径的完整对比不配置任何认证就接入 ACR 是不可能的。ZenML 提供两条认证路径面向本地快速验证的Local Authentication以及官方推荐的Azure Service Connector。前者配置简单、适合本地开发后者支持自动配置、本地登录、长期凭据安全存储并能跨多个栈组件复用同一套 Azure 凭据是可移植生产环境的正确选择。方式一本地认证Local Authentication该方式直接使用ZenML 代码运行所在环境中的 Docker 客户端认证信息。在你本机注册 Azure Container Registry 时无需显式提供任何凭据——ZenML 会复用 Azure CLI 与 Docker 客户端存储在本机的本地凭据。前置条件本机安装并配置好 Azure CLI官方安装文档并已使用账号登录。随后执行az acr login让 Docker 获得推拉镜像的权限# 将 REGISTRY_NAME 替换为实际名称。 # REGISTRY_NAME 可以从注册表 URI 中取得REGISTRY_NAME.azurecr.io az acr login --nameREGISTRY_NAME⚠️可移植性警告使用本地认证的 ACR 栈无法跨环境移植——流水线一旦迁移到 CI/CD、远程 orchestrator 或其他机器本机 Docker 凭据便不再可用。要让 ZenML 流水线完全可移植官方明确建议改用 Azure Service Connector 将栈组件与远端 ACR 关联。方式二Azure Service Connector推荐Service Connector 是 ZenML 管理云资源认证的统一机制针对 ACR 场景可以带来四方面收益自动配置auto-configuration连接器自动为栈组件注入可用的认证本地登录local login需要时可按需将凭据临时下发到本地 Docker 客户端长期凭据安全实践遵循最小权限与凭据生命周期管理最佳实践多组件凭据复用同一套 Azure 凭据可同时服务于 ACR、AKS 等其他 Azure 资源。从源码看Azure 容器注册表 flavor 在 azure_container_registry.py 中通过service_connector_requirements显式声明了兼容连接器条件connector_typeazure、resource_typedocker-registry、并以uri字段作为资源 ID 属性。也就是说zenml container-registry register --flavorazure注册出的组件天生就预期与 Azure 类型的 Service Connector 配合使用。第一步注册 Azure Service Connector如果当前 ZenML 部署中还没有可用的 Azure Service Connector使用交互式命令注册交互模式会引导你选择认证方法与目标资源类型一个连接器可以同时覆盖 ACR 及多种 Azure 资源zenml service-connector register --type azure -i非交互式示例——使用Azure Service Principal 凭据配置一个仅指向单个 ACR 注册表的连接器zenml service-connector register CONNECTOR_NAME --type azure --auth-method service-principal --tenant_idAZURE_TENANT_ID --client_idAZURE_CLIENT_ID --client_secretAZURE_CLIENT_SECRET --resource-type docker-registry --resource-id REGISTRY_URI命令输出示例$ zenml service-connector register azure-demo --type azure --auth-method service-principal --tenant_ida79f3633-8f45-4a74-a42e-68871c17b7fb --client_id8926254a-8c3f-430a-a2fd-bdab234d491e --client_secretAzureSuperSecret --resource-type docker-registry --resource-id demozenmlcontainerregistry.azurecr.io ⠸ Registering service connector azure-demo... Successfully registered service connector azure-demo with access to the following resources: ┏━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ RESOURCE TYPE │ RESOURCE NAMES ┃ ┠────────────────────┼───────────────────────────────────────┨ ┃ docker-registry │ demozenmlcontainerregistry.azurecr.io ┃ ┗━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛权限要求请务必为凭据关联的实体服务主体或托管身份授予访问 ACR 的 IAM 权限。根据 azure_service_connector.py 中ResourceTypeModel的声明ACR 资源类型要求至少具备拉取与推送镜像的权限如AcrPull、AcrPush角色以及列出注册表的权限如Contributor角色。资源名称支持两种格式规范资源名[https://]{registry-name}.azurecr.io或简写{registry-name}若连接器配置了资源组则只能访问该资源组内的 ACR。第二步查看哪些连接器可访问目标 ACR若已配置了一个或多个 Azure Service Connector可以列出所有可访问docker-registry资源的连接器zenml service-connector list-resources --connector-type azure --resource-type docker-registry命令输出示例The following docker-registry resources can be accessed by azure service connectors that you have configured: ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ CONNECTOR ID │ CONNECTOR NAME │ CONNECTOR TYPE │ RESOURCE TYPE │ RESOURCE NAMES ┃ ┠──────────────────────────────────────┼────────────────┼────────────────┼────────────────────┼───────────────────────────────────────┨ ┃ db5821d0-a658-4504-ae96-04c3302d8f85 │ azure-demo │ azure │ docker-registry │ demozenmlcontainerregistry.azurecr.io ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛第三步注册 ACR 组件并通过连接器关联先注册 Azure 容器注册表组件URI 指向目标 ACR再通过交互式命令把它与连接器绑定# 注册 Azure 容器注册表并引用目标 ACR 的 URI zenml container-registry register CONTAINER_REGISTRY_NAME -f azure \ --uriREGISTRY_URL # 通过 Azure Service Connector 将容器注册表与目标 ACR 关联 zenml container-registry connect CONTAINER_REGISTRY_NAME -i非交互式版本直接指定连接器 ID 完成关联zenml container-registry connect CONTAINER_REGISTRY_NAME --connector CONNECTOR_ID命令输出示例$ zenml container-registry connect azure-demo --connector azure-demo Successfully connected container registry azure-demo to the following resources: ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ CONNECTOR ID │ CONNECTOR NAME │ CONNECTOR TYPE │ RESOURCE TYPE │ RESOURCE NAMES ┃ ┠──────────────────────────────────────┼────────────────┼────────────────┼────────────────────┼───────────────────────────────────────┨ ┃ db5821d0-a658-4504-ae96-04c3302d8f85 │ azure-demo │ azure │ docker-registry │ demozenmlcontainerregistry.azurecr.io ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛第四步在 ZenML 栈中使用最后把容器注册表纳入一个新栈其余组件以...占位并设为活跃栈# 注册并设置包含新容器注册表的栈 zenml stack register STACK_NAME -c CONTAINER_REGISTRY_NAME ... --set补充连接器关联后的本地 Docker 登录 将 ACR 组件与 Service Connector 关联后你本地 Docker 客户端将不再被认证去访问远端注册表。如果仍需通过 Docker CLI 手动操作远端仓库可以临时使用 Service Connector 的本地登录能力将认证临时下发到本地 Dockerzenml service-connector login CONNECTOR_NAME --resource-type docker-registry --resource-id CONTAINER_REGISTRY_URI命令输出示例$ zenml service-connector login azure-demo --resource-type docker-registry --resource-id demozenmlcontainerregistry.azurecr.io ⠹ Attempting to configure local client using service connector azure-demo... WARNING! Your password will be stored unencrypted in /home/stefan/.docker/config.json. Configure a credential helper to remove this warning. See https://docs.docker.com/engine/reference/commandline/login/#credentials-store The azure-demo Docker Service Connector was used to successfully configure the local Docker/OCI container registry client/SDK.输出中关于密码明文存储的 WARNING 来自 Docker 客户端本身属于正常提示生产环境可参考输出建议为 Docker 配置 credential helper 后再进行本地登录。源码解析flavor、配置项与凭据解析链路flavor 定义与连接器约束azure_container_registry.py 中的AzureContainerRegistryFlavor是 ACR 的 flavor 入口核心逻辑有三处name属性返回ContainerRegistryFlavor.AZURE.value即 CLI 中--flavorazure对应的枚举值见 enums.pyservice_connector_requirements声明connector_typeazure、resource_typedocker-registry、resource_id_attruri用于在注册与连接时自动过滤出兼容的 Azure Service Connector并以 URI 作为资源匹配键config_class继承自BaseContainerRegistryConfig意味着 ACR 复用了所有容器注册表共用的配置模型。配置字段与校验base_container_registry.py 定义了容器注册表的基础配置ACR 场景下你需要关心的字段包括字段必填默认值说明uri是—容器注册表 URI即zenml container-registry register传入的--uri值ACR 下形如myregistry.azurecr.iodefault_repository否None镜像存储的默认仓库命名空间未指定时镜像存放在注册表根目录uri字段有一个内建验证器strip_trailing_slash注册时会自动去除 URI 尾部的/因此即使误传https://myregistry.azurecr.io/这样的值也会被规范化——但https://前缀不会被剥离最佳实践仍是直接使用myregistry.azurecr.io格式。凭据解析与 Docker 客户端注入BaseContainerRegistry.credentials属性base_container_registry.py揭示了认证的完整解析顺序优先读取组件上显式配置的认证 SecretBasicAuthSecretSchema类型的用户名/密码若组件已连接 Service Connector则从连接器获取凭据当连接器是DockerServiceConnector时直接取出其配置中的username/password连接器凭据过期时会自动刷新connector_has_expired()检查。这也解释了为什么本地认证路径无需在 ZenML 侧配置任何凭据——镜像推拉由本地 Docker 客户端持有的az acr login凭据完成而 Service Connector 路径则是将连接器的 Azure 凭据转换为可用的 Docker 认证后注入。ACR 资源类型与认证方法细节azure_service_connector.py 中 ACR 资源类型ResourceTypeModel的实现要点权限模型使用服务主体之外的其他认证方法时优先走 Entra ID 认证要求身份具备AcrPush角色若失败则回退到 ACR 管理员账号认证需要注册表开启管理员账号对应代码中Falling back to admin credentials for ACR authentication的逻辑令牌交换_ACRTokenExchangeClient同文件约 L1895实现 AAD OAuth 令牌交换——将 Azure AD 令牌通过 ACR 的/oauth2/exchange端点换取 ACR refresh tokenscope 为repository:*:*从而为 Docker 客户端提供访问仓库的短期凭据资源解析_parse_acr_resource_id同时接受[https://]{registry-name}.azurecr.io与{registry-name}两种资源 ID 格式并统一转换为注册表名。总结与最佳实践至此一套完整的 ZenML Azure Container Registry 配置链路已经清晰在 Azure 门户创建 ACR得到形如REGISTRY_NAME.azurecr.io的 URI用zenml container-registry register --flavorazure --uri...注册组件选择认证方式本地开发用az acr login本地认证快速验证生产与多云场景务必用zenml service-connector register --type azure创建连接器再通过zenml container-registry connect关联用zenml stack register ... -c NAME --set或zenml stack update -c NAME将组件纳入栈需要手动操作远端仓库时用zenml service-connector login临时下发本地 Docker 认证。遵循Service Connector 最小权限角色AcrPush/AcrPull 跨组件凭据复用的路径你的 ZenML 流水线就能在不同环境中无缝移植镜像推拉也始终经过受控、可审计的认证链路。更多可配置属性可进一步查看 flavor 对应的 SDK 文档入口sdk_docs_url见 azure_container_registry.py。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考