Client-go完全实战指南

概述

GitHub 仓库:https://github.com/kubernetes/client-go

client-go 是 Kubernetes 官方维护的 Go 语言客户端库,用于与 Kubernetes API Server 交互。它是开发控制器、Operator、CLI 工具以及其他需要与集群通信的 Go 应用的事实标准和核心依赖。

需要一个可访问的集群进行实验,可使用 Kind 搭建,参考 基于Kind搭建测试集群。

Kubernetes API 结构

理解以下概念对正确使用 client-go 至关重要:

概念 说明 示例
Group 相关功能的 API 集合 apps(Deployment, StatefulSet)、networking.k8s.io(Ingress)
Version API 的版本,标识稳定性和迭代阶段 v1、v1beta1、v1alpha1
Kind API 资源的类型,对应 YAML 中的 kind: 字段 Pod、Deployment、MyCustomResource
Resource Kind 的小写复数形式,用于 API URL 路径 pods、deployments

API 路径格式:

GVK vs GVR:GVK(GroupVersionKind)用于标识对象类型(Go 结构体和 YAML 中),GVR(GroupVersionResource)用于标识 API 端点(HTTP URL 中)。两者通过 RESTMapper 进行映射。

四种客户端类型

client-go 实现了四种客户端,分别针对不同使用场景:

graph TD
    A[ClientSet] -->|uses| B[RESTClient]
    C[Dynamic Client] -->|uses| B
    D[Discovery Client] -->|uses| B
    B --> E[http.Client]
    E --> F[apiserver/api/v1/namespaces/xxx/pods/xxx]
    F --> G[Kubernetes APIServer]
客户端 定位 操作范围 数据结构 适用场景
RESTClient 基础客户端 所有资源(含 CRD) 结构化/非结构化 底层封装,一般不直接使用
ClientSet 类型安全客户端 内置资源 强类型 Go 结构体 日常开发首选,操作 Pod/Deployment 等
DynamicClient 动态客户端 所有资源(含 CRD) *unstructured.Unstructured 操作 CRD 或运行时动态确定资源类型
DiscoveryClient 发现客户端 资源元信息 API Group/Version/Resource 发现集群支持的资源,kubectl 自动补全等

关联关系:RESTClient 为底层基础,其他三种客户端均基于它实现。DiscoveryClient 负责发现资源信息,ClientSet 和 DynamicClient 据此操作具体资源。

基础用法:使用 ClientSet

获取配置

首先需要获取 *rest.Config 对象,包含与 API Server 通信的地址和认证信息。

package main

import (
    "flag"
    "fmt"
    "path/filepath"

    "k8s.io/client-go/rest"
    "k8s.io/client-go/tools/clientcmd"
    "k8s.io/client-go/util/homedir"
)

func main() {
    var kubeconfig *string
    var config *rest.Config
    var err error

    // 尝试 In-Cluster 配置(Pod 内运行)
    if config, err = rest.InClusterConfig(); err != nil {
        // 回退到 kubeconfig 文件(本地开发)
        if home := homedir.HomeDir(); home != "" {
            kubeconfig = flag.String("kubeconfig", filepath.Join(home, ".kube", "config"), "(optional) absolute path to the kubeconfig file")
        } else {
            kubeconfig = flag.String("kubeconfig", "", "absolute path to the kubeconfig file")
        }
        flag.Parse()

        config, err = clientcmd.BuildConfigFromFlags("", *kubeconfig)
        if err != nil {
            panic(err.Error())
        }
    }

    // 后续使用 config 创建客户端...
}

rest.InClusterConfig() 依赖 kubelet 自动注入的资源:

来源 路径/变量 用途
投射卷 /var/run/secrets/kubernetes.io/serviceaccount/token ServiceAccount 的 JWT 令牌,用于 API 认证
投射卷 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 集群根 CA 证书,校验 apiserver 的 TLS 证书
环境变量 KUBERNETES_SERVICE_HOST apiserver 地址
环境变量 KUBERNETES_SERVICE_PORT apiserver 端口

