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 路径格式:
- 核心组(Pod、Node 等):
/api/v1/namespaces/<NAMESPACE>/<RESOURCE>/<NAME> - 其他组:
/apis/<GROUP>/<VERSION>/namespaces/<NAMESPACE>/<RESOURCE>/<NAME>
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
}
各方法功能:
GetRateLimiter():获取速率限制器,控制请求频率Verb(verb string):根据 HTTP 方法创建Request对象Post/Put/Patch/Get/Delete:快捷方法,内部调用VerbAPIVersion():获取当前客户端的 API 版本
构造函数
// 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
}
参数说明:
baseURL:API Server 地址versionedAPIPath:API 版本路径(如/api/v1)config:内容类型配置(JSON/Protobuf)createBackoffMgr:退避管理器工厂函数(新版本已迁移为BackoffManagerWithContext,支持上下文感知)rateLimiter:速率限制器client:底层 HTTP 客户端
版本演进:近期 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 的内部流程:
- 调用
transformResponse处理响应 - 根据
Content-Type通过内容协商找到解码器 - 如果状态码非 2xx,尝试解析为
metav1.Status生成结构化错误 - 成功时返回包含 Body、解码器、状态码的
Result对象
Watch 的内部流程:
- 发起请求,HTTP 200 成功后调用
newStreamWatcher - 根据
Content-Type创建流式解码器和分帧器(Framer) - 创建
watch.StreamWatcher,在后台持续读取数据 - 通过
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
OpenAPISchema():从/openapi/v2获取 Protobuf 格式的 OpenAPI v2 文档OpenAPIV3():创建 OpenAPI v3 客户端,访问/openapi/v3端点
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 组版本一个字段
}
核心特点:
- 类型安全:每个 API 组版本有独立的强类型客户端,编译期检查
- 多版本支持:同一 API 组支持
v1、v1beta1、v1alpha1等多个版本 - 内嵌 DiscoveryClient:通过
Discovery()方法提供资源发现能力 - 底层基于 RESTClient:每个组版本客户端内部都持有一个配置好的 RESTClient
Informer 与缓存机制
为什么需要 Informer
直接调用 API Server 存在以下问题:每次请求需要建立连接,受网络抖动影响,请求耗时高且不稳定。Informer 通过本地缓存方案解决了这些问题:
- 本地缓存:通过
List获取全量数据 +Watch获取增量更新,读操作直接命中本地缓存 - 事件通知:资源变化时调用注册的事件处理函数(Add/Update/Delete)
- 减少压力:多个消费者共享同一个 Informer 和 Watch 连接
- 自动重试:内置 List 和 Watch 的重试机制,处理连接中断
工作流程
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)
- 负责监视指定的 Kubernetes 资源类型
- 核心函数
ListAndWatch:先 List 全量,再 Watch 增量 - 将变化事件转为 Delta 对象放入 Delta FIFO 队列
Informer/Controller(k8s.io/client-go/tools/cache)
- 从 Delta FIFO 队列中消费数据
- 更新 Indexer 缓存
- 分发事件给注册的 Event Handlers
Indexer(k8s.io/client-go/tools/cache)
- 线程安全的本地缓存,支持索引
- 默认键生成函数
MetaNamespaceKeyFunc,格式为<namespace>/<name> - 支持自定义索引函数(如按标签索引)
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 协程取出处理:
- 解耦:事件监听和处理逻辑分离
- 去重:Workqueue 对同一对象的多次事件自动去重
- 重试:失败任务可重新入队,支持速率限制重试
使用 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 的工具组合而成:
- Informer/SharedInformer:监听目标资源(内置资源和 CRD)
- Workqueue:从 Event Handler 接收对象键
- Reconcile Loop(协调循环):
- Worker 从 Workqueue 取出键
- 从 Informer 缓存获取最新对象状态
- 比较当前状态与期望状态
- 调用 API 执行操作使状态收敛
- 成功则移除键,失败则重新入队重试
最佳实践
- 使用 Informer 和缓存:永远不要在控制器主循环中直接调用
List()/Get()API Server,通过 Informer 的Lister()读取缓存数据 - 合理使用 Context:为所有 API 调用传递
context.Context,实现超时和取消,防止 goroutine 泄漏 - 乐观并发控制:Update 操作依赖
ResourceVersion检查,版本不匹配会失败,需处理冲突并重试 - 处理速率限制: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)
}
}