Go Kubernetes 资源操作接口手册

模块路径：package k8s

本手册包含两个核心接口：

1. NewClient —— 创建 Kubernetes 客户端
2. EnsureNamespace —— 确保命名空间存在
3. CreateDockerRegistrySecret —— 创建 Docker 镜像仓库 Secret

---

1. 创建 Kubernetes 客户端

接口名称

NewClient

功能描述

创建一个可直接调用 Kubernetes API 的客户端，所有资源操作（Namespace、Secret、Pod 等）都依赖该客户端。

函数签名

func NewClient(kubeconfig string) (*kubernetes.Clientset, error)

请求参数

参数名	类型	说明
kubeconfig	string	kubeconfig 文件路径，一般为 ~/.kube/config 或自定义路径，用于连接 Kubernetes 集群

返回值

返回项	类型	说明
clientset	*kubernetes.Clientset	Kubernetes 客户端实例
err	error	如果 kubeconfig 加载失败或创建客户端失败，返回错误

示例代码

clientset, err := k8s.NewClient("/root/.kube/config")
if err != nil {
    fmt.Println("❌ 创建 Kubernetes 客户端失败:", err)
    return
}
fmt.Println("✅ 成功连接到 Kubernetes 集群")

错误说明

• 加载 kubeconfig 失败：文件路径错误或权限不足
• 创建客户端失败：kubeconfig 中 API Server 地址不可访问

---

2. 确保命名空间存在

接口名称

EnsureNamespace

功能描述

检查指定命名空间是否存在，如果不存在则创建。

函数签名

func EnsureNamespace(clientset *kubernetes.Clientset, name string) error

请求参数

参数名	类型	说明
clientset	*kubernetes.Clientset	已创建的 K8s 客户端
name	string	命名空间名称

返回值

返回项	类型	说明
err	error	如果创建失败或通信异常返回错误，否则为 nil

示例代码

err := k8s.EnsureNamespace(clientset, "test-ns")
if err != nil {
    fmt.Println("❌ 命名空间创建失败:", err)
} else {
    fmt.Println("✅ 命名空间已存在或创建成功")
}

输出示例

✅ 命名空间 "test-ns" 已存在。

或

✅ 命名空间 "test-ns" 创建成功。

错误说明

• 权限不足
• API Server 不可达
• 名称不合法

---

3. 创建 Docker Registry Secret

接口名称

CreateDockerRegistrySecret

功能描述

在指定命名空间创建 Docker Registry 类型 Secret，用于 Kubernetes 拉取私有镜像。

• 如果 Secret 已存在，则直接返回成功提示
• 如果不存在，则自动创建

函数签名

func CreateDockerRegistrySecret(
    clientset *kubernetes.Clientset,
    namespace, name, server, username, password string,
) error

请求参数

参数名	类型	说明
clientset	*kubernetes.Clientset	已创建的 K8s 客户端
namespace	string	Secret 所在命名空间
name	string	Secret 名称
server	string	Docker Registry 地址，例如 "mrim-cn-beijing.cr.volces.com"
username	string	Docker Registry 用户名
password	string	Docker Registry 密码

返回值

返回项	类型	说明
err	error	创建失败或通信异常返回错误，成功创建或已存在返回 nil

功能流程

1. 检查 Secret 是否存在：

   clientset.CoreV1().Secrets(namespace).Get(...)
   

2. 若存在，打印提示并返回

3. 若不存在，构造 .dockerconfigjson：

   {
     "auths": {
       "<server>": {
         "username": "<username>",
         "password": "<password>",
         "auth": "<username:password 的 Base64>"
       }
     }
   }
   

4. 序列化并 Base64 编码，创建 Secret

5. 打印创建成功提示

示例代码

err := k8s.CreateDockerRegistrySecret(
    clientset,
    "test-ns",
    "mirm-repository",
    "mrim-cn-beijing.cr.volces.com",
    "admin",
    "password",
)
if err != nil {
    fmt.Println("❌ 创建 Secret 失败:", err)
} else {
    fmt.Println("✅ Secret 创建成功或已存在")
}

输出示例

✅ Secret "mirm-repository" 已存在于命名空间 "test-ns"。

或

✅ Docker 仓库 Secret "mirm-repository" 已在命名空间 "test-ns" 创建成功。

错误说明

• Secret 创建失败（权限不足、网络问题）
• 名称不合法
• API Server 不可达

注意事项

• Secret 类型固定为 kubernetes.io/dockerconfigjson
• 创建后 Pod 可通过 imagePullSecrets 使用：

imagePullSecrets:
- name: mirm-repository

• .dockerconfigjson 必须合法 Base64，否则拉取镜像会报错 illegal base64 data

---

4. 推荐调用顺序

1. 创建客户端

clientset, _ := k8s.NewClient("/root/.kube/config")

2. 确保命名空间存在

k8s.EnsureNamespace(clientset, "test-ns")

3. 创建 Docker Registry Secret

k8s.CreateDockerRegistrySecret(clientset, "test-ns", "mirm-repository", server, username, password)

---

对应接口的代码地址