只要 Pod 以 ServiceAccount 身份运行,就能零配置调用 Kubernetes API。

创建 ClientSet

clientset, err := kubernetes.NewForConfig(config)
if err != nil {
    panic(err.Error())
}

CRUD 操作示例

List — 列出命名空间中的所有 Pod

func listPods(clientset *kubernetes.Clientset, namespace string) {
    ctx := context.TODO()
    pods, err := clientset.CoreV1().Pods(namespace).List(ctx, metav1.ListOptions{})
    if err != nil {
        panic(err.Error())
    }
    fmt.Printf("There are %d pods in the %s namespace\n", len(pods.Items), namespace)
    for _, pod := range pods.Items {
        fmt.Printf("- %s\n", pod.Name)
    }
}

Get — 获取指定 Pod

func getPod(clientset *kubernetes.Clientset, namespace, podName string) {
    ctx := context.TODO()
    pod, err := clientset.CoreV1().Pods(namespace).Get(ctx, podName, metav1.GetOptions{})
    if err != nil {
        panic(err.Error())
    }
    fmt.Printf("Pod %s status: %s\n", podName, pod.Status.Phase)
}

Create — 创建 Deployment

func createDeployment(clientset *kubernetes.Clientset) {
    deployment := &appsv1.Deployment{
        ObjectMeta: metav1.ObjectMeta{
            Name: "demo-deployment",
        },
        Spec: appsv1.DeploymentSpec{
            Replicas: int32Ptr(2),
            Selector: &metav1.LabelSelector{
                MatchLabels: map[string]string{"app": "demo"},
            },
            Template: corev1.PodTemplateSpec{
                ObjectMeta: metav1.ObjectMeta{
                    Labels: map[string]string{"app": "demo"},
                },
                Spec: corev1.PodSpec{
                    Containers: []corev1.Container{
                        {
                            Name:  "web",
                            Image: "nginx:1.14.2",
                            Ports: []corev1.ContainerPort{{ContainerPort: 80}},
                        },
                    },
                },
            },
        },
    }

    ctx := context.TODO()
    result, err := clientset.AppsV1().Deployments("default").Create(ctx, deployment, metav1.CreateOptions{})
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created deployment %q.\n", result.GetObjectMeta().GetName())
}

func int32Ptr(i int32) *int32 { return &i }

Update — 更新 Deployment 镜像

func updateDeploymentImage(clientset *kubernetes.Clientset, namespace, deploymentName, newImage string) {
    ctx := context.TODO()
    deploy, err := clientset.AppsV1().Deployments(namespace).Get(ctx, deploymentName, metav1.GetOptions{})
    if err != nil {
        panic(err)
    }

    deploy.Spec.Template.Spec.Containers[0].Image = newImage

    _, err = clientset.AppsV1().Deployments(namespace).Update(ctx, deploy, metav1.UpdateOptions{})
    if err != nil {
        panic(err)
    }
    fmt.Println("Deployment updated successfully")
}

Watch — 监听 Pod 事件

func watchPods(clientset *kubernetes.Clientset, namespace string) {
    ctx := context.TODO()
    watcher, err := clientset.CoreV1().Pods(namespace).Watch(ctx, metav1.ListOptions{})
    if err != nil {
        panic(err)
    }
    defer watcher.Stop()

    fmt.Printf("Watching for Pod events in namespace %s...\n", namespace)
    for event := range watcher.ResultChan() {
        pod, ok := event.Object.(*corev1.Pod)
        if !ok {
            continue
        }
        switch event.Type {
        case watch.Added:
            fmt.Printf("Pod ADDED: %s/%s\n", pod.Namespace, pod.Name)
        case watch.Modified:
            fmt.Printf("Pod MODIFIED: %s/%s (Phase: %s)\n", pod.Namespace, pod.Name, pod.Status.Phase)
        case watch.Deleted:
            fmt.Printf("Pod DELETED: %s/%s\n", pod.Namespace, pod.Name)
        }
    }
}

