k8s

README

k8s

Kubernetes 客户端封装——客户端构建 / Lease 选主

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/k8s@v0.1.2

这个仓库做什么

k8s 是 Kubernetes 客户端封装：一套配置解析出 rest.Config 并构建 Clientset/DynamicClient（in-cluster 自动优先，逐级回退 kubeconfig）， 外加 Lease 选主简化封装（leaderelection）适配主备/单活场景。

零可观测性副作用：不自动注入任何 tracing/logger 后端；SDK 内部统一 logx.Delegating("k8s") 懒解析。

组成

包	import 路径	做什么
k8s（模块根包）	github.com/oekit/k8s	RESTConfig（解析顺序：显式 KubeconfigPath → in-cluster → KUBECONFIG → ~/.kube/config；QPS/Burst 默认 50/100、UserAgent 默认 oekit-k8s）、NewClientset、NewDynamicClient（CRD/GVR）、InCluster() 环境探测
leaderelection	github.com/oekit/k8s/leaderelection	Lease 选主简化封装：New/Run（阻塞当选）+ OnStartedLeading/OnStoppedLeading/OnNewLeader 回调；Namespace 默认 POD_NAMESPACE → default；仅要求 Lease get/create/update 权限

快速使用

import (
    k8s "github.com/oekit/k8s"
    "github.com/oekit/k8s/leaderelection"
)

// 集群内自动走 ServiceAccount；开发机走 KUBECONFIG/~/.kube/config
cs, err := k8s.NewClientset(k8s.Config{})
pods, _ := cs.CoreV1().Pods("default").List(ctx, metav1.ListOptions{})

// 主备单活：只有 leader 跑业务，失权即退出交由重启
err = leaderelection.Run(ctx, cs, leaderelection.Config{
    LeaseName: "my-app",
    OnStartedLeading: func(ctx context.Context) { serve(ctx) },
    OnStoppedLeading: func() { log.Fatal("lost leadership") },
})

客户端限流

client-go 默认 QPS 5/Burst 10 对 controller 类负载偏保守；本仓默认 QPS 50/Burst 100，可用 Config{QPS: ..., Burst: ...} 覆盖。 Timeout 默认 0（不设单请求超时）——Watch/长流式调用必须保持 0。

边界

• 不封装 informer/cache 体系（v0.1.0 YAGNI，直接用 client-go 原生）
• 不做 kubectl 类资源运维封装
• 测试：配置解析用临时 kubeconfig，选主用 fake clientset——不依赖真实 apiserver

License

MIT

矩阵总览（24 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 19 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap；v0.10.0 起 uidgen/validator 拆至 kitx）；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约 + Checker；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试	pkg
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入	—
core	应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version）	—
kitx	标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail），自 pkg v0.10.0 拆出	pkg
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge	core、logx
data	数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；all/ 聚合模块已废弃 retract	concurrency、gormx、logx、pkg、redisx、timertask
gormx	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名）	logx、pkg
redisx	Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）	concurrency、logx、pkg
etcdx	etcd 全家——客户端封装（根包：生产默认值/Health 探活/Close(ctx) 幂等）、registry 注册发现实现（SPI 对接 registry/nacos 链路：Lease KeepAlive 注册 + 丢约指数退避自动重注册、prefix Watch 订阅推送、ConfigStore KV 配置监听）、distlock 分布式锁（Session+concurrency.Mutex 公平排队，接口与 redisx/distlock.Locker 同形可互换，可选无 etcd 降级放行）	concurrency、core、logx、registry
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传/一致性哈希（权重感知虚拟副本）	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）	concurrency、core、logx、metrics、pkg、registry、tracing
k8s	Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限）	logx
nns	NNS 服务治理客户端——provider 无关发现/配置/实例缓存	concurrency、core、logx、registry
nns-endpoint	NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——bootstrap.Run 骨架 + healthz	concurrency、logx
hertz	Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）	bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

Documentation

Overview

Package k8s 提供 Kubernetes 客户端封装：RESTConfig/Clientset/DynamicClient 构建（in-cluster 自动优先，回退 kubeconfig）与 Lease 选主简化封装 （leaderelection 子包，适配主备/单活场景）。

零可观测性副作用：不自动注入任何 tracing/logger 后端，SDK 内部统一 logx.Delegating("k8s") 懒解析。

快速接入

// 集群内（Pod）自动走 ServiceAccount；开发机走 KUBECONFIG/~/.kube/config
cs, err := k8s.NewClientset(k8s.Config{})

// 显式 kubeconfig
cs, err := k8s.NewClientset(k8s.Config{KubeconfigPath: "/path/to/kubeconfig"})

选主（同 kube-apiserver Lease 协议，二进制/多副本单活）：

err := k8s.leaderelection.Run(ctx, cs, k8s.leaderelection.Config{
    LeaseName: "my-app",
    OnStartedLeading: func(ctx context.Context) { serve(ctx) },
    OnStoppedLeading: func() { log.Fatal("lost leadership") },
})

Index

• func DefaultKubeconfigPath() string
• func InCluster() bool
• func NewClientset(cfg Config) (*kubernetes.Clientset, error)
• func NewDynamicClient(cfg Config) (dynamic.Interface, error)
• func RESTConfig(cfg Config) (*rest.Config, error)
• type Config

Functions

func DefaultKubeconfigPath

func DefaultKubeconfigPath() string

DefaultKubeconfigPath 返回当前用户家目录下的默认 kubeconfig 路径 （HOME 不可用时返回空串）。

func InCluster

func InCluster() bool

InCluster 判断当前进程是否运行在集群内（POD 环境注入了非空的 KUBERNETES_SERVICE_HOST/PORT）。

func NewClientset

func NewClientset(cfg Config) (*kubernetes.Clientset, error)

NewClientset 构建带全部内置资源组的客户端（典型入口）。

func NewDynamicClient

func NewDynamicClient(cfg Config) (dynamic.Interface, error)

NewDynamicClient 构建非资源型动态客户端（CRD/GVR 操作）。

func RESTConfig

func RESTConfig(cfg Config) (*rest.Config, error)

RESTConfig 按配置解析出 *rest.Config（连接参数已应用）。

解析顺序：显式 KubeconfigPath > in-cluster（ServiceAccount）> KUBECONFIG 环境变量 > ~/.kube/config。

Types

type Config

type Config struct {
	// KubeconfigPath 显式指定 kubeconfig 路径；设置后不再探测 in-cluster。
	// 为空时：集群内环境（POD）自动使用 ServiceAccount，本机回退
	// KUBECONFIG 环境变量，再回退 ~/.kube/config。
	KubeconfigPath string `yaml:"kubeconfigPath"`
	// QPS/Burst 是客户端限流（默认 50/100——client-go 默认 5/10 对
	// controller 类负载偏保守）。
	QPS   float32 `yaml:"qps"`
	Burst int     `yaml:"burst"`
	// Timeout 是单请求超时；0 表示不设（Watch/长流式调用必须保持 0）。
	Timeout time.Duration `yaml:"timeout"`
	// UserAgent 是请求 UA（默认 "oekit-k8s"，便于 apiserver 审计归因）。
	UserAgent string `yaml:"userAgent"`
	// InsecureSkipTLSVerify 跳过 TLS 校验（仅开发/联调，勿用于生产）。
	InsecureSkipTLSVerify bool `yaml:"insecureSkipTLSVerify"`
}

Config 是客户端构建配置。