Artifact Registry：镜像与访问控制

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

私有容器镜像仓库；Console：Artifact Registry → Repositories。

常用操作#

替换为实际资源；本段不依赖 lab.env。

PROJECT_ID='REPLACE_PROJECT_ID'
REGION='REPLACE_REGION'
REPOSITORY='REPLACE_REPOSITORY'

gcloud auth configure-docker "${REGION}-docker.pkg.dev"
gcloud artifacts docker images list \
  "${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY}" --include-tags

容易踩的坑#

configure-docker 只配置认证，不授予 IAM 权限。

镜像拉取身份与本机 push 身份不同。 GKE 检查 Node SA；Cloud Run 检查其 service agent。给业务 runtime SA 或 KSA 授权，不代表平台已能拉取镜像。

Project 与 Repository 授权范围

配置说明与完整示例（按需展开）

前置：环境篇、本机 Docker 已启动。仓库保存镜像；本机 push 需要该仓库的 Artifact Registry Writer。跨项目拉取要显式授权对应拉取身份。

镜像地址怎么读#

${REGION}-docker.pkg.dev/${PROJECT_ID}/lab-images/hello:v1 依次是 registry host、Project、Repository、image 和 tag。hello@sha256:... 用 digest 固定内容；Repository 的 Region 与部署服务的位置是不同配置。

configure-docker 配置指定 host 的 Docker credential helper，不创建仓库、不授予 Writer。push 成功也不代表 GKE 节点或 Cloud Run service agent 已有拉取权限，须核对实际拉取身份。

构建与推送#

source lab.env
gcloud services enable artifactregistry.googleapis.com
gcloud artifacts repositories create lab-images --repository-format=docker --location="$REGION"
gcloud auth configure-docker "${REGION}-docker.pkg.dev"
mkdir -p hello-app
cd hello-app
cat > Dockerfile <<'EOF'
FROM python:3.12-slim
WORKDIR /app
RUN printf 'hello GCP\n' > index.html
CMD ["python", "-m", "http.server", "8080"]
EOF
export IMAGE="${REGION}-docker.pkg.dev/${PROJECT_ID}/lab-images/hello:v1"
docker build --platform=linux/amd64 -t "$IMAGE" .
docker push "$IMAGE"
gcloud artifacts docker images list "${REGION}-docker.pkg.dev/${PROJECT_ID}/lab-images" --include-tags
cd ..

验收：记录 digest，以 digest 标识不可变版本。v1 是可移动标签，不适合作为唯一发布凭据。Apple Silicon 本机构建注意平台；使用 Cloud Build 可避免本机平台差异。推送与拉取

Project 级与Repository 级权限的区别及命令示例，见 IAM：授权范围。

清理#

保留仓库供构建和 Cloud Run 使用；完成依赖实验后：

gcloud artifacts repositories delete lab-images --location="$REGION"

费用来自存储与传输；清理旧镜像前确认不影响回滚。