Delete — 删除 Deployment

func deleteDeployment(clientset *kubernetes.Clientset, namespace, deploymentName string) {
    ctx := context.TODO()
    deletePolicy := metav1.DeletePropagationForeground
    err := clientset.AppsV1().Deployments(namespace).Delete(ctx, deploymentName, metav1.DeleteOptions{
        PropagationPolicy: &deletePolicy,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Deployment deleted successfully")
}

RESTClient 源码分析

RESTClient 是所有客户端的底层基础,定义在 rest/client.go。

接口定义

// rest/client.go:46
type Interface interface {
    GetRateLimiter() flowcontrol.RateLimiter
    Verb(verb string) *Request
    Post() *Request
    Put() *Request
    Patch(pt types.PatchType) *Request
    Get() *Request
    Delete() *Request
    APIVersion() schema.GroupVersion
}

各方法功能:

构造函数

// rest/client.go:112
func NewRESTClient(baseURL *url.URL, versionedAPIPath string, config ClientContentConfig,
    rateLimiter flowcontrol.RateLimiter, client *http.Client) (*RESTClient, error) {
    base := *baseURL
    if !strings.HasSuffix(base.Path, "/") {
        base.Path += "/"
    }
    base.RawQuery = ""
    base.Fragment = ""

    return &RESTClient{
        base:             &base,
        versionedAPIPath: versionedAPIPath,
        content:          requestClientContentConfigProvider{base: scrubCBORContentConfigIfDisabled(config)},
        createBackoffMgr: readExpBackoffConfig,
        rateLimiter:      rateLimiter,
        Client:           client,
    }, nil
}

参数说明:

版本演进:近期 client-go 正在全面迁移至 context.Context 感知的 API,包括 BackoffManagerWithContext、WarningHandlerWithContext 等,旧的 channel-based stop 模式逐步被 context 替代。

HTTP 方法实现

Post/Put/Patch/Get/Delete 五个方法都通过 Verb 构造对应的 Request:

func (c *RESTClient) Post() *Request   { return c.Verb("POST") }
func (c *RESTClient) Put() *Request    { return c.Verb("PUT") }
func (c *RESTClient) Get() *Request    { return c.Verb("GET") }
func (c *RESTClient) Delete() *Request { return c.Verb("DELETE") }

func (c *RESTClient) Patch(pt types.PatchType) *Request {
    return c.Verb("PATCH").SetHeader("Content-Type", string(pt))
}

Request 结构体

定义在 rest/request.go:100,采用**建造者模式(Builder Pattern)**支持链式调用:

type Request struct {
    c *RESTClient

    rateLimiter flowcontrol.RateLimiter
    backoff     BackoffManager
    timeout     time.Duration
    maxRetries  int

    // HTTP 请求参数
    verb       string
    pathPrefix string
    subpath    string
    params     url.Values
    headers    http.Header

    // Kubernetes 资源定位
    namespace    string
    resource     string
    resourceName string
    subresource  string

    // 请求体(body 和 bodyBytes 互斥,使用 io.Reader 的请求不可重试)
    body      io.Reader
    bodyBytes []byte

    err     error
    retryFn requestRetryFunc
}

Request 构建流程

通过链式方法逐步设置请求参数:

// 示例:构建一个获取 Pod 的请求
client.Get().
    Resource("pods").
    Namespace("default").
    Name("my-pod").
    Do(ctx)

主要设置方法:

方法 用途
.Resource("pods") 设置资源类型
.Namespace("default") 设置命名空间
.Name("my-pod") 设置资源名称
.SubResource("status") 设置子资源
.Param("labelSelector", "app=nginx") 设置查询参数
.Body(obj) 设置请求体(支持 runtime.Object、string、[]byte、io.Reader)
.Timeout(d) 设置超时

Body 序列化细节:如果 obj 是 runtime.Object,会使用 contentConfig.Negotiator 找到对应的编码器(JSON/Protobuf)自动序列化并设置 Content-Type。使用 io.Reader 作为 Body 的请求不可重试,因为内容只能被读取一次。

Request 执行流程

由私有方法 request(ctx, fn) 完成,处理重试、限流、超时等逻辑:

1. 速率限制(Throttling)

每次请求前调用 r.rateLimiter.Wait(ctx) 阻塞等待,直到速率限制器放行。

2. 超时控制

如果设置了 Timeout,使用 context.WithTimeout 创建有超时限制的上下文。

3. 重试循环

for retry := r.retryFn(r.maxRetries); ; {
    retry.Before()          // 限流 + 前置检查
    req := r.newHTTPRequest(ctx)  // 构建 HTTP 请求
    resp := r.c.Client.Do(req)    // 执行 HTTP 调用
    retry.After()           // 更新重试指标

    if retry.IsNextRetry() {
        continue  // 可重试错误,等待退避后重试
    }
    fn(resp)  // 处理最终响应
    break
}

默认最大重试 10 次。可重试的错误包括:连接重置、EOF、超时、5xx、429(带 Retry-After 头)。4xx 错误(404、400 等)通常不重试。

响应处理

根据调用方法不同,响应处理方式也不同:

方法 返回类型 用途
DoRaw(ctx) ([]byte, error) 获取原始响应字节
Do(ctx) Result 获取结构化响应,可通过 .Into(&obj) 反序列化为 Go 结构体
Watch(ctx) (watch.Interface, error) 建立长连接监听资源变化(ADDED/MODIFIED/DELETED/BOOKMARK)
Stream(ctx) (io.ReadCloser, error) 获取可读流(如 Pod 日志)

Do 的内部流程:

  1. 调用 transformResponse 处理响应
  2. 根据 Content-Type 通过内容协商找到解码器
  3. 如果状态码非 2xx,尝试解析为 metav1.Status 生成结构化错误
  4. 成功时返回包含 Body、解码器、状态码的 Result 对象

Watch 的内部流程:

  1. 发起请求,HTTP 200 成功后调用 newStreamWatcher
  2. 根据 Content-Type 创建流式解码器和分帧器(Framer)
  3. 创建 watch.StreamWatcher,在后台持续读取数据
  4. 通过 ResultChan() channel 将解码后的 watch.Event 发送给调用者

DiscoveryClient 源码分析

DiscoveryClient 用于发现 API Server 支持的资源组、版本和资源信息,定义在 discovery/discovery_client.go。

接口定义

// discovery/discovery_client.go:78
type DiscoveryInterface interface {
    RESTClient() restclient.Interface
    ServerGroupsInterface
    ServerResourcesInterface
    ServerVersionInterface
    OpenAPISchemaInterface
    OpenAPIV3SchemaInterface
    WithLegacy() DiscoveryInterface
}

核心方法

ServerGroups — 获取 API 组信息

通过 GroupsAndMaybeResources 方法从 /api(核心组 core/v1)和 /apis(其他 API 组)端点获取并合并结果。

ServerResourcesForGroupVersion — 获取指定组版本的资源列表

func (d *DiscoveryClient) ServerResourcesForGroupVersion(groupVersion string) (*metav1.APIResourceList, error) {
    url := url.URL{}
    if len(groupVersion) == 0 {
        return nil, fmt.Errorf("groupVersion shouldn't be empty")
    }
    if len(d.LegacyPrefix) > 0 && groupVersion == "v1" {
        url.Path = d.LegacyPrefix + "/" + groupVersion  // 核心组走 /api/v1
    } else {
        url.Path = "/apis/" + groupVersion               // 其他组走 /apis/<group>/<version>
    }
    resources := &metav1.APIResourceList{GroupVersion: groupVersion}
    err = d.restClient.Get().AbsPath(url.String()).Do(context.TODO()).Into(resources)
    // ...
}

ServerGroupsAndResources — 获取所有 API 组及其资源

支持聚合发现(Aggregated Discovery):如果 API Server 支持,一次请求获取所有信息;否则逐个组版本获取。内置重试机制处理 API 组信息变化。

ServerPreferredResources — 获取服务器首选版本的资源

与 ServerGroupsAndResources 的区别在于,它只返回每个 API 组的 PreferredVersion 对应的资源,而非所有版本。

ServerVersion — 获取服务器版本

func (d *DiscoveryClient) ServerVersion() (*version.Info, error) {
    body, err := d.restClient.Get().AbsPath("/version").Do(context.TODO()).Raw()
    // 解析 JSON 为 version.Info
}

OpenAPISchema / OpenAPIV3 — 获取 API Schema

WithLegacy — 兼容旧版发现格式

返回仅使用旧版发现协议的客户端副本,用于与旧版 Kubernetes 集群交互或混合环境下的渐进式迁移。

版本演进:Aggregated Discovery V2 在 Kubernetes 1.30 中升级为 GA,V2beta1 客户端支持在 1.37 中被移除。当前客户端默认优先使用 V2 格式,V1(legacy JSON)作为 fallback。

ClientSet 源码分析

ClientSet 定义在 kubernetes/clientset.go,为每个 API 组/版本预生成了强类型客户端。

接口定义

// kubernetes/clientset.go:84(省略大部分方法)
type Interface interface {
    Discovery() discovery.DiscoveryInterface
    CoreV1() corev1.CoreV1Interface
    AppsV1() appsv1.AppsV1Interface
    BatchV1() batchv1.BatchV1Interface
    NetworkingV1() networkingv1.NetworkingV1Interface
    RbacV1() rbacv1.RbacV1Interface
    // ... 覆盖所有内置 API 组和版本
}

实现结构

// kubernetes/clientset.go:143
type Clientset struct {
    *discovery.DiscoveryClient
    coreV1      *corev1.CoreV1Client
    appsV1      *appsv1.AppsV1Client
    batchV1     *batchv1.BatchV1Client
    // ... 每个 API 组版本一个字段
}

核心特点:

Informer 与缓存机制

为什么需要 Informer

直接调用 API Server 存在以下问题:每次请求需要建立连接,受网络抖动影响,请求耗时高且不稳定。Informer 通过本地缓存方案解决了这些问题:

工作流程

graph TD
    A[API Server] <-->|List & Watch| B[Reflector]
    B -->|Add/Update/Delete Events| C[Delta FIFO Queue]
    C -->|Pop| D[Informer]
    D -->|更新缓存| E[Indexer / Cache]
    D -->|分发事件| F[Event Handlers
Add/Update/Delete] F -->|enqueue key| G[Workqueue] G -->|dequeue| H[Process Item / Reconcile] H -->|GetByKey| E

核心组件

Reflector(k8s.io/client-go/tools/cache)

Informer/Controller(k8s.io/client-go/tools/cache)

Indexer(k8s.io/client-go/tools/cache)

SharedIndexInformer 示例

package main

import (
    "flag"
    "fmt"
    "path/filepath"

    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/fields"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/rest"
    "k8s.io/client-go/tools/cache"
    "k8s.io/client-go/tools/clientcmd"
    "k8s.io/client-go/util/homedir"
)

func main() {
    var kubeconfig *string
    var config *rest.Config
    var err error

    if config, err = rest.InClusterConfig(); err != nil {
        if home := homedir.HomeDir(); home != "" {
            kubeconfig = flag.String("kubeconfig", filepath.Join(home, ".kube", "config"), "")
        } else {
            kubeconfig = flag.String("kubeconfig", "", "")
        }
        flag.Parse()
        config, err = clientcmd.BuildConfigFromFlags("", *kubeconfig)
        if err != nil {
            panic(err.Error())
        }
    }

    clientset, err := kubernetes.NewForConfig(config)
    if err != nil {
        panic(err.Error())
    }

    // 创建 ListerWatcher
    podListWatcher := cache.NewListWatchFromClient(
        clientset.CoreV1().RESTClient(),
        "pods",
        "kube-system",
        fields.Everything(),
    )

    // 创建 Informer
    indexer, informer := cache.NewIndexerInformer(
        podListWatcher,
        &corev1.Pod{},
        0, // ResyncPeriod,0 表示不定期重新同步
        cache.ResourceEventHandlerFuncs{
            AddFunc: func(obj interface{}) {
                pod := obj.(*corev1.Pod)
                fmt.Printf("Pod Added: %s/%s\n", pod.Namespace, pod.Name)
            },
            UpdateFunc: func(oldObj, newObj interface{}) {
                oldPod := oldObj.(*corev1.Pod)
                newPod := newObj.(*corev1.Pod)
                if oldPod.ResourceVersion == newPod.ResourceVersion {
                    return // 周期性重新同步事件,忽略
                }
                fmt.Printf("Pod Updated: %s/%s (Phase: %s -> %s)\n",
                    newPod.Namespace, newPod.Name,
                    oldPod.Status.Phase, newPod.Status.Phase)
            },
            DeleteFunc: func(obj interface{}) {
                pod, ok := obj.(*corev1.Pod)
                if !ok {
                    // 处理 DeletedFinalStateUnknown
                    tombstone, ok := obj.(cache.DeletedFinalStateUnknown)
                    if !ok {
                        return
                    }
                    pod, ok = tombstone.Obj.(*corev1.Pod)
                    if !ok {
                        return
                    }
                }
                fmt.Printf("Pod Deleted: %s/%s\n", pod.Namespace, pod.Name)
            },
        },
        cache.Indexers{cache.NamespaceIndex: cache.MetaNamespaceIndexFunc},
    )

    stopCh := make(chan struct{})
    defer close(stopCh)
    go informer.Run(stopCh)

    // 等待缓存同步
    if !cache.WaitForCacheSync(stopCh, informer.HasSynced) {
        panic("Timed out waiting for caches to sync")
    }
    fmt.Println("Informer cache synced successfully.")

    // 从本地缓存读取数据
    pods, err := indexer.ByIndex(cache.NamespaceIndex, "kube-system")
    if err != nil {
        panic(err)
    }
    for _, pod := range pods {
        fmt.Printf("Cached Pod: %s\n", pod.(*corev1.Pod).Name)
    }

    <-stopCh
}

最新 API 推荐:较新版本的 client-go 推荐使用 SharedInformerFactory 和基于 Context 的 API:

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
factory := informers.NewSharedInformerFactory(clientset, 0)
defer factory.Shutdown()

podInformer := factory.Core().V1().Pods()
podInformer.Informer().AddEventHandler(cache.ResourceEventHandlerFuncs{...})

factory.StartWithContext(ctx)
synced := factory.WaitForCacheSyncWithContext(ctx)
if err := synced.AsError(); err != nil {
    panic(err)
}

StartWithContext(ctx) 和 WaitForCacheSyncWithContext(ctx) 是推荐替代旧版 Start(stopCh) 和 WaitForCacheSync(stopCh) 的方式。

Workqueue 模式

在实际控制器中,Event Handler 不应直接处理业务逻辑。标准模式是将对象键加入 Workqueue,由 Worker 协程取出处理:

使用 DynamicClient

操作 CRD 或运行时动态确定类型的资源时使用 DynamicClient。

先部署一个 CRD:

# resourcedefinition.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              cronSpec:
                type: string
              image:
                type: string
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
    - ct
kubectl apply -f resourcedefinition.yaml

使用 DynamicClient 操作 CRD:

// 创建 DynamicClient
dynamicClient, err := dynamic.NewForConfig(config)
if err != nil {
    panic(err)
}

// 定义 GVR
gvr := schema.GroupVersionResource{
    Group:    "stable.example.com",
    Version:  "v1",
    Resource: "crontabs", // 必须是复数小写形式
}

namespace := "default"
resourceInterface := dynamicClient.Resource(gvr).Namespace(namespace)

// 创建 Unstructured 对象
cronTab := &unstructured.Unstructured{
    Object: map[string]interface{}{
        "apiVersion": "stable.example.com/v1",
        "kind":       "CronTab",
        "metadata": map[string]interface{}{
            "name": "my-crontab",
        },
        "spec": map[string]interface{}{
            "cronSpec": "* * * * */5",
            "image":    "my-awesome-cron-image",
        },
    },
}

ctx := context.TODO()

// Create
createdCronTab, err := resourceInterface.Create(ctx, cronTab, metav1.CreateOptions{})
fmt.Printf("Created %s\n", createdCronTab.GetName())

// Get
gotCronTab, err := resourceInterface.Get(ctx, "my-crontab", metav1.GetOptions{})
spec, found, err := unstructured.NestedMap(gotCronTab.Object, "spec")
fmt.Printf("CronSpec is: %s\n", spec["cronSpec"])

// List
list, err := resourceInterface.List(ctx, metav1.ListOptions{})
for _, item := range list.Items {
    fmt.Printf("Listed %s\n", item.GetName())
}

控制器模式

控制器是 Kubernetes 的核心编排概念,由 client-go 的工具组合而成:

  1. Informer/SharedInformer:监听目标资源(内置资源和 CRD)
  2. Workqueue:从 Event Handler 接收对象键
  3. Reconcile Loop(协调循环):
    • Worker 从 Workqueue 取出键
    • 从 Informer 缓存获取最新对象状态
    • 比较当前状态与期望状态
    • 调用 API 执行操作使状态收敛
    • 成功则移除键,失败则重新入队重试

最佳实践

  1. 使用 Informer 和缓存:永远不要在控制器主循环中直接调用 List()/Get() API Server,通过 Informer 的 Lister() 读取缓存数据
  2. 合理使用 Context:为所有 API 调用传递 context.Context,实现超时和取消,防止 goroutine 泄漏
  3. 乐观并发控制:Update 操作依赖 ResourceVersion 检查,版本不匹配会失败,需处理冲突并重试
  4. 处理速率限制:API Server 有速率限制,client-go 自动指数退避重试 429 错误,但应通过缓存减少请求量

故障排查

启用详细日志

client-go 使用 klog 日志库,可通过命令行参数或 Config 启用详细日志:

// 方式一:命令行参数
import "k8s.io/klog/v2"

func main() {
    klog.InitFlags(nil)
    flag.Parse()
    // 运行时加 -v=6 启用详细日志
}

// 方式二:Transport 调试
func debugConfig(config *rest.Config) {
    config.WrapTransport = func(rt http.RoundTripper) http.RoundTripper {
        return transport.NewDebuggingRoundTripper(rt, transport.DebugCurlCommand)
    }
}

常见错误处理

k8s.io/apimachinery/pkg/api/errors 包提供了错误类型判断函数:

import apierrors "k8s.io/apimachinery/pkg/api/errors"

pod, err := clientset.CoreV1().Pods("default").Get(ctx, "my-pod", metav1.GetOptions{})
if err != nil {
    if apierrors.IsNotFound(err) {
        fmt.Println("Pod not found, needs to be created")
    } else if apierrors.IsAlreadyExists(err) {
        fmt.Println("Pod already exists")
    } else if apierrors.IsConflict(err) {
        fmt.Println("Update conflict, retry needed")
    } else if apierrors.IsServerTimeout(err) || apierrors.IsTooManyRequests(err) {
        fmt.Println("Server is overloaded, retry later")
    } else {
        panic(err)
    }
}