企业官网建设流程全解析

ZenML 接入 Amazon ECR：AWS 容器注册中心（Container Registry）完整配置指南

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml

本篇技术指南以 ZenML 开源仓库中 Amazon Elastic Container Registry (ECR) 组件文档 为主体，讲解如何将 AWS ECR 作为 ZenML Stack 中的容器注册中心组件接入、注册与认证，并深度结合仓库源码（src/zenml/integrations/aws/下的 flavor、实现类与 Service Connector）揭示其底层工作原理。读完本篇，你将掌握：ECR 仓库的创建与 URI 拼接规则、zenml container-registry命令行注册与挂载流程、本地 Docker 认证与 AWS Service Connector 两种认证方式，以及 ZenML 在推送镜像前对 ECR 仓库的预检逻辑。

适用场景：何时需要使用 AWS Container Registry

在 ZenML 中，容器注册中心（Container Registry）是多数远程 MLOps Stack 的必备组件，用于存放 ZenML 为运行流水线而构建的 Docker 镜像。当满足以下任一条件时，应当使用 AWS 容器注册中心（flavor 名为aws，来自 ZenML 的awsintegration，后端即 Amazon ECR）：

• Stack 中有一个或多个组件需要拉取或推送容器镜像。在 ZenML 中，绝大多数远程 orchestrators、step operators 以及部分 model deployer 都会把流水线代码容器化，因此需要容器注册中心来存储构建产物（详见 容器注册中心总览）；
• 你拥有 AWS 账号并可以访问 ECR 服务。如果你并非使用 AWS，可以参考其他 container registry flavors（如gcp、azure、dockerhub、github等）。

提示：ZenML 的awsintegration 同时注册了多个 stack 组件 flavor，包括AWSContainerRegistryFlavor、AWSDeployerFlavor、AWSImageBuilderFlavor、SagemakerStepOperatorFlavor与SagemakerOrchestratorFlavor（见 src/zenml/integrations/aws/init.py）。如果你同时使用 SageMaker orchestrator / step operator，同一个awsintegration 即可覆盖全部组件。

部署 ECR：创建仓库（Repository）

ECR 注册中心本身在你创建 AWS 账号后即自动激活，无需额外开通。但在向 ECR 推送镜像前，必须先在目标区域内创建Repository。操作步骤如下：

1. 打开 ECR 控制台；
2. 确认右上角已选中正确的区域（Region）；
3. 点击Create repository（创建仓库）；
4. 创建一个private（私有）仓库。仓库的名称取决于你 Stack 中使用的 orchestrator 或 step operator 会构建的镜像名。

关于仓库命名，ZenML 源码给出了明确的指引：AWSContainerRegistry.post_registration_message（见 aws_container_registry.py）会在注册组件后打印提示——Amazon ECR 要求你先创建仓库才能推送镜像，使用远程 orchestrator 运行流水线时，ZenML 会自动构建并推送名为<REGISTRY_URI>/zenml:<PIPELINE_NAME>的 Docker 镜像，因此至少需要在 ECR 中创建一个名为zenml的仓库，否则首次推送会失败。

如果你希望跳过手工搭建，直接部署一整套包含 ECR 的 ZenML 云端 Stack，可以使用浏览器内的 stack 部署向导、stack 注册向导或 ZenML 官方 AWS Terraform 模块来完成部署与注册。

URI 格式：拼接你的 ECR 注册中心地址

AWS Container Registry 的 URI 必须遵循以下格式：

<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com # 示例： 123456789.dkr.ecr.eu-west-2.amazonaws.com 987654321.dkr.ecr.ap-south-1.amazonaws.com 135792468.dkr.ecr.af-south-1.amazonaws.com

获取你的注册中心 URI 的方法：

• 打开 AWS 控制台，点击右上角用户账户即可看到Account ID（账号 ID）；
• 在 AWS 区域端点列表中选择你希望存放容器镜像的区域。建议选择地理上更近的区域以获得更快的访问速度；
• 将上述两个值填入模板<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com，即得到注册中心 URI。

从源码层面看，URI 是决定注册中心行为的关键配置：

• AWSContainerRegistryConfig中的validate_aws_uri校验器（见 aws_container_registry_flavor.py）规定 URI不能包含/字符，例如715803424592.dkr.ecr.us-east-1.amazonaws.com是合法的；
• 基类BaseContainerRegistryConfig（见 base_container_registry.py）还会自动去除 URI 末尾的斜杠，并提供可选的default_repository字段用于指定镜像存储的默认命名空间；
• AWSContainerRegistry._get_region（见 aws_container_registry.py）通过正则.*\.dkr\.ecr\.(.*)\.amazonaws\.com从 URI 中解析出 Region，用于后续构造 ECR 客户端。若 URI 不符合该格式，会抛出RuntimeError。

注册并使用 AWS Container Registry

前置条件

使用 AWS Container Registry 需要准备：

• 已安装 ZenML 的awsintegration：

  zenml integration install aws

  AWSIntegration.REQUIREMENTS（见 src/zenml/integrations/aws/init.py）会安装sagemaker>=2.237.3,<3.0.0、kubernetes、aws-profile-manager、pytz>=2021.1等依赖；

