为什么 Code Engine 无法拉取映像?

部署 Code Engine 应用程序或运行作业时，会收到包含 Unable to pull the image 的错误消息。

要对此问题进行故障诊断，请确认该映像是否存在以及您是否有权访问该映像。 检查是否满足以下条件。

• 要确认应用程序或作业的映像存在，请查看错误消息以获取有关失败的信息。

• 要在 Code Engine中部署应用程序或运行作业，需要首先创建具有应用程序需要运行的所有运行时工件 (例如运行时库) 的容器映像。 您可以使用许多不同的方法来 创建容器映像，包括使用 Code Engine中提供的构建容器映像功能从源代码构建应用程序。 可以从公共或专用映像注册表下载映像。 有关访问专用注册表的更多信息，请参阅 添加对专用容器注册表的访问权。

• 如果在 Code Engine CLI 中使用 ibmcloud ce app create，ibmcloud ce job create 或 ibmcloud ce jobrun submit 命令，请使用 REGISTRY/NAMESPACE/REPOSITORY:TAG 格式指定用于应用程序或作业的映像的名称，其中 REGISTRY 和 TAG 是可选的。 如果未指定 REGISTRY，那么缺省值为 docker.io. 如果未指定 TAG，那么缺省值为 latest。 请查看这些命令，以获取有关用于指定映像注册表的格式的更多信息。

请尝试以下解决方案来解决您的问题。

1. 您未获授权。 如果您没有访问所引用映像的许可权，那么应用程序创建将不会完成，并且会发生错误。 您接收到包含 Unable to pull 图像的错误消息。

   • 要确认您可以访问引用的映像，请验证映像的位置，并确认您具有访问该映像的许可权。

   • 如果映像位于容器映像注册表 (例如 Docker Hub 或 IBM Cloud® Container Registry) 中，请检查您是否已添加对 Code Engine 的注册表访问权，以及您是否正在使用正确的注册表私钥。 有关在容器映像注册表中使用映像的更多信息，请参阅 添加对专用容器注册表的访问权。

2. 已超出容器注册表配额。

   • 通过运行 ibmcloud ce jobrun events --jobrun JOBRUN_NAME 命令来检查 ImagePullBackOff 错误; 例如，

     ibmcloud ce jobrun events --jobrun myjobrun
   

   • 如果系统事件中的错误类似于以下消息，那么此错误指示超出注册表配额。 请考虑升级套餐。 有关 IBM Cloud® Container Registry 服务套餐和配额限制的信息，请参阅 关于 IBM Cloud Container Registry。

   403 Forbidden - Server message: denied: You have exceeded your pull traffic quota for the current month. Review your pull traffic quota and pricing plan.
   

3. 容器注册表需要认证。

   • 如果系统事件中的错误类似于以下消息，那么此错误指示对注册表的访问不存在或可能需要授权。 请检查您的凭证是否具有对注册表的相应访问权。

   Failed to pull image "<image_name>": rpc error: code = Unknown desc = failed to pull and unpack image "<image_name:image_tag>": failed to resolve reference <image_name:image_tag>": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed.
   

4. Code Engine 在容器注册表中找不到映像。

   在此场景中，您的映像存在并且注册表访问有效，但 Code Engine 发现的映像与它期望的特定应用程序修订版的映像不同。 容器注册表映像摘要与应用程序修订版的映像预期摘要不匹配。

   部署应用程序或新应用程序修订版时，将下载并部署引用的容器映像的最新版本，除非为该映像指定了标记。 如果为映像指定了标记，那么标记的映像将用于部署。

   如果使用与应用程序引用的原始映像相同的标记创建映像的较新版本，那么将在容器注册表中覆盖原始映像。 但是，Code Engine 找不到此较新映像，因为较新映像的摘要与应用程序修订版的摘要不同。 与特定应用程序修订版关联的映像具有唯一的容器注册表摘要，并且 Code Engine 将此摘要用于应用程序修订版的生命周期。

   如果您创建与原始映像具有相同标记的映像的较新版本，那么原始映像将在容器注册表中覆盖并变为未标记。 更新的映像已标记，并且此更新的映像具有不同的摘要。 Code Engine 应用程序未使用此较新映像，因为较新映像的摘要与应用程序修订版所引用的映像的摘要不同。如果最初引用的映像仍然存在，那么 Code Engine 仍可以创建应用程序修订版的新实例。 如果应用程序最初引用的映像不存在，那么 Code Engine 找不到期望的映像摘要，并且应用程序由于无法拉取该映像而失败。 在清除和删除映像时，以及在为容器注册表配置保留时间策略时，请谨慎操作。 覆盖标记的图像没有问题。 但是，如果使用用于删除未标记的映像的已启用保留策略覆盖映像，或者如果手动触发未标记的映像的清除，那么可能会发生问题。

   如果系统事件中的错误类似于以下消息，那么此错误指示 Code Engine 无法从注册表名称空间中拉取映像。 检查图像的标记是否指向正确的图像摘要。

   Unable to pull the image. Image "<image_name>" does not exist in the registry namespace. Check your registry repository and tag. If the image exists in the repository, check whether the specified tag points to the correct image digest.
   

   要将使用同一标记推送的较新映像与应用程序配合使用，必须 更新应用程序 以创建引用较新标记的映像的新应用程序修订版。

5. Code Engine 无法对容器注册表进行身份验证。

   在这种情况下，您的映像存在，注册表访问正常，配置的注册表秘密有效，但 Code Engine 无法验证您的容器注册表。 您可能会看到与下图类似的错误信息：

   ErrImagePull : failed to pull and unpack image "<image name>": failed to resolve reference "<image name>": failed to authorize: failed to fetch oauth token: unexpected status from GET request to...
   

   检查是否已为账户启用 Restrict IP address access （请参阅 允许特定 IP 地址 ）。 如果启用，则只有允许的 IP 地址才能验证 IBM Cloud®，您的账户。 这将阻止 Code Engine 验证容器注册表，从而无法提取映像。 您需要添加 Code Engine 项目的 public 和 private IP 地址。 请参阅 Code Engine 公共和专用 IP 地址，了解如何识别这些 IP 地址。