MicroK8s中使用containerd拉取GCP Artifact Registry镜像的认证问题解析

背景介绍

在使用MicroK8s或Kubernetes环境时，从Google Cloud Platform(GCP)的Artifact Registry拉取私有容器镜像是一个常见需求。然而，许多用户在配置containerd与GCP认证时会遇到401未授权错误，特别是在使用服务账户密钥进行认证时。

问题现象

当尝试通过crictl或ctr命令从Artifact Registry拉取镜像时，会出现类似以下的错误信息：

failed to authorize: failed to fetch oauth token: unexpected status from GET request to https://europe-docker.pkg.dev/v2/token?scope=repository%3Acm-controls%2Flgm%2Flgm-hmi%3Apull&service=europe-docker.pkg.dev: 401 Unauthorized

这种错误表明containerd无法正确使用提供的服务账户密钥来获取必要的OAuth令牌。

根本原因分析

这个问题源于containerd对GCP服务账户密钥的特殊处理方式。与Kubernetes直接使用.dockerconfig secret不同，containerd需要特定的配置格式来处理GCP的认证流程。

GCP Artifact Registry使用基于OAuth 2.0的认证机制，需要containerd能够：

1. 正确解析服务账户密钥JSON文件
2. 使用其中的RSA密钥获取JWT令牌
3. 自动处理令牌的刷新机制

解决方案

经过实践验证，正确的containerd配置方式如下：

方法一：使用_base64编码的服务账户密钥_

[plugins.cri.registry]
  [plugins.cri.registry.configs]
    [plugins.cri.registry.configs."europe-docker.pkg.dev"]
      [plugins.cri.registry.configs."europe-docker.pkg.dev".auth]
        username = "_json_key_base64"
        password = "base64编码的服务账户密钥文件内容"

方法二：直接使用JSON服务账户密钥

[plugins.cri.registry]
  [plugins.cri.registry.configs]
    [plugins.cri.registry.configs."europe-docker.pkg.dev"]
      [plugins.cri.registry.configs."europe-docker.pkg.dev".auth]
        username = "_json_key"
        password = '''{
          "type": "service_account",
          "project_id": "...",
          "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
          ...
        }'''

重要注意事项：

1. 当使用直接JSON方式时，必须确保private_key字段中的换行符(\n)被正确保留
2. 必须使用完整的registry域名(如europe-docker.pkg.dev)，不能使用通配符(*.pkg.dev)
3. 服务账户密钥需要有足够的权限访问目标Artifact Registry

技术原理

这种配置方式之所以有效，是因为：

1. _json_key和_json_key_base64是GCP专门为容器运行时设计的特殊用户名标识
2. containerd会识别这些特殊标识，并自动执行OAuth令牌获取流程
3. 系统会处理令牌的自动刷新，无需手动管理短期令牌

最佳实践建议

1. 最小权限原则：为服务账户分配仅够拉取镜像的最小权限
2. 密钥管理：考虑使用GCP的Workload Identity Federation替代长期密钥
3. 配置验证：使用crictl pull命令测试配置是否生效
4. 日志排查：遇到问题时，检查containerd日志获取详细错误信息

总结

通过正确配置containerd的registry认证部分，可以稳定地从GCP Artifact Registry拉取镜像。关键在于理解GCP特殊的认证机制和containerd的配置格式要求。相比Kubernetes的.dockerconfig secret方式，containerd层面的配置提供了更基础的控制能力，适合需要精细管理容器运行时行为的场景。