4. dockerconfigjson Secrets 详解：结构解析、base64 编码原理、手动创建示例

在 Kubernetes 中拉取私有镜像仓库的容器镜像时，最核心的凭证载体就是 dockerconfigjson 类型的 Secret。它本质上是将 Docker 客户端认证文件 config.json 经过 base64 编码后，存储在 Kubernetes Secret 的 .dockerconfigjson 字段中。理解其内部结构、编码原理以及手动创建方式，是掌握 Secrets 外部集成配置的基础。

4.1 dockerconfigjson 内部结构解析

一个标准的 dockerconfigjson Secret 在 Kubernetes 中的 YAML 定义如下：

apiVersion: v1
kind: Secret
metadata:
  name: my-registry-secret
  namespace: default
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsiYXV0aCI6IlpXNTZZWEJ3Y205dmNtRnllUT09In19fQ==

其中 .dockerconfigjson 字段的值是一个 base64 编码后的字符串。解码后，其原始 JSON 结构如下：

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "ZW52bG9wZWVkX2FjY291bnQ6cGFzc3dvcmQ="
    }
  }
}

4.2 base64 编码原理与解码验证

base64 是一种用 64 个可打印字符表示二进制数据的编码方式。在 dockerconfigjson 中，它被用于两层编码：

1. 第一层（内部）： 将 username:password 字符串编码为 auth 字段的值。
2. 第二层（外部）： 将整个 config.json JSON 对象编码为 .dockerconfigjson 字段的值。

以下是一个手动解码与编码的示例，假设用户名为 admin，密码为 mypassword：

4.3 手动创建 dockerconfigjson Secret 的三种方法

Kubernetes 提供了多种手动创建 dockerconfigjson Secret 的方式，以下是最常用的三种：

方法一：使用 kubectl create secret docker-registry（推荐）

这是最简洁的方式，Kubernetes 会自动完成凭证拼接和 base64 编码：

kubectl create secret docker-registry my-registry-secret \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=admin \
  --docker-password=mypassword \
  --docker-email=admin@example.com \
  --namespace=default

执行后，Kubernetes 会自动生成 .dockerconfigjson 字段的完整编码值。

方法二：基于 Docker 本地 config.json 文件创建

如果本地已经通过 docker login 完成了认证，可以直接使用已有的配置文件：

# 默认路径：~/.docker/config.json
kubectl create secret generic my-registry-secret \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson \
  --namespace=default

方法三：完全手动构造 YAML

适用于需要精确控制内容或离线环境。需要手动完成两次 base64 编码：

# 1. 生成第一层 base64（username:password）
echo -n "admin:mypassword" | base64
# 输出: YWRtaW46bXlwYXNzd29yZA==

# 2. 构建 JSON 并生成第二层 base64
echo -n '{"auths":{"https://index.docker.io/v1/":{"auth":"YWRtaW46bXlwYXNzd29yZA=="}}}' | base64
# 输出: eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsiYXV0aCI6IllXUnRhVzQ2YlhseVlYTnpkVzI5eVpBPT0ifX19

# 3. 编写 Secret YAML
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: my-registry-secret
  namespace: default
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsiYXV0aCI6IllXUnRhVzQ2YlhseVlYTnpkVzI5eVpBPT0ifX19
EOF

4.4 dockerconfigjson 结构关系图

下图展示了从原始凭证到 Kubernetes Secret 的完整编码链路与内部结构：

4.5 多仓库认证配置

一个 dockerconfigjson Secret 可以同时包含多个镜像仓库的认证信息，只需在 auths 对象中添加多个键值对即可：

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "YWRtaW46bXlwYXNzd29yZA=="
    },
    "https://myregistry.example.com": {
      "auth": "bXl1c2VyOm15cGFzc3dvcmQ="
    },
    "https://gcr.io": {
      "auth": "c2VydmljZV9hY2NvdW50OnRva2VuMTIz"
    }
  }
}

4.6 常见错误与排查