删除旧版本后无法向AWS SageMaker Studio附加自定义镜像

故障触发场景 #

• 自定义镜像附加功能前期正常可用
• 手动删除若干历史镜像版本后功能异常
• 故障表现：无法附加全新自定义镜像，也无法为已有镜像追加新版本

根因说明 #

该问题90%以上是删除镜像版本时，SageMaker侧残留了状态异常的Image/ImageVersion资源，或者域配置中残留了已删除镜像版本的引用条目，导致后续镜像附加操作的前置校验不通过；剩余小概率原因是ECR仓库权限丢失、镜像拉取权限配置失效。

修复步骤 #

1. 清理异常状态的残留资源

• 配置好对应区域的AWS CLI管理员凭证，执行命令列出所有SageMaker镜像资源：
  aws sagemaker list-images
• 找到出问题的自定义镜像名称，执行命令查询所有版本状态：
  aws sagemaker list-image-versions --image-name <替换为你的自定义镜像名称>
• 所有状态不是CREATED的版本（含卡在DELETING/DELETE_FAILED/CREATE_FAILED状态的版本），全部执行强制删除：
  aws sagemaker delete-image-version --image-name <替换为你的自定义镜像名称> --version-number <替换为异常版本号>
• 若镜像本身状态异常，直接删除镜像资源重建：
  aws sagemaker delete-image --image-name <替换为你的自定义镜像名称>

2. 校验ECR仓库权限

• 进入ECR控制台，确认待附加的镜像标签存在、镜像完整性正常
• 给对应ECR仓库添加SageMaker服务拉取权限，策略如下：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"Service": "sagemaker.amazonaws.com"},
      "Action": ["ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer"]
    }
  ]
}

3. 刷新域配置后重试附加

• 进入SageMaker Studio域详情页，点击编辑，不修改任何配置直接提交，等待域状态回到InService
• 若上述操作无效，执行命令查询域配置：
  aws sagemaker describe-domain --domain-id <替换为你的Studio域ID>
• 找到返回结果中DefaultUserSettings.KernelGatewayAppSettings.CustomImages字段，手动删除所有引用已删除镜像、已删除版本的条目，调用update-domain接口提交更新
• 等待域配置生效后，重新创建自定义镜像、执行附加操作即可

注意：跨账号引用ECR镜像时，需要额外配置ECR跨账号信任策略，同时给SageMaker执行角色绑定对应ECR仓库的拉取权限

内容的提问来源于stack exchange，提问作者therealbappi