• Docker 已安装并运行；

• 注册中心 URI（参照上文 URI 格式 小节获取）。

注册组件并挂载到 Stack

执行以下命令注册 AWS Container Registry，并将其加入当前激活的 Stack：

zenml container-registry register <NAME> \ --flavor=aws \ --uri=<REGISTRY_URI> # 将容器注册中心添加到激活的 Stack zenml stack update -c <NAME>

其中<NAME>是你为这个注册中心组件起的名字，<REGISTRY_URI>形如715803424592.dkr.ecr.us-east-1.amazonaws.com。注册之后还需要配置认证方式才能登录 ECR。

如果你想查看 ZenML 当前可用的所有容器注册中心 flavor，可以执行：

zenml container-registry flavor list

从实现角度看，AWSContainerRegistryFlavor（见 aws_container_registry_flavor.py）的name为aws，并声明了 Service Connector 需求：connector_type="aws"、resource_type=DOCKER_REGISTRY_RESOURCE_TYPE（即docker-registry）、resource_id_attr="uri"。这意味着该 flavor 会以 URI 作为资源标识，与 AWS Service Connector 做自动匹配。

推送前的仓库预检（源码行为）

AWSContainerRegistry.prepare_image_push（见 aws_container_registry.py）实现了镜像推送前的预检逻辑：

1. 从镜像名中提取仓库名（正则匹配<uri>/<repo>:<tag>形式），镜像名不合法时抛出ValueError；
2. 通过 ECR 客户端调用describe_repositories()拉取已有仓库列表；
3. 若本地 AWS 凭据不可用导致调用失败，会打印警告并继续尝试推送；
4. 若目标仓库不存在，则列出当前检测到的仓库并警告，提示你可能需要先创建名为<repo>的仓库，然后仍继续尝试推送。

因此，如果你在推送阶段收到 "repository not found" 类错误，第一反应应当是回到 ECR 控制台确认目标仓库已创建。

认证方式（Authentication Methods）

不采用任何形式的认证，ZenML 流水线就无法真正使用 AWS Container Registry。快速本地起步可使用Local Authentication；而官方推荐的方式是通过AWS Service Connector认证，尤其是当你配置的 ZenML Stack 同时组合了其他运行在 AWS 上的远程组件时，Service Connector 可以复用同一套凭据。

方式一：本地认证（Local Authentication）

该方式使用ZenML 代码运行所在环境中的 Docker 客户端认证。在本地机器上这是配置 AWS Container Registry 最快的方式：注册时无需显式提供凭据，直接复用 AWS CLI 与 Docker 客户端存储在本地机器上的凭据与配置。

前置要求：按 AWS CLI 官方文档 安装并配置好 AWS CLI。

随后执行登录命令，让 Docker 具备拉取与推送镜像的权限：

# 将 REGISTRY_URI 和 REGION 填入下面的占位符。 # REGION 可以从 REGISTRY_URI 中提取：`<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com` aws ecr get-login-password --region <REGION> | docker login --username AWS --password-stdin <REGISTRY_URI>

⚠️ 警告：使用本地认证的 AWS Container Registry 所构成的 Stack不具备跨环境可移植性。若要实现 ZenML 流水线的完全可移植，推荐使用 AWS Service Connector 将你的 AWS Container Registry 与远程 ECR 注册中心关联起来。

方式二：AWS Service Connector（推荐）

AWS Service Connector 为 ECR 访问带来了自动配置（auto-configuration）、本地登录（local login）、更优的长期凭据安全实践、细粒度访问控制以及跨多个 Stack 组件复用同一凭据等能力。

第 1 步：注册 AWS Service Connector

如果你尚未在 ZenML 部署中配置任何 AWS Service Connector，可以运行交互式 CLI 命令进行注册，并选择配置为仅访问 ECR 注册中心或同时访问多种 AWS 资源：

zenml service-connector register --type aws -i

利用本地机器上已有的 AWS CLI 配置 自动配置一个面向 ECR 注册中心的 AWS Service Connector 的非交互式示例：

zenml service-connector register <CONNECTOR_NAME> --type aws --resource-type docker-registry --auto-configure

示例命令输出：

$ zenml service-connector register aws-us-east-1 --type aws --resource-type docker-registry --auto-configure ⠸ Registering service connector 'aws-us-east-1'... Successfully registered service connector `aws-us-east-1` with access to the following resources: ┏━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ RESOURCE TYPE │ RESOURCE NAMES ┃ ┠────────────────────┼──────────────────────────────────────────────┨ ┃ 🐳 docker-registry │ 715803424590.dkr.ecr.us-east-1.amazonaws.com ┃ ┗━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

注意：请务必为 AWS 凭据对应的实体授予对目标 ECR 仓库的读写权限，以及列举可访问 ECR 仓库的权限。AWS Service Connector 支持多种安全性与便捷性不同的认证方法，请选择最适合你场景的一种。

第 2 步：查看可用的 Service Connector 资源

若已配置一个或多个 AWS Service Connector，可以查看其中哪些可用于访问你目标 ECR 注册中心：

