3. Kubernetes Secrets 基础：Secret 资源定义、类型与创建方式

在容器镜像拉取加速场景中，Kubernetes Secrets 是承载私有仓库认证凭据的核心载体。理解 Secret 的资源定义、类型及创建方式，是后续实现外部集成配置的前提。本章将系统梳理 Secret 的基础知识，重点聚焦 Opaque 与 dockerconfigjson 两种类型。

3.1 Secret 资源定义与核心字段

Secret 是 Kubernetes 内置的命名空间级资源，用于存储敏感数据（如密码、、证书）。其数据以 Base64 编码存储于 data 字段中，或明文存储于 stringData 字段（仅用于创建/更新）。

3.2 Secret 类型对比：Opaque vs dockerconfigjson

Kubernetes 定义了多种 Secret 类型，其中 Opaque 和 kubernetes.io/dockerconfigjson 是容器镜像拉取场景中最常用的两种。

3.3 创建 Secret 的三种方式

Kubernetes 提供声明式 YAML、命令行指令和自动生成三种创建方式，满足不同运维习惯与自动化需求。

3.3.1 方式一：声明式 YAML 创建

通过 YAML 文件定义 Secret 资源，适用于版本管理与 CI/CD 集成。

# opaque-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-opaque-secret
  namespace: default
type: Opaque
data:
  username: YWRtaW4=        # admin
  password: MWYyZDFlMmU2N2Rm  # 1f2d1e2e67df
---
# dockerconfig-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-registry-secret
  namespace: default
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsiYXV0aCI6IlpXNTZZWEJwYzNSeVlXbG5hVzVrT2lCb2RIUndjem92TDNkM2R5NXBibVp2WDJsa0xtTnZiUzloY0hCekxtTnZiUT09In19fQ==

3.3.2 方式二：命令行指令创建

使用 kubectl create secret 命令，无需手动编码，适合快速创建与调试。

# 创建 Opaque Secret（从字面值）
kubectl create secret generic my-opaque-secret \
  --from-literal=username=admin \
  --from-literal=password=1f2d1e2e67df

# 创建 Opaque Secret（从文件）
kubectl create secret generic my-opaque-secret \
  --from-file=./cert.pem

# 创建 dockerconfigjson Secret
kubectl create secret docker-registry my-registry-secret \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=myuser \
  --docker-password=mypassword \
  --docker-email=myuser@example.com

3.3.3 方式三：自动生成（kubectl 与 Helm 集成）

在 Helm Chart 或自动化脚本中，可利用模板函数或 kubectl 组合命令动态生成 Secret，避免硬编码。

# Helm 模板示例（_helpers.tpl）
{{- define "imagePullSecret" }}
{{- printf "{\"auths\":{\"%s\":{\"auth\":\"%s\"}}}" .Values.registry.url (printf "%s:%s" .Values.registry.username .Values.registry.password | b64enc) | b64enc }}
{{- end }}

# 使用方式（deployment.yaml）
apiVersion: v1
kind: Secret
metadata:
  name: {{ include "myapp.fullname" . }}-registry
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ include "imagePullSecret" . }}

3.4 Secret 类型与创建方式对照表

3.5 Secret 数据流与 Pod 引用关系

下图展示了 Secret 从创建到被 Pod 引用的完整数据流，重点突出 dockerconfigjson 类型在镜像拉取过程中的作用。

3.6 最佳实践与避坑指南

• 优先使用 dockerconfigjson 类型： 对于私有镜像仓库认证，始终使用 kubernetes.io/dockerconfigjson 而非 Opaque，Kubernetes 会原生解析并处理。
• 避免手动 Base64 编码： 使用 kubectl create secret docker-registry 或 Helm 模板自动生成，减少编码错误。
• 限制 Secret 访问权限： 通过 RBAC 控制 Secret 的 get/list 权限，避免敏感数据泄露。
• 不要将 Secret 硬编码到镜像或代码仓库： 使用外部 Secret 存储（如 HashiCorp Vault、External Secrets Operator）实现动态注入。
• 注意 Secret 大小限制： etcd 默认单个 Secret 不超过 1MB，超出时考虑拆分或使用外部存储。