本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 为 Amazon EMR on EKS 自定义 Docker 镜像 您可以使用 Amazon EMR on EKS 自定义 Docker 镜像。自定义 Amazon EMR on EKS 运行时的镜像具有以下优势： + 将应用程序依赖项和运行时环境打包到单个不可改变容器中，以提高可移植性并简化每个工作负载的依赖项管理。 + 安装并配置针对您的工作负载进行优化的软件包。这些软件包可能不会在 Amazon EMR 运行时的公开分配中广泛使用。 + 将 Amazon EMR on EKS 与组织中当前建立的构建、测试和部署流程（包括本地开发和测试）集成在一起。 + 应用已建立的安全过程（如镜像扫描），以满足组织内的合规性和监管要求。 **Topics** + [如何自定义 Docker 镜像](docker-custom-images-steps.md) + [如何选择基础映像 URI 的详细信息](docker-custom-images-tag.md) + [自定义映像的注意事项](docker-custom-images-considerations.md) # 如何自定义 Docker 镜像 请按照以下步骤为 Amazon EMR on EKS 自定义 Docker 映像。这些步骤展示了如何获取基础映像、自定义和发布映像，以及如何使用映像提交工作负载。 + [先决条件](#docker-custom-images-prereq) + [步骤 1：从 Amazon Elastic Container Registry（Amazon ECR）中检索基础镜像](#docker-custom-images-retrieve) + [步骤 2：自定义基础镜像](#docker-custom-images-customize) + [步骤 3：（可选但建议）验证自定义镜像](#docker-custom-images-validate) + [步骤 4：发布自定义镜像](#docker-custom-images-publish) + [步骤 5：使用自定义镜像在 Amazon EMR 中提交 Spark 工作负载](#docker-custom-images-submit) **注意** 在自定义 Docker 映像时，可能要考虑的其他选项包括为交互式端点进行自定义（以确保拥有所需的依赖项），或使用多架构容器映像： [为交互式端点自定义 Docker 映像](docker-custom-images-managed-endpoint.md) [使用多架构镜像](docker-custom-images-multi-architecture.md) ## 先决条件 + 请完成 Amazon EMR on EKS 的[设置 Amazon EMR on EKS](setting-up.md)步骤。 + 在您的环境中安装 Docker。有关更多信息，请参阅[获取 Docker](https://docs.docker.com/get-docker/)。 ## 步骤 1：从 Amazon Elastic Container Registry（Amazon ECR）中检索基础镜像 基础映像包含用于访问其他 AWS 服务的 Amazon EMR 运行时系统和连接器。对于 Amazon EMR 6.9.0 及更高版本，您可以从 Amazon ECR Public Gallery 获取基础映像。浏览图库以找到映像链接，然后将映像拉到本地工作区。例如，对于 Amazon EMR 7.12.0 版本，以下`docker pull`命令将为您提供最新的标准基础映像。您可以将 `emr-7.12.0:latest` 替换为 `emr-7.12.0-spark-rapids:latest`，检索带 Nvidia RAPIDS Accelerator 的映像。您也可以将 `emr-7.12.0:latest` 替换为 `emr-7.12.0-java11:latest`，使用 Java 11 运行时系统检索映像。 ``` docker pull public.ecr.aws/emr-on-eks/spark/emr-7.12.0:latest ``` 如果您想检索 Amazon EMR 6.9.0 或更早版本的基础映像，或者如果您希望从每个区域中的 Amazon ECR 注册账户中检索，请使用以下步骤： 1. 选择基础镜像 URI。镜像 URI 遵循格式（`ECR-registry-account.dkr.ecr.Region.amazonaws.com/spark/container-image-tag`），示例如下。 ``` 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest ``` 要选择您所在区域的基础镜像，请参阅[如何选择基础映像 URI 的详细信息](docker-custom-images-tag.md)。 1. 登录存储基础镜像的 Amazon ECR 存储库。用 Amazon ECR 注册账户和您选择的 AWS 地区替换*895885662937*和。*us-west-2* ``` aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 895885662937.dkr.ecr.us-west-2.amazonaws.com ``` 1. 将基础镜像拉入本地 Workspace。*emr-6.6.0:latest*替换为您选择的容器镜像标签。 ``` docker pull 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest ``` ## 步骤 2：自定义基础镜像 请按照以下步骤自定义您从 Amazon ECR 中拉取的基础映像。 1. 在您的本地 Workspace 上创建新的 `Dockerfile`。 1. 编辑您刚刚创建的 `Dockerfile` 并添加以下内容。该 `Dockerfile` 使用您从 `895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest` 中提取的容器镜像。 ``` FROM 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest USER root ### Add customization commands here #### USER hadoop:hadoop ``` 1. 将命令添加到 `Dockerfile` 以自定义基础镜像。例如，添加命令来安装 Python 库，如以下 `Dockerfile` 所示。 ``` FROM 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest USER root RUN pip3 install --upgrade boto3 pandas numpy // For python 3 USER hadoop:hadoop ``` 1. 在创建 `Dockerfile` 的同一目录中，请运行以下命令构建 Docker 镜像。提供 Docker 镜像的名称，*emr6.6\$1custom*例如。 ``` docker build -t emr6.6_custom . ``` ## 步骤 3：（可选但建议）验证自定义镜像 我们建议您在发布自定义镜像之前测试它的兼容性。您可以使用 [Amazon EMR on EKS 自定义镜像 CLI ](https://github.com/awslabs/amazon-emr-on-eks-custom-image-cli)检查您的镜像是否具有在 Amazon EMR on EKS 上运行所需要的文件结构和正确配置。 **注意** Amazon EMR on EKS 的自定义镜像 CLI 无法确认您的镜像没有错误。在删除基础镜像的依赖项时要格外小心。 可以执行以下步骤，验证您的自定义镜像。 1. 下载并安装 Amazon EMR on EKS 自定义镜像 CLI。有关更多信息，请参阅 [Amazon EMR on EKS 自定义镜像 CLI 安装指南](https://github.com/awslabs/amazon-emr-on-eks-custom-image-cli/blob/main/installer/assets/INSTALLATION_GUIDE.md)。 1. 运行以下命令以测试安装。 ``` emr-on-eks-custom-image --version ``` 下面是此类输出的示例。 ``` Amazon EMR on EKS Custom Image CLI Version: x.xx ``` 1. 运行以下命令以验证您的自定义镜像。 ``` emr-on-eks-custom-image validate-image -i image_name -r release_version [-t image_type] ``` + `-i` 指定需要验证的本地镜像 URI。它可以是镜像 URI，也可以是为镜像定义的任何名称或标签。 + `-r` 为基础镜像指定确切的发布版本，例如 `emr-6.6.0-latest`。 + `-t` 指定镜像类型。如果这是 Spark 镜像，请输入 `spark`。默认值为 `spark`。当前 Amazon EMR on EKS 自定义镜像 CLI 版本仅支持 Spark 运行时镜像。 如果您成功运行命令并且自定义镜像满足所有必需的配置和文件结构，则返回的输出会显示所有测试结果，如以下示例所示。 ``` Amazon EMR on EKS Custom Image Test Version: x.xx ... Checking if docker cli is installed ... Checking Image Manifest [INFO] Image ID: xxx [INFO] Created On: 2021-05-17T20:50:07.986662904Z [INFO] Default User Set to hadoop:hadoop : PASS [INFO] Working Directory Set to /home/hadoop : PASS [INFO] Entrypoint Set to /usr/bin/entrypoint.sh : PASS [INFO] SPARK_HOME is set with value: /usr/lib/spark : PASS [INFO] JAVA_HOME is set with value: /etc/alternatives/jre : PASS [INFO] File Structure Test for spark-jars in /usr/lib/spark/jars: PASS [INFO] File Structure Test for hadoop-files in /usr/lib/hadoop: PASS [INFO] File Structure Test for hadoop-jars in /usr/lib/hadoop/lib: PASS [INFO] File Structure Test for bin-files in /usr/bin: PASS ... Start Running Sample Spark Job [INFO] Sample Spark Job Test with local:///usr/lib/spark/examples/jars/spark-examples.jar : PASS ----------------------------------------------------------------- Overall Custom Image Validation Succeeded. ----------------------------------------------------------------- ``` 如果自定义镜像不满足所需的配置或文件结构，则会出现错误消息。返回的输出提供了错误配置或文件结构相关信息。 ## 步骤 4：发布自定义镜像 将新的 Docker 镜像发布到您的 Amazon ECR 注册表。 1. 运行以下命令创建用于存储 Docker 镜像的 Amazon ECR 存储库。为仓库提供一个名称，例如*emr6.6\$1custom\$1repo*。将 *us-west-2* 替换为您的区域。 ``` aws ecr create-repository \ --repository-name emr6.6_custom_repo \ --image-scanning-configuration scanOnPush=true \ --region us-west-2 ``` 有关更多信息，请参阅《Amazon ECR 用户指南》**中的[创建存储库](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html#cli-create-repository)。 1. 运行以下命令对您的默认注册表进行身份验证。 ``` aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.us-west-2.amazonaws.com ``` 有关更多信息，请参阅《Amazon ECR 用户指南》**中的[对您的默认注册表进行身份验证](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html#cli-authenticate-registry)。 1. 标记镜像并将其发布到您创建的 Amazon ECR 存储库。 标记镜像。 ``` docker tag emr6.6_custom aws_account_id.dkr.ecr.us-west-2.amazonaws.com/emr6.6_custom_repo ``` 推送镜像。 ``` docker push aws_account_id.dkr.ecr.us-west-2.amazonaws.com/emr6.6_custom_repo ``` 有关更多信息，请参阅*《Amazon ECR 用户指南》*中的[将镜像推送到 Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html#cli-push-image)。 ## 步骤 5：使用自定义镜像在 Amazon EMR 中提交 Spark 工作负载 构建和发布自定义镜像后，您可以使用自定义镜像提交 Amazon EMR on EKS 任务。 首先，创建一个 start-job-run-request .json 文件并指定引用自定义图像的`spark.kubernetes.container.image`参数，如以下示例 JSON 文件所示。 **注意** 您可以使用 `local://` 方案来引用自定义镜像中的可用文件，如下面所示的 JSON 片段中的 `entryPoint` 参数。您也可以使用 `local://` 方案来引用应用程序依赖项。使用 `local://` 方案引用的所有文件和依赖项必须已存在于自定义镜像的指定路径。 ``` { "name": "spark-custom-image", "virtualClusterId": "virtual-cluster-id", "executionRoleArn": "execution-role-arn", "releaseLabel": "emr-6.6.0-latest", "jobDriver": { "sparkSubmitJobDriver": { "entryPoint": "local:///usr/lib/spark/examples/jars/spark-examples.jar", "entryPointArguments": [ "10" ], "sparkSubmitParameters": "--class org.apache.spark.examples.SparkPi --conf spark.kubernetes.container.image=123456789012.dkr.ecr.us-west-2.amazonaws.com/emr6.6_custom_repo" } } } ``` 您还可以使用 `applicationConfiguration` 属性来引用自定义映像，如以下示例所示。 ``` { "name": "spark-custom-image", "virtualClusterId": "virtual-cluster-id", "executionRoleArn": "execution-role-arn", "releaseLabel": "emr-6.6.0-latest", "jobDriver": { "sparkSubmitJobDriver": { "entryPoint": "local:///usr/lib/spark/examples/jars/spark-examples.jar", "entryPointArguments": [ "10" ], "sparkSubmitParameters": "--class org.apache.spark.examples.SparkPi" } }, "configurationOverrides": { "applicationConfiguration": [ { "classification": "spark-defaults", "properties": { "spark.kubernetes.container.image": "123456789012.dkr.ecr.us-west-2.amazonaws.com/emr6.6_custom_repo" } } ] } } ``` 然后运行 `start-job-run` 命令提交任务。 ``` aws emr-containers start-job-run --cli-input-json file://./start-job-run-request.json ``` 在上面的 JSON 示例中，*emr-6.6.0-latest*替换为您的 Amazon EMR 发行版。我们强烈建议您使用 `-latest` 发布版本，以确保所选版本包含最新的安全更新。有关 Amazon EMR 发行版本和相应映像标签的更多信息，请参阅 [如何选择基础映像 URI 的详细信息](docker-custom-images-tag.md)。 **注意** 您可以使用 `spark.kubernetes.driver.container.image` 和 `spark.kubernetes.executor.container.image` 为驱动程序和执行程序 Pod 指定不同的镜像。 # 为交互式端点自定义 Docker 映像 您还可以为交互式端点自定义 Docker 映像，以便运行自定义的基础内核映像。这有助于确保在从 EMR Studio 运行交互式工作负载时拥有所需的依赖项。 1. 按照上述[第 1-4 步](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/docker-custom-images-steps.html#docker-custom-images-retrieve)进行操作，以自定义 Docker 镜像。对于 Amazon EMR 6.9.0 版本及更高版本，您可以从 Amazon ECR Public Gallery 获取基础映像 URI。对于 Amazon EMR 6.9.0 之前的版本，您可以在每个 AWS 区域的 Amazon ECR 注册账户中获取映像，唯一的区别是 Dockerfile 中的基础映像 URI。基础映像 URI 遵循以下格式： ``` ECR-registry-account.dkr.ecr.Region.amazonaws.com/notebook-spark/container-image-tag ``` 您需要在基本镜像 URI 中使用 `notebook-spark`，而不是 `spark`。基本镜像包含 Spark 运行时，以及随之运行的 Notebook 内核。有关选择区域和容器镜像标签的更多信息，请参阅 [如何选择基础映像 URI 的详细信息](docker-custom-images-tag.md)。 **注意** 目前仅支持基础映像的替换，并且不支持引入除基础映像 AWS 提供的其他类型的全新内核。 1. 创建可与自定义映像配合使用的交互式端点。 首先，使用以下内容创建名为 `custom-image-managed-endpoint.json` 的 JSON 文件。 ``` { "name": "endpoint-name", "virtualClusterId": "virtual-cluster-id", "type": "JUPYTER_ENTERPRISE_GATEWAY", "releaseLabel": "emr-6.6.0-latest", "executionRoleArn": "execution-role-arn", "certificateArn": "certificate-arn", "configurationOverrides": { "applicationConfiguration": [ { "classification": "jupyter-kernel-overrides", "configurations": [ { "classification": "python3", "properties": { "container-image": "123456789012.dkr.ecr.us-west-2.amazonaws.com/custom-notebook-python:latest" } }, { "classification": "spark-python-kubernetes", "properties": { "container-image": "123456789012.dkr.ecr.us-west-2.amazonaws.com/custom-notebook-spark:latest" } } ] } ] } } ``` 然后，使用该 JSON 文件中指定的配置创建交互式端点，如以下示例所示。 ``` aws emr-containers create-managed-endpoint --cli-input-json custom-image-managed-endpoint.json ``` 有关更多信息，请参阅[为虚拟集群创建交互式端点](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-studio-create-eks-cluster.html#emr-studio-create-managed-endpoint)。 1. 通过 EMR Studio 连接到交互式端点。有关更多信息，请参阅[从 Studio 连接](https://emr-on-eks.workshop.aws/advanced/emr-studio/connecting-from-studio.html)。 # 使用多架构镜像 Amazon EMR on EKS 支持适用于 Amazon Elastic Container Registry (Amazon ECR) 的多架构容器镜像。有关更多信息，请参阅[适用于 Amazon ECR 的多架构容器镜像简介](https://aws.amazon.com/blogs/containers/introducing-multi-architecture-container-images-for-amazon-ecr/)。 EKS 上的 Amazon EMR 自定义映像同时支持 AWS 基于 Graviton 的 EC2 实例和 EC2 实例。 non-Graviton-based基于 Graviton 的图像与图像存储在 Amazon ECR 中的相同图像存储库中。 non-Graviton-based 例如，要检查 Docker 清单列表中是否有 6.6.0 镜像，请运行下面的命令。 ``` docker manifest inspect 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest ``` 下面是输出。`arm64` 架构适用于 Graviton 实例。`amd64` 适用于非 Graviton 实例。 ``` { "schemaVersion": 2, "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", "manifests": [ { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 1805, "digest": "xxx123:6b971cb47d11011ab3d45fff925e9442914b4977ae0f9fbcdcf5cfa99a7593f0", "platform": { "architecture": "arm64", "os": "linux" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 1805, "digest": "xxx123:6f2375582c9c57fa9838c1d3a626f1b4fc281e287d2963a72dfe0bd81117e52f", "platform": { "architecture": "amd64", "os": "linux" } } ] } ``` 请执行以下步骤以创建多架构镜像： 1. 创建包含以下内容的 `Dockerfile`，以便您能拉取 `arm64` 映像。 ``` FROM --platform=arm64 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-6.6.0:latest USER root RUN pip3 install boto3 // install customizations here USER hadoop:hadoop ``` 1. 按照[适用于 Amazon ECR 的多架构容器镜像简介](https://aws.amazon.com/blogs/containers/introducing-multi-architecture-container-images-for-amazon-ecr/)中的说明操作，构建一个多架构镜像。 **注意** 您必须在 `arm64` 实例上创建 `arm64` 映像。同样，您必须在 `amd64` 实例上构建 `amd64` 映像。 您还可以使用 Docker `buildx` 命令构建多架构映像，而无需基于每种特定实例类型上进行构建。有关更多信息，请参阅[利用多 CPU 架构支持](https://docs.docker.com/desktop/multi-arch/)。 1. 构建多架构镜像后，您可以使用相同的 `spark.kubernetes.container.image` 参数并指向该映像来提交任务。在同时包含 AWS 基于 Graviton 和 non-Graviton-based EC2 的实例的异构集群中，该实例根据提取映像的实例架构确定正确的架构映像。 # 如何选择基础映像 URI 的详细信息 **注意** 对于 Amazon EMR 6.9.0 版本及更高版本，您可以从 Amazon ECR Public Gallery 中检索基础映像，因此您无需按照本页上的说明构造基础映像 URI。要查找基础映像的容器映像标签，请参阅 Amazon EMR on EKS 相应版本的[发布说明页面](emr-eks-releases.md)。 所选基础 Docker 映像存储在 Amazon Elastic Container Registry（Amazon ECR）。镜像 URI 遵循此格式：`ECR-registry-account.dkr.ecr.Region.amazonaws.com/spark/container-image-tag`，如下面的示例所示。 ``` 895885662937.dkr.ecr.us-west-2.amazonaws.com/spark/emr-7.12.0:latest ``` 适用于交互式端点的映像 URI 遵循此格式：`ECR-registry-account.dkr.ecr.Region.amazonaws.com/notebook-spark/container-image-tag`，如以下示例所示。您需要在基本镜像 URI 中使用 `notebook-spark`，而不是 `spark`。 ``` 895885662937.dkr.ecr.us-west-2.amazonaws.com/notebook-spark/emr-7.12.0:latest ``` 同样，对于交互式端点的非 Spark `python3` 映像，映像 URI 为 `ECR-registry-account.dkr.ecr.Region.amazonaws.com/notebook-python/container-image-tag`。以下示例 URI 格式正确： ``` 895885662937.dkr.ecr.us-west-2.amazonaws.com/notebook-python/emr-7.12.0:latest ``` 要查找基础映像的容器映像标签，请参阅 Amazon EMR on EKS 相应版本的[发布说明页面](emr-eks-releases.md)。 ## 按区域划分的 Amazon ECR 注册账户 为避免高网络延迟，请从离您最近的位置提取基础映像 AWS 区域。根据下表，选择与您从中拉取映像区域对应的 Amazon ECR 注册账户。 | Regions | Amazon ECR 注册账户 | | --- | --- | | ap-east-1 | 736135916053 | | ap-northeast-1 | 059004520145 | | ap-northeast-2 | 996579266876 | | ap-northeast-3 | 705689932349 | | ap-southeast-3 | 946962994502 | | ap-south-1 | 235914868574 | | ap-south-2 | 691480105545 | | ap-southeast-1 | 671219180197 | | ap-southeast-2 | 038297999601 | | ca-central-1 | 351826393999 | | eu-central-1 | 107292555468 | | eu-central-2 | 314408114945 | | eu-north-1 | 830386416364 | | eu-west-1 | 483788554619 | | eu-west-2 | 118780647275 | | eu-west-3 | 307523725174 | | eu-south-1 | 238014973495 | | eu-south-2 | 350796622945 | | il-central-1 | 395734710648 | | me-south-1 | 008085056818 | | me-central-1 | 818935616732 | | sa-east-1 | 052806832358 | | us-gov-west-1 | 299385240661 | | us-gov-east-1 | 299393998622 | | us-east-1 | 755674844232 | | us-east-2 | 711395599931 | | us-west-1 | 608033475327 | | us-west-2 | 895885662937 | | af-south-1 | 358491847878 | | cn-north-1 | 068337069695 | | cn-northwest-1 | 068420816659 | # 自定义映像的注意事项 自定义 Docker 映像时，您可精细地选择精确的任务运行时间。使用此功能时，请考虑以下最佳实践。其中包括安全、配置和安装映像方面的注意事项： + 安全是双方共同承担 AWS 的责任。您负责对添加到映像中的二进制文件进行安全修补。按照[Amazon EMR on EKS 安全最佳实践](security-best-practices.md)中的说明操作，特别是[获取自定义镜像的最新安全更新](security-best-practices.md#security-custom-image)和[采用最低特权原则](security-best-practices.md#security-least-privilege)。 + 自定义基础映像时，请务必将 Docker 用户更改为 `hadoop:hadoop`，以确保不使用根用户运行任务。 + Amazon EMR on EKS 会在运行时将文件挂载到映像的配置之上，例如 `spark-defaults.conf`。要覆盖这些配置文件，我们建议您在提交任务期间使用 `applicationOverrides` 参数，而不是仅直接在自定义映像中修改文件。 + Amazon EMR on EKS 会在运行时挂载某些文件夹。对这些文件夹所做的任何修改都不可用于容器中。如果要为自定义映像添加应用程序或其依赖项，我们建议您选择不属于以下预定义路径的目录： + `/var/log/fluentd` + `/var/log/spark/user` + `/var/log/spark/apps` + `/mnt` + `/tmp` + `/home/hadoop` + 您可以将自定义映像上载到任何兼容 Docker 的存储库，例如 Amazon ECR、Docker Hub 或私有企业存储库。有关使用所选 Docker 存储库配置 Amazon EKS 集群身份验证的更多信息，请参阅[从私有仓库拉取镜像](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)。