Cilium Operator Azure Troubleshoot 命令详解控制面 etcd 与 ClusterMesh 连通性排查实战指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文围绕 Cilium 仓库中cilium-operator-azure二进制提供的troubleshoot命令族展开深入讲解如何利用它对控制面关键依赖etcd kvstore、远端集群 ClusterMesh 配置进行快速连通性体检。读完本文你将掌握troubleshoot kvstore与troubleshoot clustermesh两条命令的参数语义、典型输出解读以及其底层基于 etcd_debug.go 的 DNS → TCP → TLS → 业务请求四级检查流水线能够在 Azure 集群中直接落地执行。一、命令概览cilium-operator-azure troubleshootcilium-operator-azure是 Cilium Operator 面向 Azure 环境的发行形态负责 Azure 云场景下的 IPAM、身份管理等控制面任务它复用了与cilium-dbg完全一致的troubleshoot实现因此在两个二进制中该命令的用法和输出完全等价。命令短描述为Run troubleshooting utilities to check control-plane connectivity即运行排查工具以检查控制面连通性它不修改任何状态只做只读的健康检查安全地在生产环境运行。命令层级如下cilium-operator-azure troubleshoot ├── cilium-operator-azure troubleshoot clustermesh # 排查到远端集群的连通性 └── cilium-operator-azure troubleshoot kvstore # 排查到 etcd kvstore 的连通性从源码看troubleshoot主命令定义在 cilium-dbg/cmd/troubleshoot/troubleshoot.go而 Operator 在装配命令时将其注册为自己的子命令并额外设置了一个关键开关见 operator/cmd/root.gotroubleshoot.DisableLocalNameLookup true cmd.AddCommand( cmdref.NewCmd(cmd), MetricsCmd, StatusCmd, troubleshoot.Cmd, hive.CiliumShellCmd, h.Command(), )DisableLocalNameLookup true表示 Operator 场景下不会主动去 Cilium API 查询本集群名称agent 场景才需要这一点在后面的 clustermesh 子命令中会展开解释。二、子命令一troubleshoot kvstore— 排查 etcd 连通性2.1 命令语法与参数cilium-operator-azure troubleshoot kvstore [flags]该子命令用于检查 Operator 到 etcd kvstore 的完整连接链路。完整的参数说明如下源自 cilium-operator-azure_troubleshoot_kvstore.md参数说明默认值--etcd-config stringetcd 配置文件路径/var/lib/etcd-config/etcd.config--timeout duration检查 kvstore 连通性的超时时间5s--without-service-resolution禁用通过 k8s client 将 Service 名解析为 IPfalse-h, --help查看帮助—对应源码中的参数定义见 troubleshoot_kvstore.go其中两个默认路径与 Cilium 在 Kubernetes 环境下的标准挂载约定一致etcd 配置默认路径/var/lib/etcd-config/etcd.config这正是 etcd 模式--kvstore etcd下以 Secret 方式挂载的配置文件位置超时默认 5 秒足够覆盖控制面一般的网络往返又不会在故障时长时间卡住。2.2 CRD 模式下的预期错误运行前命令会先检查 etcd 配置文件是否存在对应源码 troubleshoot_kvstore.go。如果文件不存在会输出如下友好提示并直接退出Unable to read etcd configuration: /var/lib/etcd-config/etcd.config This is expected when Cilium is running in CRD mode这句话是预期行为而非故障当 Cilium 以 CRD 模式--kvstore crd运行时身份与节点信息存放在 Kubernetes CRD 而非 etcd 中根本没有 etcd 配置文件此时无需排查。2.3 它到底检查了什么底层EtcdDbg流水线kvstore 子命令的核心调用是kvstore.EtcdDbg(cctx, cfg, dialer, stdout)见 troubleshoot_kvstore.go。EtcdDbg实现在 pkg/kvstore/etcd_debug.go它按顺序执行一整套分层体检并以 emoji 标记输出每步结果配置解析读取并解析 etcd YAML 配置 Configuration path解析失败输出❌ Cannot parse etcd configuration。端点枚举遍历cfg.Endpoints中每一个端点 Endpoints。主机名解析若端点是域名而非 IP先做 DNS 解析✅ Hostname resolved to: .../❌ Cannot resolve hostname。TCP 建连对每个端点做 TCP 拨号✅ TCP connection successfully established/❌ Cannot establish TCP connection。TLS 握手对https端点进行 TLS 握手并输出协商版本与密码套件ℹ️ Negotiated TLS version ... ciphersuite ...同时列出服务端证书链握手失败时会额外打印服务端可接受的 CAℹ️ Acceptable CAs。etcd 客户端与授权检查用与真实 Agent/Operator 相同的客户端配置建立 etcd client并在 1 秒超时内尝试读取 heartbeat keyHeartbeatPath作为最基础的用户/证书授权验证✅ Etcd connection successfully established成功时还会打印 etcd 集群 IDℹ️ Etcd cluster ID。其中第 5 步的实现细节值得一提源码在 etcd_debug.go 中设置了InsecureSkipVerify true并手动通过VerifyPeerCertificate复刻标准证书校验目的仅仅是为了在握手失败时也能拿到服务端证书链用于诊断校验逻辑本身并未放宽。2.4 一个关键设计Service 名解析为什么会有--without-service-resolution这个开关因为 Cilium Agent/Operator 在 pod 中默认使用宿主网络命名空间的 DNShost DNS而非 CoreDNS以避免循环依赖——这导致 etcd 配置里的 Service 名如cilium-etcd-client.kube-system.svc在排查时可能解析不到。为此newTroubleshootDialer见 troubleshoot.go会尝试用 in-cluster 的 k8s client 把 Service 名直接翻译成 ClusterIP若初始化 k8s client 失败打印警告⚠️ Could not initialize k8s client, service resolution may not work并回退到系统默认解析器若传入--without-service-resolution则直接使用kvstore.DefaultEtcdDbgDialer{}即系统 DNS 普通 TCP 拨号见 etcd_debug.go。Service→ClusterIP 的解析逻辑troubleshootDialer.resolve会先尝试把主机名解析为namespace/name查 Service 的ClusterIP并带内存缓存解析失败则回退系统解析器见 troubleshoot.go。三、子命令二troubleshoot clustermesh— 排查到远端集群的连通性3.1 命令语法与参数cilium-operator-azure troubleshoot clustermesh [clusters...] [flags]该子命令用于检查 Operator 到 ClusterMesh 远端集群的 etcd 配置连通性可以指定一个或多个集群名做定向排查不指定则检查全部。参数说明源自 cilium-operator-azure_troubleshoot_clustermesh.md参数说明默认值--clustermesh-config stringClusterMesh 配置目录路径/var/lib/cilium/clustermesh/--timeout duration检查单个集群连通性的超时时间5s--H string服务端 API 的 URICilium API空--without-service-resolution禁用通过 k8s client 将 Service 名解析为 IPfalse-h, --help查看帮助—3.2 执行流程与输出解读对应实现位于 troubleshoot_clustermesh.go流程如下扫描配置目录调用common.ConfigFiles(cfgdir)见 pkg/clustermesh/common/config.go读取/var/lib/cilium/clustermesh/下所有 etcd 配置文件输出Found N cluster configurations若目录不存在或为空输出Unable to retrieve cluster configurations ... This is expected when Cluster Mesh is disabled——这是未启用 ClusterMesh 时的预期提示。集群筛选与排序未传集群名则检查全部传入clusters...时输出Troubleshooting filtered subset of clusters: ...并按名称排序保证输出顺序稳定。逐个集群体检对每个集群打印Cluster name:然后若是本集群提示ℹ️ This entry corresponds to the local clusterOperator 因DisableLocalNameLookuptrue无法查询本集群名因此该提示仅在 agent 场景生效校验集群名合法性❌ Invalid cluster name对应types.ValidateClusterName找不到配置则提示❌ Configuration not found解析 Cilium 配置失败则提示❌ Could not parse Cilium config解析成功后在--timeout限定的 context 内对该集群配置执行与 kvstore 子命令完全相同的kvstore.EtcdDbg体检端点解析、TCP、TLS、heartbeat 读取等。HostAlias 静态解析如果远端集群配置中包含hostAliases指定主机名到 IP 的静态映射会构造staticEtcdDbgDialerWithFallback见 troubleshoot_clustermesh.go——先用静态映射解析未命中再回退到默认 dialer。这与 Agent 连接远端 clustermesh-apiserver 时使用dial.NewStaticHostDialer的行为保持一致确保排查路径与真实数据面路径一致。四、结合仓库源码理解为什么这套检查值得信赖troubleshoot命令的价值在于用与真实组件完全一致的配置与拨号路径做检查而非简单的ping一致的解析链kvstore 子命令复用与 Agent 相同的 Service→ClusterIP 解析 dialerclustermesh 子命令还叠加了与远端 apiserver 连接一致的 HostAlias 静态解析见 troubleshoot_clustermesh.go一致的安全校验TLS 校验使用 etcd 配置中的RootCAs与客户端证书并刻意复刻了标准校验以获取证书链用于诊断见 etcd_debug.go一致的业务探活最终以 etcd 客户端真实发起Get读取 heartbeat key 作为授权与连通性的终极验证而不是停留在 TCP 层见 etcd_debug.go主动兜底k8s client 初始化失败时降级为系统解析并给出警告保证命令在任何环境下都能运行出结果见 troubleshoot.go。五、Azure 环境实战如何运行与解读cilium-operator-azure以 Deployment 形式运行在kube-system命名空间推荐直接在其 Pod 内执行排查无需额外网络权限且默认路径天然就位# 找到 operator pod kubectl -n kube-system get pods -l namecilium-operator-azure # 1) 排查 etcd 连通性覆盖 DNS/TCP/TLS/授权全链路 kubectl -n kube-system exec deploy/cilium-operator-azure -- \ cilium-operator-azure troubleshoot kvstore # 2) 指定自定义 etcd 配置路径与更宽松的超时 kubectl -n kube-system exec deploy/cilium-operator-azure -- \ cilium-operator-azure troubleshoot kvstore \ --etcd-config /var/lib/etcd-config/etcd.config --timeout 10s # 3) 排查所有远端集群 kubectl -n kube-system exec deploy/cilium-operator-azure -- \ cilium-operator-azure troubleshoot clustermesh # 4) 只排查指定集群且关闭 Service 名解析如已知 DNS 环境异常时对比定位 kubectl -n kube-system exec deploy/cilium-operator-azure -- \ cilium-operator-azure troubleshoot clustermesh cluster-remote \ --without-service-resolution常见输出与处置建议输出特征含义建议动作❌ Cannot resolve hostnameDNS 解析失败Service 名场景确认是否存在cilium-etcd-client这类 Service可对比加/不加--without-service-resolution定位是 DNS 还是 k8s 解析问题❌ Cannot establish TCP connection网络层不通检查 NetworkPolicy、Azure NSG/安全组、服务暴露方式是否允许控制面端口etcd 2379/2380或 clustermesh-apiserver 端口✅ TCP ...但❌ Cannot establish TLS connectionTLS 握手失败检查证书是否过期、RootCAs是否匹配命令会额外打印服务端证书链与Acceptable CAs帮助比对TLS 成功但❌ Failed to retrieve key from etcd授权/鉴权问题检查客户端证书是否被 etcd 侧信任--etcd-ca-cert、RBAC 用户配置✅ Etcd connection successfully established且打印集群 ID全链路正常无需处理六、总结cilium-operator-azure troubleshoot是 Operator 控制面故障时第一现场的只读体检工具troubleshoot kvstore覆盖 Operator 与 etcd 之间从配置文件、DNS、TCP、TLS 到授权探活的全部环节troubleshoot clustermesh在此基础上批量巡检每个远端集群的配置与连通性并支持按集群名定向筛选。二者共享同一套EtcdDbg检查引擎与 Service 名解析 dialer保证排查路径与真实运行路径一致。相关命令的完整参考文档可继续阅读cilium-operator-azure 命令总览troubleshoot clustermesh 命令参考troubleshoot kvstore 命令参考【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考