AWS SDK for Java 2.x 实战：Amazon ECR 仓库全生命周期管理入门场景

示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载Amazon ECRElastic Container Registry是 AWS 提供的一项完全托管的 Docker 容器镜像注册服务。本技术指南以 scenarios/basics/ecr/SPECIFICATION.md 为骨架围绕该仓库中ECR Getting Started Scenario的工程规范展开说明如何使用 AWS SDK for Java 2.x 的EcrAsyncClient完成从创建仓库、设置仓库策略、获取授权令牌、推送镜像、验证镜像到最终清理资源的完整流程。读完本文你将掌握 ECR 仓库管理的十余个核心 API 调用方式、与 Docker Clientdocker-java的集成手法以及如何准备本地测试镜像并驱动整个场景运行。场景背景与资源要求场景定位该 SDK 入门场景的目标是让不熟悉 Amazon ECR 的开发者快速上手其核心演示逻辑是ecrClient.listImagesPaginator()Hello 程序并在完整场景中以创建仓库 → 策略管理 → 令牌与 URI → 生命周期策略 → 推送镜像 → 验证 → 清理为主线展示与 ECR 交互的标准姿势。场景对应的语言实现包括 Java、Python、Kotlin本文以仓库中已落地的 Java 2.x 实现为准。必备资源按 SPECIFICATION.md 的 Resources 一节运行本场景需要两类资源IAM 角色必须具有与 ECR 服务交互的权限例如ecr:PutImage。创建 IAM 角色可参考 AWS IAM 文档见原规范中的外链此处不再重复输出关于 ECR 与 IAM 的配合方式如身份策略的编写可参考 javav2/example_code/ecr/README.md 中给出的指引。本地 Docker 镜像名为echo-text的本地镜像若缺失程序会直接退出见下文。此外场景通过某编程语言的 Docker 客户端 APIJava 侧使用 docker-java与本地 Docker 守护进程通信SDK 层面仅负责 ECR 的控制面操作。准备本地 Docker 镜像echo-text场景要求本地存在名为echo-text的镜像仓库在 scenarios/basics/ecr/README.md 中给出了完整的构建步骤且配套资源文件真实存在于 scenarios/basics/ecr/resourcesDockerfile基于alpine:latest将hello.sh复制到/app并设置为可执行容器启动命令为./hello.shhello.sh内容为#!/bin/shecho Hello There!。构建与运行命令docker build -t echo-text . docker run echo-textdocker run echo-text会输出Hello There!说明本地镜像可用。这一前置步骤不可跳过场景源码 ECRScenario.java 在创建仓库前会调用ecrActions.isEchoTextImagePresent()检查本地镜像是否存在若不存在则直接return终止程序。Hello Amazon ECR第一个 API 调用在进入完整场景前规范单独定义了一个 Hello 程序面向不熟悉 ECR SDK 的开发者用于演示ecrClient.listImagesPaginator()的使用。其控制台输出为The docker image tag is latest该程序对应的 Java 示例入口是 javav2/example_code/ecr/src/main/java/com/example/ecr/HelloECR.javalistImages。它通过分页器遍历仓库中的镜像并打印镜像标签是理解 ECR 镜像列表 API 的最小范例。场景程序流程全景程序入口与参数解析运行 ECRScenario.java 需要恰好两个命令行参数iamRoleARN具备 ECR 访问与管理权限的 IAM 角色 ARNaccountId你的 AWS 账号号。源码中的 usage 文本如下Usage: iamRoleARN accountId参数数量不符时程序打印 usage 并退出。进入主流程后程序会先给出 ECR 与EcrAsyncClient的介绍文案并让用户二选一输入1运行完整场景输入2仅删除上一次未完成执行留下的echo-text仓库调用deleteECRRepository后退出。这种设计让场景具备可重入性避免残留仓库阻塞后续运行。十个核心步骤对应规范 Scenario Program Flow规范中列出的完整执行步骤依次为解析命令行参数校验iamRoleARN与accountId两个参数介绍 Amazon ECR输出服务简介检查本地 Docker 镜像确认名为echo-text的本地镜像存在不存在则程序结束创建 ECR 仓库通过createECRRepository方法创建设置仓库策略通过setRepoPolicy将指定 IAM 角色授权为可访问仓库展示仓库策略通过getRepoPolicy检索并打印策略获取授权令牌通过getAuthToken获取 ECR 授权令牌供后续操作使用获取仓库 URI通过getRepositoryURI获取仓库地址设置生命周期策略通过setLifeCyclePolicy自动清理旧镜像推送 Docker 镜像通过 Docker Client 将本地镜像推送到 ECR规范明确说明不推荐直接用 ECRClient 上传镜像数据验证镜像入库通过verifyImage确认镜像已成功推送可选运行镜像向用户展示如何用 CLI 运行仓库中的镜像删除 ECR 仓库询问用户后通过deleteECRRepository清理仓库及其内容。控制台交互与运行输出解析规范给出了完整场景的逐步控制台输出见 SPECIFICATION.md 的 Program execution 小节其交互模式为每个阶段前打印说明文案等待用户输入cENTER继续。这由源码中的waitForInputToContinue(Scanner)私有方法实现ECRScenario.java输入非c会提示 Invalid input. Please try again.。关键输出片段逐段解读如下。步骤 1 — 创建仓库echo-text:latest The local image named echo-text exists. ECR repository already exists, moving on... The ARN of the ECR repository is arn:aws:ecr:us-east-1:1234567890:repository/echo-text注意输出中的 ECR repository already exists 对应 ECRActions.java 对RepositoryAlreadyExistsException的兜底处理当创建请求抛出该异常时改为调用describeRepositories获取既有仓库的 ARN 并继续执行而非直接失败。步骤 3 — 展示仓库策略检索到策略原文如下授权主体为传入的 IAM 角色动作仅限ecr:BatchGetImage{ Version : 2012-10-17, Statement : [ { Sid : new statement, Effect : Allow, Principal : { AWS : arn:aws:iam::1234567890:role/Admin }, Action : ecr:BatchGetImage } ] }步骤 4 — 获取授权令牌输出The token was successfully retrieved.。该令牌由 getAuthToken 调用getAuthorizationToken()获取返回的authorizationData中的authorizationToken即为后续 Docker 登录所需的凭证。步骤 5 — 获取仓库 URIThe repository URI is 1234567890.dkr.ecr.us-east-1.amazonaws.com/echo-text仓库 URI 由 getRepositoryURI 通过describeRepositories获取格式为accountId.dkr.ecr.region.amazonaws.com/repoName。步骤 6 — 设置生命周期策略输出Lifecycle policy preview started successfully.表明调用了startLifecyclePolicyPreviewAPI。步骤 7 — 推送镜像Pushing echo-text will take a few seconds The echo-text image was pushed to ECR步骤 8 — 验证镜像输出Image is present in the repository.步骤 9 — 可选 CLI 交互用户选择y后程序打印三条 CLI 命令aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 1234567890.dkr.ecr.us-east-1.amazonaws.com aws ecr describe-images --repository-name echo-text --image-ids imageTagecho-text docker run --rm 1234567890.dkr.ecr.us-east-1.amazonaws.com/echo-text这些命令分别完成向 ECR 注册表登录、查看镜像详情、直接运行仓库中的容器。命令中的账号与仓库名由String.format用运行参数动态填充ECRScenario.java。步骤 10 — 删除仓库用户确认y后调用deleteECRRepository输出You have successfully deleted the repository随后场景以分隔线收尾。源码级剖析ECRActions 的核心实现所有动作封装在 ECRActions.java 中。该类同时持有EcrAsyncClientECR 控制面与DockerClientdocker-java镜像数据面两个客户端值得逐一剖析。异步 ECR 客户端构造getAsyncClient()ECRActions.java展示了 AWS SDK for Java 2.x 异步客户端的推荐配置方式使用NettyNioAsyncHttpClient作为底层 HTTP 客户端设置maxConcurrency(50)、连接/读/写超时各 60 秒通过ClientOverrideConfiguration设置apiCallTimeout2 分钟与apiCallAttemptTimeout90 秒客户端绑定Region.US_EAST_1单例复用。这意味着场景所有 ECR 调用都走异步接口并以CompletableFuture编排、join()同步等待异常通过CompletionException包装后由调用方按EcrException细分处理。Docker 客户端构造与平台差异getDockerClient()ECRActions.java根据操作系统分支处理Windows显式连接tcp://localhost:2375Docker Desktop 默认端口使用NettyDockerCmdExecFactory并设置读写/连接超时 20 秒其他系统DockerClientBuilder.getInstance().build()使用默认 Docker 环境Unix socket。仓库策略设置setRepoPolicyECRActions.java以 IAM 角色 ARN 为参数将角色填充进策略模板的Principal.AWS字段再调用setRepositoryPolicy。其异常处理覆盖RepositoryPolicyNotFoundException与EcrException两种类型。生命周期策略文本setLifeCyclePolicyECRActions.java内置了规范的策略 JSON规则为过期 14 天前推送的任意镜像{ rules: [ { rulePriority: 1, description: Expire images older than 14 days, selection: { tagStatus: any, countType: sinceImagePushed, countUnit: days, countNumber: 14 }, action: { type: expire } } ] }其 API 调用为startLifecyclePolicyPreview先启动预览这正是 SOS 元数据表中ecr_LifecyclePolicyPreview对应的动作。镜像推送docker-java 与 ECR 的集成pushDockerImageECRActions.java是最复杂的部分完整链路为异步调用getAuthorizationToken()获取令牌Base64 解码令牌截取第 4 个字符之后的内容作为密码解码结果前缀为AWS:故substring(4)去除该前缀通过describeRepositories得到仓库 URI取其域名部分repositoryUri().split(/)[0]作为注册表地址构造 docker-java 的AuthConfig用户名固定为AWS密码为解码后的令牌注册表地址为上述域名用tagImageCmd将本地镜像打上仓库URI:latest的标签用pushImageCmd携带AuthConfig推送镜像。这一设计印证了规范中的提示上传镜像数据应使用 Docker Client而不是 ECRClient——ECR SDK 只负责获取凭据与元数据镜像 blob 的传输交给 Docker 协议完成。镜像验证verifyImageECRActions.java构造DescribeImagesRequest携带ImageIdentifier(imageTag)调用describeImages若返回的imageDetails非空则打印 Image is present in the repository.否则提示镜像不存在。本地镜像检测isEchoTextImagePresentECRActions.java通过 docker-java 的listImagesCmd遍历本地镜像检查 RepoTags 中是否有以echo-text开头的标签遇到DockerClientException如 Docker 未启动会记录日志并返回false。测试与验证场景配套测试位于 javav2/example_code/ecr/src/test/java/ECRTest.java采用 JUnit 5 的TestMethodOrder(MethodOrderer.OrderAnnotation.class)按序执行核心断言testScenario依次对createECRRepository、setRepoPolicy、getRepoPolicy、getAuthToken、getRepositoryURI、setLifeCyclePolicy、pushDockerImage等动作执行assertDoesNotThrow即要求整条动作链在真实 AWS 环境中不抛异常。这与规范的 SOS 元数据表一一对应。SOS 元数据对照规范末尾的 SOS Tags 表格将场景中每个动作与ecr_metadata.yaml的元数据键绑定用于文档系统自动化检索完整对照如下动作元数据文件元数据键deleteRepositoryecr_metadata.yamlecr_DeleteRepositorydescribeImagesecr_metadata.yamlecr_DescribeImagesstartLifecyclePolicyPreviewecr_metadata.yamlecr_LifecyclePolicyPreviewdescribeRepositoriesecr_metadata.yamlecr_DescribeRepositoriesgetAuthorizationTokenecr_metadata.yamlecr_GetAuthorizationTokengetRepositoryPolicyecr_metadata.yamlecr_GetRepositoryPolicysetRepositoryPolicyecr_metadata.yamlecr_SetRepositoryPolicycreateRepositoryecr_metadata.yamlecr_CreateRepositoryPutImageecr_metadata.yamlecr_PutImagelistImagesPaginatorecr_metadata.yamlecr_Helloscenarioecr_metadata.yamlecr_Scenario这些键名如ecr_Hello、ecr_Scenario与 javav2/example_code/ecr/README.md 中 Hello Amazon ECR 与 Learn the basics 两个代码块的组织方式相呼应前者指向HelloECR.java的listImages后者指向ECRScenario.java。运行前提与注意事项综合规范与源码运行该场景需要满足配置好 AWS 凭证与开发环境按 javav2/example_code/ecr/README.md 所述前置条件可参考javav2目录的 README本地安装 Docker 并确保守护进程可用否则isEchoTextImagePresent会返回false程序直接退出先构建echo-text镜像执行docker build -t echo-text .准备具有 ECR 权限的 IAM 角色并取得其 ARN 与账号 ID注意区域一致性源码中EcrAsyncClient固定使用Region.US_EAST_1ECRActions.java若你的凭证/资源在其他区域需相应调整收费提醒运行场景与测试可能产生 AWS 费用且建议遵循最小权限原则仅授予任务所需权限如ecr:PutImage。整体而言该场景以控制面用EcrAsyncClient、数据面用 Docker Client的分层思想覆盖了 ECR 仓库从创建、授权、推送、验证到清理的完整闭环可作为接入 ECR 的最佳实践模板直接迁移到生产项目。赞分享示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载相关推荐基于 AWS SDK for Java 2.x 的 Amazon OpenSearch Service 域生命周期管理实战指南aws-doc-sdk-examples Basics 场景全解析基于 AWS SDK for Java 2.x 的 Amazon OpenSearch Service 域生命周期管理实战指南aws doc sdk exam示例工程教程后端Amazon RDS 的 Java 2.x SDK 实战从 Hello RDS 到完整数据库生命周期场景Amazon RDS 的 Java 2.x SDK 实战从 Hello RDS 到完整数据库生命周期场景 本文基于 AWS 官方代码示例仓库aws doc示例工程教程后端AWS CodePipeline 的 Java V2 实战指南基于 AWS SDK for Java 2.x 管理流水线生命周期AWS CodePipeline 的 Java V2 实战指南基于 AWS SDK for Java 2.x 管理流水线生命周期 本指南围绕 aws doc示例工程教程后端上一篇ComfyUI ReActor换脸插件高效AI面部替换完整指南下一篇NS-USBloader一站式解决Switch文件传输的终极工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考