从Google Cloud Compute拉取Docker镜像时权限被拒的问题排查

问题分析 #

你遇到的权限拒绝问题，核心是GCE实例使用的服务账户（默认或自定义）未被授予Artifact Registry仓库的下载权限。本地能正常拉取是因为使用了本地已授权的用户身份，而实例环境使用的是服务账户身份，二者权限独立。

错误详情 #

sudo docker pull europe-west3-docker.pkg.dev/[project]/[repo]/[image]:latest
Error response from daemon: 
Head "https://europe-west3-docker.pkg.dev/v2/[project]/[repo]/api/manifests/latest": denied: 
Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/[project]/locations/europe-west3/repositories/[repo]" (or it may not exist)

已验证操作 #

• 尝试使用默认服务账户及自定义服务账户（已赋予必要角色）
• 策略排查工具显示权限配置正常
• 执行gcloud auth configure-docker europe-west3-docker.pkg.dev配置Docker认证，gcloud auth list确认账户无误
• 本地机器可正常拉取镜像，gcloud artifacts docker images list [repo]访问仓库正常
• 完成gcloud init，可正常拉取官方Docker镜像

解决方案 #

1. 给服务账户绑定Artifact Registry Reader角色 #

显式给实例使用的服务账户绑定roles/artifactregistry.reader角色，该角色包含artifactregistry.repositories.downloadArtifacts权限。

用Terraform添加权限绑定：

# 绑定权限到实例使用的服务账户
resource "google_project_iam_member" "artifact_registry_reader" {
  project = var.project_id
  role    = "roles/artifactregistry.reader"
  # 如果用默认服务账户，直接引用实例的服务账户邮箱
  member  = "serviceAccount:${google_compute_instance.mono.service_account.email}"
}

# 若使用自定义服务账户，替换为自定义账户邮箱：
# member = "serviceAccount:${google_service_account.custom_sa.email}"

2. 显式指定实例的服务账户（可选） #

如果使用自定义服务账户，在Terraform实例配置中明确指定，避免依赖默认账户：

# 自定义服务账户
resource "google_service_account" "custom_sa" {
  account_id   = "artifact-access-sa"
  display_name = "Service Account for Artifact Registry Access"
}

# GCE实例配置
resource "google_compute_instance" "mono" {
  name = "mono"
  machine_type = "n1-standard-1"
  allow_stopping_for_update = true

  service_account {
    email  = google_service_account.custom_sa.email
    scopes = ["cloud-platform"]
  }

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }

  network_interface {
    network = "default"
    access_config {}
  }
}

3. 自动配置Docker认证 #

通过启动脚本在实例初始化时自动完成Docker认证，无需手动操作：

resource "google_compute_instance" "mono" {
  # ... 其他配置 ...

  metadata_startup_script = <<-EOT
    #!/bin/bash
    # 安装Docker（若实例未预装）
    apt-get update && apt-get install -y docker.io
    # 配置Docker使用GCE服务账户认证
    gcloud auth configure-docker europe-west3-docker.pkg.dev --quiet
  EOT
}

4. 验证修复效果 #

部署Terraform后，登录GCE实例执行以下命令验证：

# 确认当前使用的服务账户
gcloud auth list
# 尝试拉取目标镜像
docker pull europe-west3-docker.pkg.dev/[project]/[repo]/[image]:latest

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