zenml service-connector list-resources --connector-type aws --resource-type docker-registry

示例命令输出：

The following 'docker-registry' resources can be accessed by service connectors that you have configured: ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ CONNECTOR ID │ CONNECTOR NAME │ CONNECTOR TYPE │ RESOURCE TYPE │ RESOURCE NAMES ┃ ┠──────────────────────────────────────┼─────────────────────────┼────────────────┼────────────────────┼──────────────────────────────────────────────┨ ┃ 37c97fa0-fa47-4d55-9970-e2aa6e1b50cf │ aws-secret-key │ 🔶 aws │ 🐳 docker-registry │ 715803424590.dkr.ecr.us-east-1.amazonaws.com ┃ ┠──────────────────────────────────────┼─────────────────────────┼────────────────┼────────────────────┼──────────────────────────────────────────────┨ ┃ d400e0c6-a8e7-4b95-ab34-0359229c5d36 │ aws-us-east-1 │ 🔶 aws │ 🐳 docker-registry │ 715803424590.dkr.ecr.us-east-1.amazonaws.com ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

第 3 步：注册 AWS Container Registry 并连接 Service Connector

确定好用于连接目标 ECR 注册中心的 AWS Service Connector 后，注册 AWS Container Registry 并通过 Service Connector 建立关联：

# 注册 AWS container registry 并指定目标 ECR 注册中心 URI zenml container-registry register <CONTAINER_REGISTRY_NAME> -f aws \ --uri=<REGISTRY_URL> # 通过 AWS Service Connector 将 AWS container registry 连接到目标 ECR 注册中心 zenml container-registry connect <CONTAINER_REGISTRY_NAME> -i

非交互式连接方式（按 connector ID 指定）：

zenml container-registry connect <CONTAINER_REGISTRY_NAME> --connector <CONNECTOR_ID>

示例命令输出：

$ zenml container-registry connect aws-us-east-1 --connector aws-us-east-1 Successfully connected container registry `aws-us-east-1` to the following resources: ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ CONNECTOR ID │ CONNECTOR NAME │ CONNECTOR TYPE │ RESOURCE TYPE │ RESOURCE NAMES ┃ ┠──────────────────────────────────────┼────────────────┼────────────────┼────────────────────┼──────────────────────────────────────────────┨ ┃ d400e0c6-a8e7-4b95-ab34-0359229c5d36 │ aws-us-east-1 │ 🔶 aws │ 🐳 docker-registry │ 715803424590.dkr.ecr.us-east-1.amazonaws.com ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

第 4 步：将 AWS Container Registry 加入 ZenML Stack

# 注册并设置包含新容器注册中心的 Stack zenml stack register <STACK_NAME> -c <CONTAINER_REGISTRY_NAME> ... --set

提示：将 AWS Container Registry 与 Service Connector 关联后，你的本地 Docker 客户端将不再自动认证到远程注册中心。如果仍需要通过 Docker CLI 手动操作远程注册中心，可以使用 Service Connector 的 local login 功能临时为本地 Docker 客户端完成认证：

zenml service-connector login <CONNECTOR_NAME> --resource-type docker-registry

示例命令输出：

$ zenml service-connector login aws-us-east-1 --resource-type docker-registry ⠼ Attempting to configure local client using service connector 'aws-us-east-1'... 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 'aws-us-east-1' Docker Service Connector was used to successfully configure the local Docker/OCI container registry client/SDK.

底层原理：ECS 客户端与凭据解析

理解 Service Connector 如何驱动 ECR，有助于排查认证类问题。AWSContainerRegistry._get_ecr_client（见 aws_container_registry.py）的客户端构造逻辑为：

1. 若该注册中心配置了 connector，则通过Client().get_service_connector(...)获取 connector 模型，实例化AWSServiceConnector并调用其get_ecr_client()返回经 Service Connector 认证的 ECR 客户端；
2. 否则回退到boto3.Session().client("ecr", region_name=...)，即直接使用本地 AWS 凭据（对应文档中的 Local Authentication 方式）。

AWSServiceConnector.get_ecr_client的实现位于 aws_service_connector.py，它按DOCKER_REGISTRY_RESOURCE_TYPE资源类型装配客户端，与 flavor 声明的 Service Connector 需求一一对应。这意味着：只要zenml container-registry connect成功，流水线构建镜像时就会自动使用 connector 提供的短期凭据，无需在 Docker 中手工 login。

小结与延伸

至此，你已完成 ZenML 接入 Amazon ECR 的完整闭环：创建 ECR 私有仓库 → 拼接注册中心 URI → 安装awsintegration 并注册awsflavor 的 Container Registry → 通过本地认证或（推荐的）AWS Service Connector 完成认证 → 将组件挂载进 ZenML Stack 并交付给 orchestrator / step operator 使用。

关键要点回顾：

进一步阅读：本文所依托的原始组件文档为 docs/book/component-guide/container-registries/aws.md，完整 flavor 列表可参考 容器注册中心总览；AWS integration 的其余组件（SageMaker orchestrator、SageMaker step operator、AWS image builder、AWS deployer）实现位于 src/zenml/integrations/aws/ 目录下，可供继续深入。

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml