holoplot/registry-creds

registry-creds Docker镜像文档

镜像概述和主要用途

registry-creds 是一个用于 Kubernetes (K8S) 环境的工具镜像，旨在解决集群从私有镜像仓库拉取镜像时的凭证管理问题。该镜像基于 https://github.com/holoplot/registry-creds 项目构建，通过自动化凭证同步与注入，帮助 K8S 节点或 Pod 安全、高效地访问私有仓库中的镜像，避免手动配置 imagePullSecrets 或节点级凭证的复杂性。

核心功能和特性

• 凭证集中管理：从 K8S Secrets 中读取私有仓库凭证，支持集中式配置与分发。
• 跨范围同步：支持集群级、命名空间级或节点级的凭证同步，满足不同粒度的访问控制需求。
• 多仓库兼容：适配主流私有镜像仓库，包括 Docker Hub、AWS ECR、Google GCR、Azure ACR、Harbor、GitLab Container Registry 等。
• 自动凭证注入：自动将凭证注入节点的容器运行时配置（如 Docker、containerd）或 Pod 的 imagePullSecrets，无需手动修改应用部署配置。
• 安全增强：支持凭证自动轮换、最小权限原则（基于 RBAC），避免凭证明文暴露。
• 高可用性：支持以 DaemonSet 形式部署，确保集群所有节点均能获取最新凭证。

使用场景和适用范围

典型使用场景

• 多团队共享私有仓库：企业内部多团队共用私有镜像仓库时，通过集中管理凭证避免重复配置。
• 跨命名空间访问私有镜像：无需在每个命名空间手动创建 imagePullSecrets，实现跨命名空间私有镜像拉取。
• 动态凭证更新：私有仓库凭证过期或轮换时，自动同步新凭证至集群，避免服务中断。
• 节点级镜像拉取优化：对于需要节点直接拉取镜像的场景（如静态 Pod、系统组件），自动配置节点级镜像拉取凭证。

适用范围

• Kubernetes 集群：支持主流发行版（EKS、GKE、AKS、RKE、K3s、自建集群等），版本 ≥ 1.16。
• 容器运行时：兼容 Docker、containerd、CRI-O。
• 私有仓库服务：支持所有遵循 Docker Registry v2 API 的私有仓库。

使用方法和配置说明

部署到 Kubernetes 集群

registry-creds 通常以 DaemonSet 形式部署在 K8S 集群中，确保每个节点均运行凭证同步进程。部署需通过 YAML 配置文件或 Helm Chart（若项目提供）完成。

前提条件

• 集群已配置 RBAC，且部署账户具有读取 Secrets、管理节点配置的权限。
• 私有仓库凭证已存储为 K8S Secret（类型为 kubernetes.io/dockerconfigjson 或 kubernetes.io/basic-auth）。

部署步骤

1. 准备私有仓库凭证 Secret
   创建存储私有仓库凭证的 Secret（以 Docker Hub 为例）：

   bash
   kubectl create secret docker-registry private-registry-creds \
     --namespace kube-system \
     --docker-server=https://index.docker.io/v1/ \
     --docker-username=<your-username> \
     --docker-password=<your-password> \
     --docker-email=<your-email>
   

2. 部署 registry-creds DaemonSet
   从项目仓库获取部署 YAML（或自定义配置），并应用至集群：

   bash
   kubectl apply -f https://raw.githubusercontent.com/holoplot/registry-creds/main/deploy/daemonset.yaml
   

3. 验证部署
   检查 DaemonSet 状态及 Pod 运行情况：

   bash
   kubectl get daemonset registry-creds -n kube-system
   kubectl get pods -n kube-system -l app=registry-creds
   

配置参数说明

通过 ConfigMap 或环境变量配置 registry-creds 行为，核心参数如下：

环境变量说明

容器内可通过环境变量覆盖默认配置，示例：

yaml
env:
  - name: REGISTRY_URLS
    value: "https://index.docker.io/v1/,https://600000000000.dkr.ecr.us-west-2.amazonaws.com"
  - name: SYNC_INTERVAL
    value: "600"  # 10分钟同步一次
  - name: LOG_LEVEL
    value: "debug"  # 调试模式

部署方案示例

Kubernetes DaemonSet 部署示例

以下是简化的 DaemonSet 配置 YAML（完整配置请参考项目官方文档）：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: registry-creds
  namespace: kube-system
  labels:
    app: registry-creds
spec:
  selector:
    matchLabels:
      app: registry-creds
  template:
    metadata:
      labels:
        app: registry-creds
    spec:
      hostPath:
        - name: node-root
          path: /var/lib/kubelet
          type: Directory
      containers:
        - name: registry-creds
          image: holoplot/registry-creds:latest  # 替换为具体版本
          env:
            - name: REGISTRY_URLS
              value: "https://index.docker.io/v1/,https://gcr.io"
            - name: SECRET_NAME
              value: "private-registry-creds"
            - name: SECRET_NAMESPACE
              value: "kube-system"
          volumeMounts:
            - name: node-root
              mountPath: /node-root
          securityContext:
            privileged: true  # 需特权模式修改节点配置
      volumes:
        - name: node-root
          hostPath:
            path: /var/lib/kubelet

注意事项和最佳实践

1. 凭证安全：存储凭证的 Secret 应限制访问权限，仅允许 registry-creds 服务账户读取。
2. 版本固定：部署时建议使用具体镜像版本（如 holoplot/registry-creds:v1.2.3），避免 latest 标签导致不可预期更新。
3. 监控与日志：配置日志收集（如 ELK Stack）和监控（如 Prometheus），追踪凭证同步状态及异常。
4. 凭证轮换：定期更新私有仓库凭证，并通过 SYNC_INTERVAL 确保集群及时同步新凭证。
5. 测试验证：部署后通过创建使用私有镜像的 Pod 验证拉取功能：

   yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: private-image-test
   spec:
     containers:
       - name: test
         image: <private-registry>/<your-image>:<tag>  # 私有仓库镜像
   

   若 Pod 成功启动，表明凭证配置生效。