尧图网页设计 
Cilium Operator 控制面故障排查cilium-operator troubleshoot kvstore命令详解【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本指南围绕 Cilium 项目中cilium-operator troubleshoot kvstore命令展开深入讲解该命令如何对 Operator 与 etcd 键值存储KVStore之间的连接进行系统性诊断覆盖配置解析、DNS 解析、TCP/TLS 握手、证书校验与授权验证等完整检查链路。读者学完本文后将掌握该命令的全部参数用法、输出信息的逐段解读方法以及结合源码定位 etcd 连接故障根因的实战能力。命令概述cilium-operator troubleshoot kvstore是cilium-operator提供的控制面连接故障排查工具之一用于检查 Operator 到 etcd KVStore 的连通性。它是cilium-operator troubleshoot子命令树详见 cilium-operator troubleshoot 命令文档中的一员同级的还有troubleshoot clustermesh检查到远端集群的连通性。该命令并非独立实现而是复用了 Cilium 命令行工具cilium-dbg中的troubleshoot命令包。从源码 operator/cmd/root.go 可以看到Operator 的根命令在构建时直接通过troubleshoot.Cmd注册了该子命令troubleshoot.DisableLocalNameLookup true cmd.AddCommand( cmdref.NewCmd(cmd), MetricsCmd, StatusCmd, troubleshoot.Cmd, hive.CiliumShellCmd, h.Command(), )因此在启用了 etcd KVStore 模式的 Cilium 集群中这条命令是运维人员排查Operator 连不上 etcd问题的首选工具。命令语法与参数cilium-operator troubleshoot kvstore [flags]参数一览参数说明默认值--etcd-config stringetcd 配置文件的路径/var/lib/etcd-config/etcd.config-h, --help显示帮助信息---timeout duration检查 kvstore 连通性的超时时间5s--without-service-resolution禁用通过 k8s client 进行 Service 到 IP 的解析false以上参数定义与默认值与源码 cilium-dbg/cmd/troubleshoot/troubleshoot_kvstore.go 中的 flag 注册完全一致flags.StringVar(cfg, etcd-config, /var/lib/etcd-config/etcd.config, Path to the etcd configuration) flags.DurationVar(timeout, timeout, 5*time.Second, Timeout when checking connectivity to the kvstore) flags.BoolVar(disableDialer, without-service-resolution, false, Disable k8s service to IP resolution through the k8s client)参数细节说明--etcd-config指向 etcd 客户端配置文件。默认路径/var/lib/etcd-config/etcd.config与 Helm 模板中挂载的配置一致——在 install/kubernetes/cilium/templates/cilium-agent/daemonset.yaml 中etcd-config-path卷被挂载到/var/lib/etcd-config而 install/kubernetes/cilium/templates/cilium-configmap.yaml 中通过kvstore-opt: {etcd.config: /var/lib/etcd-config/etcd.config}指定了该配置文件。--timeout整个检查过程的超时上限默认 5 秒。若网络环境延迟较高例如跨区域访问 etcd可适当调大。--without-service-resolution默认情况下命令会尝试利用 Kubernetes client 将配置中的 Service 主机名如cilium-etcd.kube-system.svc解析为 ClusterIP以模拟 Cilium Agent 的拨号行为Agent 默认使用宿主 DNS 而非 CoreDNS避免循环依赖。传入该参数后则直接使用系统默认解析器。检查流程与实现原理命令的核心执行逻辑非常清晰先检查配置文件是否存在再调用kvstore.EtcdDbg完成逐层诊断。命令入口见 troubleshoot_kvstore.go// Check if the etcd configuration file does not exist, to provide a more // helpful error in case this is expected as Cilium is running in CRD mode. if _, err : os.Stat(cfg); errors.Is(err, os.ErrNotExist) { fmt.Fprintf(stdout, Unable to read etcd configuration: %s\n, cfg) fmt.Fprintf(stdout, This is expected when Cilium is running in CRD mode\n) return } dialer : newTroubleshootDialer(cmd.ErrOrStderr(), disableDialer) cctx, cancel : context.WithTimeout(cmd.Context(), timeout) kvstore.EtcdDbg(cctx, cfg, dialer, stdout) cancel()一个值得注意的细节当 etcd 配置文件不存在时命令不会报错崩溃而是友好提示This is expected when Cilium is running in CRD mode。这是因为 Cilium 的 KVStore 后端并非必需——当集群使用 CRD 模式kvstoreetcd未启用时/var/lib/etcd-config/etcd.config本来就不存在此时无需继续检查。诊断主流程EtcdDbgEtcdDbg是诊断的核心函数位于 pkg/kvstore/etcd_debug.go。它按以下顺序输出检查结果配置文件解析使用clientyaml.NewConfig(cfgfile)解析 etcd 配置。若解析失败输出❌ Cannot parse etcd configuration。Endpoints 检查读取配置中的所有 etcd endpoint对每个 endpoint 逐一执行连通性诊断见下文etcdDbgEndpoint。数字证书检查读取配置中的 Root CA 与客户端证书逐个解析并尝试校验见下文etcdDbgCerts。Etcd 客户端验证基于解析出的配置创建真实 etcd clientv3并以 1 秒超时尝试Get心跳键HeartbeatPath作为基础的授权验证。若连接处于TransientFailure状态则提示连接建立失败否则提示键读取失败成功则输出✅ Etcd connection successfully established及 etcd 集群 ID。单端点诊断etcdDbgEndpoint对每个 endpointetcdDbgEndpoint 依次执行四层检查每层失败都会给出明确提示检查层次输出示例说明URL 解析❌ Cannot parse endpointendpoint 是否为合法 URL主机名解析✅ Hostname resolved to: 10.0.0.1, ...通过 dialer 的LookupIP解析主机名最多展示 4 个 IPTCP 连接✅ TCP connection successfully established to ...通过DialContext建立 TCP 连接TLS 连接✅ TLS connection successfully established to ...仅当 scheme 为https时执行含握手与证书校验TLS 层检查尤其细致值得单独说明服务端证书校验代码设置了InsecureSkipVerify并手动通过VerifyPeerCertificate回调模拟完整的证书链校验使用配置中的 Root CAs 和 ServerName 验证这样做的目的是在握手失败时也能拿到服务端证书详情用于诊断。客户端证书选择通过GetClientCertificate回调选择证书当客户端证书不匹配 etcd 服务端要求的 CA 时会输出client certificate is not signed by any acceptable CA错误并打印服务端可接受的 CA 列表。TLS 1.3 客户端认证验证TLS 1.3 下服务端不会在握手中确认客户端认证是否成功错误只会在数据读写时暴露。因此代码主动构造GET /versionHTTP 请求触发一次读写若读回remote error则判定为❌ TLS client authentication failed成功则可解析出 etcd server 版本输出ℹ️ Etcd server version: ...。证书检查etcdDbgCertsetcdDbgCerts 负责输出配置中证书的详细诊断Root CA若未配置则提示⚠️ Root CA unset: using system pool若配置了trusted-ca-file则解析 PEM 文件并逐个输出证书详情。客户端证书无证书时提示⚠️ No available TLS client certificates有证书则输出叶子证书与中间证书详情并尝试用配置的 Root CAs 校验客户端证书链失败时输出⚠️ Cannot verify certificate with the configured root CAs提示这并非一定错误但多数情况下意味着配置不一致。用户名/密码若配置了username输出用户名是否设置、密码是否设置不泄露明文。证书详情输出包括序列号、Subject、Subject alternative names、Subject key ID、Issuer、Authority key ID、有效期Not before / Not after。对应实现见 etcdDbgOutputCert。服务名到 IP 的解析 dialer默认情况下不传--without-service-resolution命令会构造一个特殊的 dialer用于把 etcd 配置中的 Kubernetes Service 主机名解析为 ClusterIP。其实现位于 cilium-dbg/cmd/troubleshoot/troubleshoot.go通过rest.InClusterConfig()尝试在 Pod 内初始化 Kubernetes client命令通常运行在 Cilium Operator Pod 内若初始化失败打印⚠️ Could not initialize k8s client, service resolution may not work并回退到默认 dialer若成功则按namespace/name查询 Service 的ClusterIP并做缓存解析失败时回退到系统解析器。这一设计是为了精确复刻 Cilium Agent 的 etcd 拨号路径——Agent 默认不使用 CoreDNS而是自行把 Service 名解析成 ClusterIP从而规避 DNS 循环依赖。诊断时使用同样的解析逻辑才能真实还原故障现场。典型使用场景场景一Operator 报 etcd 连接错误当 Cilium Operator 日志中出现 etcd 连接失败、leader 选举异常或 KVStore 心跳超时时可进入 Operator Pod 执行kubectl -n kube-system exec -it deploy/cilium-operator -- \ cilium-operator troubleshoot kvstore输出将按上文所述的层次逐一给出检查结果根据每个❌的位置即可快速定位故障层。场景二自定义 etcd 配置路径若 etcd 配置文件不在默认路径例如通过--etcd-config指定了其他位置显式传入路径cilium-operator troubleshoot kvstore --etcd-config /etc/cilium/etcd.config场景三非 Pod 环境手动执行在 Operator 容器外如本机运行无法初始化 in-cluster k8s client 时可禁用 Service 解析直接用系统 DNS 解析主机名cilium-operator troubleshoot kvstore --without-service-resolution --timeout 10s检查结果解读速查输出含义建议动作Unable to read etcd configuration ... expected when Cilium is running in CRD mode配置文件不存在若使用 CRD 模式则属正常若预期使用 etcd 模式需检查 ConfigMap/Helm 挂载❌ Cannot parse etcd configuration配置文件格式错误检查 YAML 格式及字段❌ No available endpoints配置中无 endpoint在配置中补充endpoints❌ Cannot resolve hostnameDNS 解析失败检查 Service 是否存在、ClusterIP 是否分配❌ Cannot establish TCP connection网络层不通检查网络策略、防火墙、Service/Endpoint 状态❌ Cannot establish TLS connection/❌ TLS client authentication failedTLS 握手或双向认证失败核对 CA、客户端证书、ServerName 是否匹配❌ Failed to retrieve key from etcd授权/权限不足检查 etcd 用户名密码、RBAC 与证书权限✅ Etcd connection successfully established全部检查通过无需处理与源码测试的印证诊断输出中的 IP 格式化逻辑由 TestEtcdDbgOutputIPs 覆盖测试验证了单 IPv4 / 单 IPv6 的展示格式IPv4-mapped IPv6 地址::ffff:10.0.0.1会被还原为 IPv4 展示超过 4 个 IP 时截断并以...结尾。从该测试可以看到解析结果展示最多前 4 个 IP避免输出过长。总结cilium-operator troubleshoot kvstore是排查 Cilium 控制面与 etcd 连通性的一站式诊断工具。它把配置解析、DNS、TCP、TLS、证书、授权六类检查整合为一次命令执行输出带图标与缩进的可读化结果并且与 Agent 的拨号路径保持一致Service 名到 ClusterIP 解析能够真实还原故障现场。配合 etcd_debug.go 的实现细节与上文的结果解读速查表运维人员可以在分钟级时间内定位绝大多数 etcd 连接类问题。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium Operator 控制面故障排查：`cilium-operator troubleshoot kvstore` 命令详解
Cilium Operator 控制面故障排查cilium-operator troubleshoot kvstore命令详解【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本指南围绕 Cilium 项目中cilium-operator troubleshoot kvstore命令展开深入讲解该命令如何对 Operator 与 etcd 键值存储KVStore之间的连接进行系统性诊断覆盖配置解析、DNS 解析、TCP/TLS 握手、证书校验与授权验证等完整检查链路。读者学完本文后将掌握该命令的全部参数用法、输出信息的逐段解读方法以及结合源码定位 etcd 连接故障根因的实战能力。命令概述cilium-operator troubleshoot kvstore是cilium-operator提供的控制面连接故障排查工具之一用于检查 Operator 到 etcd KVStore 的连通性。它是cilium-operator troubleshoot子命令树详见 cilium-operator troubleshoot 命令文档中的一员同级的还有troubleshoot clustermesh检查到远端集群的连通性。该命令并非独立实现而是复用了 Cilium 命令行工具cilium-dbg中的troubleshoot命令包。从源码 operator/cmd/root.go 可以看到Operator 的根命令在构建时直接通过troubleshoot.Cmd注册了该子命令troubleshoot.DisableLocalNameLookup true cmd.AddCommand( cmdref.NewCmd(cmd), MetricsCmd, StatusCmd, troubleshoot.Cmd, hive.CiliumShellCmd, h.Command(), )因此在启用了 etcd KVStore 模式的 Cilium 集群中这条命令是运维人员排查Operator 连不上 etcd问题的首选工具。命令语法与参数cilium-operator troubleshoot kvstore [flags]参数一览参数说明默认值--etcd-config stringetcd 配置文件的路径/var/lib/etcd-config/etcd.config-h, --help显示帮助信息---timeout duration检查 kvstore 连通性的超时时间5s--without-service-resolution禁用通过 k8s client 进行 Service 到 IP 的解析false以上参数定义与默认值与源码 cilium-dbg/cmd/troubleshoot/troubleshoot_kvstore.go 中的 flag 注册完全一致flags.StringVar(cfg, etcd-config, /var/lib/etcd-config/etcd.config, Path to the etcd configuration) flags.DurationVar(timeout, timeout, 5*time.Second, Timeout when checking connectivity to the kvstore) flags.BoolVar(disableDialer, without-service-resolution, false, Disable k8s service to IP resolution through the k8s client)参数细节说明--etcd-config指向 etcd 客户端配置文件。默认路径/var/lib/etcd-config/etcd.config与 Helm 模板中挂载的配置一致——在 install/kubernetes/cilium/templates/cilium-agent/daemonset.yaml 中etcd-config-path卷被挂载到/var/lib/etcd-config而 install/kubernetes/cilium/templates/cilium-configmap.yaml 中通过kvstore-opt: {etcd.config: /var/lib/etcd-config/etcd.config}指定了该配置文件。--timeout整个检查过程的超时上限默认 5 秒。若网络环境延迟较高例如跨区域访问 etcd可适当调大。--without-service-resolution默认情况下命令会尝试利用 Kubernetes client 将配置中的 Service 主机名如cilium-etcd.kube-system.svc解析为 ClusterIP以模拟 Cilium Agent 的拨号行为Agent 默认使用宿主 DNS 而非 CoreDNS避免循环依赖。传入该参数后则直接使用系统默认解析器。检查流程与实现原理命令的核心执行逻辑非常清晰先检查配置文件是否存在再调用kvstore.EtcdDbg完成逐层诊断。命令入口见 troubleshoot_kvstore.go// Check if the etcd configuration file does not exist, to provide a more // helpful error in case this is expected as Cilium is running in CRD mode. if _, err : os.Stat(cfg); errors.Is(err, os.ErrNotExist) { fmt.Fprintf(stdout, Unable to read etcd configuration: %s\n, cfg) fmt.Fprintf(stdout, This is expected when Cilium is running in CRD mode\n) return } dialer : newTroubleshootDialer(cmd.ErrOrStderr(), disableDialer) cctx, cancel : context.WithTimeout(cmd.Context(), timeout) kvstore.EtcdDbg(cctx, cfg, dialer, stdout) cancel()一个值得注意的细节当 etcd 配置文件不存在时命令不会报错崩溃而是友好提示This is expected when Cilium is running in CRD mode。这是因为 Cilium 的 KVStore 后端并非必需——当集群使用 CRD 模式kvstoreetcd未启用时/var/lib/etcd-config/etcd.config本来就不存在此时无需继续检查。诊断主流程EtcdDbgEtcdDbg是诊断的核心函数位于 pkg/kvstore/etcd_debug.go。它按以下顺序输出检查结果配置文件解析使用clientyaml.NewConfig(cfgfile)解析 etcd 配置。若解析失败输出❌ Cannot parse etcd configuration。Endpoints 检查读取配置中的所有 etcd endpoint对每个 endpoint 逐一执行连通性诊断见下文etcdDbgEndpoint。数字证书检查读取配置中的 Root CA 与客户端证书逐个解析并尝试校验见下文etcdDbgCerts。Etcd 客户端验证基于解析出的配置创建真实 etcd clientv3并以 1 秒超时尝试Get心跳键HeartbeatPath作为基础的授权验证。若连接处于TransientFailure状态则提示连接建立失败否则提示键读取失败成功则输出✅ Etcd connection successfully established及 etcd 集群 ID。单端点诊断etcdDbgEndpoint对每个 endpointetcdDbgEndpoint 依次执行四层检查每层失败都会给出明确提示检查层次输出示例说明URL 解析❌ Cannot parse endpointendpoint 是否为合法 URL主机名解析✅ Hostname resolved to: 10.0.0.1, ...通过 dialer 的LookupIP解析主机名最多展示 4 个 IPTCP 连接✅ TCP connection successfully established to ...通过DialContext建立 TCP 连接TLS 连接✅ TLS connection successfully established to ...仅当 scheme 为https时执行含握手与证书校验TLS 层检查尤其细致值得单独说明服务端证书校验代码设置了InsecureSkipVerify并手动通过VerifyPeerCertificate回调模拟完整的证书链校验使用配置中的 Root CAs 和 ServerName 验证这样做的目的是在握手失败时也能拿到服务端证书详情用于诊断。客户端证书选择通过GetClientCertificate回调选择证书当客户端证书不匹配 etcd 服务端要求的 CA 时会输出client certificate is not signed by any acceptable CA错误并打印服务端可接受的 CA 列表。TLS 1.3 客户端认证验证TLS 1.3 下服务端不会在握手中确认客户端认证是否成功错误只会在数据读写时暴露。因此代码主动构造GET /versionHTTP 请求触发一次读写若读回remote error则判定为❌ TLS client authentication failed成功则可解析出 etcd server 版本输出ℹ️ Etcd server version: ...。证书检查etcdDbgCertsetcdDbgCerts 负责输出配置中证书的详细诊断Root CA若未配置则提示⚠️ Root CA unset: using system pool若配置了trusted-ca-file则解析 PEM 文件并逐个输出证书详情。客户端证书无证书时提示⚠️ No available TLS client certificates有证书则输出叶子证书与中间证书详情并尝试用配置的 Root CAs 校验客户端证书链失败时输出⚠️ Cannot verify certificate with the configured root CAs提示这并非一定错误但多数情况下意味着配置不一致。用户名/密码若配置了username输出用户名是否设置、密码是否设置不泄露明文。证书详情输出包括序列号、Subject、Subject alternative names、Subject key ID、Issuer、Authority key ID、有效期Not before / Not after。对应实现见 etcdDbgOutputCert。服务名到 IP 的解析 dialer默认情况下不传--without-service-resolution命令会构造一个特殊的 dialer用于把 etcd 配置中的 Kubernetes Service 主机名解析为 ClusterIP。其实现位于 cilium-dbg/cmd/troubleshoot/troubleshoot.go通过rest.InClusterConfig()尝试在 Pod 内初始化 Kubernetes client命令通常运行在 Cilium Operator Pod 内若初始化失败打印⚠️ Could not initialize k8s client, service resolution may not work并回退到默认 dialer若成功则按namespace/name查询 Service 的ClusterIP并做缓存解析失败时回退到系统解析器。这一设计是为了精确复刻 Cilium Agent 的 etcd 拨号路径——Agent 默认不使用 CoreDNS而是自行把 Service 名解析成 ClusterIP从而规避 DNS 循环依赖。诊断时使用同样的解析逻辑才能真实还原故障现场。典型使用场景场景一Operator 报 etcd 连接错误当 Cilium Operator 日志中出现 etcd 连接失败、leader 选举异常或 KVStore 心跳超时时可进入 Operator Pod 执行kubectl -n kube-system exec -it deploy/cilium-operator -- \ cilium-operator troubleshoot kvstore输出将按上文所述的层次逐一给出检查结果根据每个❌的位置即可快速定位故障层。场景二自定义 etcd 配置路径若 etcd 配置文件不在默认路径例如通过--etcd-config指定了其他位置显式传入路径cilium-operator troubleshoot kvstore --etcd-config /etc/cilium/etcd.config场景三非 Pod 环境手动执行在 Operator 容器外如本机运行无法初始化 in-cluster k8s client 时可禁用 Service 解析直接用系统 DNS 解析主机名cilium-operator troubleshoot kvstore --without-service-resolution --timeout 10s检查结果解读速查输出含义建议动作Unable to read etcd configuration ... expected when Cilium is running in CRD mode配置文件不存在若使用 CRD 模式则属正常若预期使用 etcd 模式需检查 ConfigMap/Helm 挂载❌ Cannot parse etcd configuration配置文件格式错误检查 YAML 格式及字段❌ No available endpoints配置中无 endpoint在配置中补充endpoints❌ Cannot resolve hostnameDNS 解析失败检查 Service 是否存在、ClusterIP 是否分配❌ Cannot establish TCP connection网络层不通检查网络策略、防火墙、Service/Endpoint 状态❌ Cannot establish TLS connection/❌ TLS client authentication failedTLS 握手或双向认证失败核对 CA、客户端证书、ServerName 是否匹配❌ Failed to retrieve key from etcd授权/权限不足检查 etcd 用户名密码、RBAC 与证书权限✅ Etcd connection successfully established全部检查通过无需处理与源码测试的印证诊断输出中的 IP 格式化逻辑由 TestEtcdDbgOutputIPs 覆盖测试验证了单 IPv4 / 单 IPv6 的展示格式IPv4-mapped IPv6 地址::ffff:10.0.0.1会被还原为 IPv4 展示超过 4 个 IP 时截断并以...结尾。从该测试可以看到解析结果展示最多前 4 个 IP避免输出过长。总结cilium-operator troubleshoot kvstore是排查 Cilium 控制面与 etcd 连通性的一站式诊断工具。它把配置解析、DNS、TCP、TLS、证书、授权六类检查整合为一次命令执行输出带图标与缩进的可读化结果并且与 Agent 的拨号路径保持一致Service 名到 ClusterIP 解析能够真实还原故障现场。配合 etcd_debug.go 的实现细节与上文的结果解读速查表运维人员可以在分钟级时间内定位绝大多数 etcd 连接类问题。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考