Cilium Operator 集群网格连接排障：cilium-operator-azure troubleshoot clustermesh 命令全解析
发布时间：2026/9/13 1:38:28 作者：尧图编辑部 阅读量：1,286
Cilium Operator 集群网格连接排障cilium-operator-azure troubleshoot clustermesh 命令全解析【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumcilium-operator-azure troubleshoot clustermesh是 Cilium 云运营商Operator系列二进制内置的 Cluster Mesh集群网格控制面连通性排障子命令用于逐集群诊断 Agent 与远端clustermesh-apiserver背后的 etcd kvstore 之间从 DNS 解析到 TLS 双向认证的整条链路。本文以 官方命令参考 为主体骨架结合 命令源码、kvstore 诊断核心 与 ClusterMesh 配置解析 展开读者将掌握该命令的完整选项语义、执行流程、输出解读方法及在 Azure 云运营商场景下的实际排查套路。命令定位operator 控制面诊断工具链的一部分cilium-operator-azure troubleshoot是一个命令组其下挂接多个针对控制面组件的排障子命令。从命令参考文档的 SEE ALSO 一节可以确认完整命令层级cilium-operator-azure主命令运行 cilium-operator-azurecilium-operator-azure troubleshoot排障命令组说明为 Run troubleshooting utilities to check control-plane connectivitycilium-operator-azure troubleshoot clustermesh本文主题排查与远端集群的连接cilium-operator-azure troubleshoot kvstore排查本机 etcd kvstore 连接。值得注意的是这套troubleshoot命令并非 operator 独有。从源码看operator/cmd/root.go 直接复用了cilium-dbg/cmd/troubleshoot包的命令定义troubleshoot.DisableLocalNameLookup true cmd.AddCommand( cmdref.NewCmd(cmd), MetricsCmd, StatusCmd, troubleshoot.Cmd, hive.CiliumShellCmd, h.Command(), )这里有一个关键差异点operator 通过troubleshoot.DisableLocalNameLookup true关闭了“本地集群名”的自动查询Agent 端可通过 Cilium API 获取本地 ClusterName而 operator 不具备该 API 通道仅将其作为存在本地配置时的提示信息这是 operator 与cilium-dbg中同名命令在行为上的唯一实质区别。Use描述被统一为clustermesh [clusters...]说明该命令允许传入零个或多个集群名参数。语法与选项详解命令基本语法如下cilium-operator-azure troubleshoot clustermesh [clusters...] [flags]clusters...可选的位置参数指定要排查的远端集群名列表。不传时将对配置目录中发现的所有集群逐一检查[flags]见下表。选项类型默认值说明--H stringstring空URI 到服务端 API用于 Cilium API 客户端初始化operator 场景下主要服务于本地集群名查询的兼容通道--clustermesh-config stringstring/var/lib/cilium/clustermesh/ClusterMesh 配置目录路径命令会扫描该目录下所有 etcd 配置文件作为候选集群-h, --helpbool-显示clustermesh子命令帮助--timeout durationduration5s对单个集群执行连通性检查的超时时间--without-service-resolutionboolfalse禁用通过 k8s client 进行的 Service 到 IP 的解析即禁用 k8s 服务发现拨号器这些 flag 的定义可直接在源码中找到troubleshoot_clustermesh.goflags : cmd.Flags() flags.StringVar(cfg, clustermesh-config, /var/lib/cilium/clustermesh/, Path to the ClusterMesh configuration directory) flags.DurationVar(timeout, timeout, 5*time.Second, Timeout when checking connectivity to a given cluster) flags.BoolVar(disableDialer, without-service-resolution, false, Disable k8s service to IP resolution through the k8s client) flags.StringVar(clientHost, H, , URI to server-side API)选项的行为细节--clustermesh-config命令通过 common.ConfigFiles 读取目录内容仅收集被isEtcdConfigFile判定为 etcd 配置的候选文件即标准 etcd 客户端 YAML包含endpoints、TLS 证书路径等字段。每个文件的文件名即视为集群名。如果目录不存在或不可读命令会输出 Unable to retrieve cluster configurations 并提示 This is expected when Cluster Mesh is disabledCluster Mesh 未启用时这是正常现象而非故障。clusters...参数当传入集群名时命令会先输出 Troubleshooting filtered subset of clusters: ...仅检查指定集群未传入时遍历全部发现配置并输出 Found N cluster configurations。随后集群按名称排序以保证输出顺序稳定slices.Sort(clusters)。--without-service-resolution控制拨号器的构造。默认情况下命令通过 k8s client 构造支持 Service 名到 ClusterIP 解析的拨号器newTroubleshootDialer这与 Cilium 在无 CoreDNS 环境下解析etcdService 的能力一脉相承置为 true 后改用纯系统 DNS 的DefaultEtcdDbgDialer。当 k8s Service 解析本身异常导致误判时此开关可用于隔离变量。--timeout每个集群的检查都会套用context.WithTimeout(ctx, timeout)超时后该集群输出失败结果并继续下一个集群不会中断整条命令。核心执行流程逐集群四段式检查命令主逻辑位于 TroubleshootClusterMesh其执行流程如下枚举配置调用common.ConfigFiles(cfgdir)扫描配置目录得到集群名 - 配置文件路径映射读取失败则直接结束Cluster Mesh 未启用时的预期行为。确定目标集群集无位置参数时取全部集群名并排序有参数时仅取指定的子集。逐个集群处理对每个集群依次执行——若与本地集群同名输出 This entry corresponds to the local cluster 提示仅当未禁用本地名查询且能从 API 取到时用 types.ValidateClusterName 校验集群名合法性如 DNS 命名规范非法则标❌ Invalid cluster name并跳过在配置映射中查找该集群缺失则标❌ Configuration not found调用common.ParseCiliumConfig解析配置中的 Cilium 扩展字段cilium-host-aliases解析失败则标❌ Could not parse Cilium config若存在HostAliases主机别名则用newStaticEtcdDbgDialerWithFallback构造静态解析优先、原拨号器兜底的复合拨号器对应 config.go 中cilium-host-aliases字段hostnameips列表使配置中静态指定的 IP 优先于 DNS 查询最后调用 kvstore.EtcdDbg 对该集群执行完整检查。EtcdDbg 的检查内容与输出含义EtcdDbg是整条排障链路的诊断核心依次输出以下信息源码见 etcd_debug.go Configuration path正在检查的配置文件路径若无法解析 etcd 配置则输出❌ Cannot parse etcd configuration。 Endpoints遍历配置中的每个 endpoint逐个执行etcdDbgEndpointHostname resolution对 endpoint 主机名做 DNS 解析失败输出❌ Cannot resolve hostname成功输出解析到的 IP 列表最多展示前 4 个多余用...省略TCP connection建立 TCP 连接失败输出❌ Cannot establish TCP connection成功输出远端地址若 scheme 不是https则到此为止TLS connectionhttps场景下继续 TLS 握手。实现通过InsecureSkipVerify 自定义VerifyPeerCertificate模拟完整校验并收集服务端证书链随后输出协商的 TLS 版本、加密套件以及服务端证书详情序列号、Subject、SAN、Subject/Authority Key ID、有效期。若客户端证书不满足服务端 CA 要求还会列出服务端可接受的 CA DNGET /version 探测TLS 1.3 下服务端不会主动通知双向认证结果因此命令主动发送GET /version请求并读取应答若读错误类型为remote error则判定为❌ TLS client authentication failed典型的证书/CA 不匹配症状成功则提取并输出 etcd server 版本。 Digital certificatesetcdDbgCerts输出配置引用的 Root CA 证书链、TLS 客户端证书链含是否可用配置的 Root CA 验证通过并提示 Username/Password 是否已设置只显示密码已设置/未设置而不泄露内容。⚙️ Etcd client真正以 etcd client 身份发起连接并尝试读取 heartbeat key 作为基础鉴权检查。连接状态为TransientFailure时输出❌ Failed to establish connection否则按❌ Failed to retrieve key from etcd区分成功则输出✅ Etcd connection successfully established并显示 etcd 集群 ID。通过这四段输出命令可以在一次执行内精确定位故障属于DNS 解析失败 / TCP 不通 / TLS 证书不受信 / 双向认证失败 / 鉴权被拒中的哪一层。配置目录与配置示例默认配置目录为/var/lib/cilium/clustermesh/其中每个 etcd 配置文件的文件名即集群名。配置是标准 etcd client YAML可携带 Cilium 扩展字段cilium-host-aliases。参考解析逻辑 ParseCiliumConfig一个典型配置示例# /var/lib/cilium/clustermesh/remote-cluster-name endpoints: - https://clustermesh-apiserver.cilium.svc.cluster.local:2379 trusted-ca-file: /var/lib/cilium/clustermesh/remote-cluster-name.ca.pem cert-file: /var/lib/cilium/clustermesh/remote-cluster-name.client.pem key-file: /var/lib/cilium/clustermesh/remote-cluster-name.client.key cilium-host-aliases: - hostname: clustermesh-apiserver.cilium.svc.cluster.local ips: - 10.96.0.10cilium-host-aliases的校验规则源码 config.gohostname 不能为空、每个条目至少一个 IP、hostname 不能重复违反任一规则都会导致配置解析失败并在排障输出中体现为❌ Could not parse Cilium config。典型使用场景与输出示例场景一全量检查所有远端集群cilium-operator-azure troubleshoot clustermesh预期输出骨架节选Found 3 cluster configurations Cluster cluster-a: Configuration path: /var/lib/cilium/clustermesh/cluster-a Endpoints: - https://10.0.0.5:2379 ✅ Hostname resolved to: 10.0.0.5 ✅ TCP connection successfully established to 10.0.0.5:2379 ✅ TLS connection successfully established to 10.0.0.5:2379 ℹ️ Negotiated TLS version: TLS 1.3, ciphersuite TLS_AES_128_GCM_SHA256 ℹ️ Etcd server version: 3.5.9 ... ✅ Etcd connection successfully established ℹ️ Etcd cluster ID: 1a2b3c4d场景二只检查指定集群cilium-operator-azure troubleshoot clustermesh cluster-b输出首行出现Troubleshooting filtered subset of clusters: cluster-b仅对该集群执行完整诊断。场景三排除 k8s Service 解析干扰当怀疑 k8s Service 到 ClusterIP 的解析路径--without-service-resolution对应的拨号器本身有误、导致 TCP 层无法连通时可关闭该能力做对照实验cilium-operator-azure troubleshoot clustermesh cluster-c --without-service-resolution场景四调整超时对高延迟控制面可将单集群检查超时从默认 5s 放大cilium-operator-azure troubleshoot clustermesh --timeout 15s常见故障模式与解读指引结合 EtcdDbg 的输出结构可将常见故障按下表快速定位输出特征故障层排查方向❌ Cannot resolve hostnameDNS检查集群网络 DNS 策略、CoreDNS、Service 与 Endpoints 状态❌ Cannot establish TCP connection网络层检查防火墙/安全组Azure NSG、CNI 网络策略、clustermesh-apiserver 的 Service/LoadBalancer 可达性❌ Cannot establish TLS connection 证书链信息TLS/证书检查trusted-ca-file是否与远端 CA 一致、证书是否过期输出含 Validity 区间❌ TLS client authentication failed双向认证检查cert-file/key-file是否由远端可接受的 CA 签发输出会列出远端可接受的 CA DN 便于比对❌ Failed to establish connection/Failed to retrieve keyetcd 会话/鉴权检查 etcd 用户密码Username/Password 字段及 heartbeat key 权限此外有两个伪故障需要区分目录读取失败并提示This is expected when Cluster Mesh is disabled说明 Cluster Mesh 未启用属预期行为输出中本地集群条目会出现ℹ️ This entry corresponds to the local cluster提示operator 场景因DisableLocalNameLookuptrue可能缺省不要将本地集群误判为异常。关联命令与进一步阅读命令组入口与兄弟命令cilium-operator-azure troubleshoot 与 cilium-operator-azure troubleshoot kvstore命令在 agent 侧的同源实现cilium-dbg troubleshoot clustermesh同一troubleshoot_clustermesh.go源码差异仅在本地集群名查询是否启用诊断核心实现pkg/kvstore/etcd_debug.goEtcdDbg 主流程、pkg/clustermesh/common/config.go配置目录扫描operator 命令组装与DisableLocalNameLookup设置operator/cmd/root.goClusterMesh 相关排障的 kvstoremesh 变体kvstoremesh-dbg troubleshoot可参考 clustermesh-apiserver/clustermesh-dbg/troubleshoot.go其目标为本机 etcd kvstore使用的同样是对kvstore.EtcdDbg的封装。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 