cilium-operator-aws troubleshoot 命令详解Cilium Operator 控制面连通性排查实战指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本文围绕 Cilium 仓库中cilium-operator-aws二进制提供的troubleshoot命令族展开介绍如何用它诊断 Operator 控制面与外部依赖etcd kvstore、远端集群 ClusterMesh 配置之间的连通性。读者将掌握该命令的完整子命令结构、全部参数含义、底层诊断流程以及如何在 AWS 环境下的 Cilium Operator 中实际执行连通性检查。命令定位Operator 控制面的体检工具troubleshoot是cilium-operator-aws的子命令其定位是Run troubleshooting utilities to check control-plane connectivity即运行排查工具来检查控制面连通性。所谓控制面连通性指的是 Cilium Operator 进程与运行其数据所需的分布式依赖之间的网络可达性主要包括两类etcd kvstore当 Cilium 不以 CRD 模式运行时Operator 依赖 etcd 存储集群状态身份分配、服务同步等远端集群的 ClusterMesh 配置当启用 ClusterMesh多集群互联时Operator 需要连接各远端集群的 clustermesh-apiserver。从源码结构看cilium-operator-aws的主命令在 operator/cmd/root.go 中通过cmd.AddCommand(...)挂载了troubleshoot.Cmd该命令本体定义于 cilium-dbg/cmd/troubleshoot/troubleshoot.go并且设置了troubleshoot.DisableLocalNameLookup true——这表示在 Operator 场景下不会通过本地 Cilium Agent API 查询本地集群名Operator 中没有 Agent 的 API 服务该细节将在 clustermesh 子命令一节展开说明。命令层级总览cilium-operator-aws troubleshoot的命令树如下cilium-operator-aws troubleshoot ├── cilium-operator-aws troubleshoot clustermesh [clusters...] └── cilium-operator-aws troubleshoot kvstore完整命令参考见仓库自动生成的文档cilium-operator-aws.md父命令含全部启动参数cilium-operator-aws_troubleshoot_clustermesh.mdcilium-operator-aws_troubleshoot_kvstore.md父命令 troubleshootcilium-operator-aws troubleshoot [flags]父命令本身仅是一个命令分组不执行具体的诊断动作只提供-h, --help帮助选项。其核心价值在于承载两个具备完整诊断逻辑的子命令。从命令注册代码cilium-dbg/cmd/troubleshoot/troubleshoot.go可以确认父命令与子命令位于同一包中两个子命令通过各自的init()函数完成注册。troubleshoot clustermesh远端集群连通性排查cilium-operator-aws troubleshoot clustermesh [clusters...] [flags]该子命令用于Troubleshoot connectivity towards remote clusters排查与远端集群的连通性。[clusters...]为可选的位置参数当不指定任何集群名时工具会遍历 ClusterMesh 配置目录下发现的所有集群当指定一个或多个集群名时只针对这些集群执行检查输出会注明Troubleshooting filtered subset of clusters。参数详解参数默认值说明--H string空URI to server-side API即要连接的 Cilium API 地址用于获取本地集群名等元数据--clustermesh-config string/var/lib/cilium/clustermesh/ClusterMesh 配置目录路径-h, --help-帮助信息--timeout duration5s检查单个集群连通性时的超时时间--without-service-resolutionfalse禁用通过 k8s client 将 Kubernetes Service 解析为 IP 的能力底层诊断流程源码 troubleshoot_clustermesh.go 中的TroubleshootClusterMesh函数按以下顺序执行发现集群配置调用common.ConfigFiles(cfgdir)读取配置目录输出Found N cluster configurations如果目录为空或不可读会提示This is expected when Cluster Mesh is disabled——这是判断是否根本没有启用 ClusterMesh的关键信息。确定检查目标未传集群参数时收集全部配置键否则输出过滤子集并将集群名排序保证输出顺序稳定。逐集群校验对每个集群依次执行——若集群名等于本地集群名输出This entry corresponds to the local cluster提示该信息来自getLocalClusterName在 Operator 中因DisableLocalNameLookuptrue会跳过并通过--H指向的 API 获取失败时输出警告并返回空串调用types.ValidateClusterName校验集群名合法性非法则报Invalid cluster name从配置映射中查找集群配置缺失则报Configuration not found调用common.ParseCiliumConfig解析远端集群的 Cilium 配置失败则报Could not parse Cilium config若配置中带HostAliases则构造staticEtcdDbgDialerWithFallback一个静态主机名解析器优先使用配置中的主机别名映射否则回退到默认 dialer这与 clustermesh-apiserver 连接使用的dial.NewStaticHostDialer机制一致最后以--timeout为上下文超时调用kvstore.EtcdDbg完成对远端集群 etcd 的完整诊断。troubleshoot kvstoreetcd kvstore 连通性排查cilium-operator-aws troubleshoot kvstore [flags]该子命令用于Troubleshoot connectivity towards the etcd kvstore排查与 etcd kvstore 的连通性是 kvstore 模式下 Operator 无法启动、身份分配失败等问题的第一排查手段。参数详解参数默认值说明--etcd-config string/var/lib/etcd-config/etcd.configetcd 配置文件路径-h, --help-帮助信息--timeout duration5s检查 kvstore 连通性时的超时时间--without-service-resolutionfalse禁用通过 k8s client 将 Kubernetes Service 解析为 IP 的能力底层诊断流程源码 troubleshoot_kvstore.go 首先检查--etcd-config指向的文件是否存在若文件不存在直接输出Unable to read etcd configuration: 路径并附上关键提示This is expected when Cilium is running in CRD mode。这是因为 Cilium 支持 CRD 模式默认将 Kubernetes CRD 作为后端存储与 kvstore 模式两种数据平面后端在 CRD 模式下不存在 etcd 配置文件该报错属正常现象并非故障。文件存在时构造一个newTroubleshootDialer可选择关闭 Service 解析以--timeout为超时调用kvstore.EtcdDbg执行完整诊断。诊断内核EtcdDbg 的四层检查clustermesh与kvstore两个子命令最终都汇聚到pkg/kvstore/etcd_debug.go中的EtcdDbg函数pkg/kvstore/etcd_debug.go。它按层递进执行以下检查输出带 emoji 标记的友好诊断信息配置解析通过clientyaml.NewConfig解析 etcd 配置文件失败则报Cannot parse etcd configuration随后列出所有Endpoints。端点级检查对每个 endpoint见etcdDbgEndpoint主机名解析对非 IP 字面量的主机名执行LookupIP失败报Cannot resolve hostname成功输出Hostname resolved to: IPsTCP 连接通过DialContext建立 TCP 连接失败报Cannot establish TCP connection对https端点继续执行 TLS 检查TLS 证书检查手工模拟InsecureSkipVerify下的证书校验通过VerifyPeerCertificate回调获取服务端实际下发的证书以区分证书过期、主机名不匹配等具体原因。证书文件检查验证 etcd 配置中引用的数字证书文件是否存在、可读。etcd gRPC 客户端握手与鉴权以实际 etcd client 建立 gRPC 连接通过grpc.WithContextDialer注入自定义 dialer读取心跳键HeartbeatPath作为基本鉴权探测。根据ActiveConnection().GetState()区分Failed to establish connection连接层失败与Failed to retrieve key from etcd连接成功但鉴权/读取失败成功时输出Etcd connection successfully established及 etcd 集群 ID。这一分层设计意味着一条诊断输出可以快速定位问题位于 DNS 层、TCP 层、TLS 层还是鉴权层无需人工逐层手动验证。实战场景与建议场景一kvstore 模式下 Operator 无法启动。在运行cilium-operator-aws的 Pod 中执行cilium-operator-aws troubleshoot kvstore --etcd-config /var/lib/etcd-config/etcd.config若输出Cannot establish TCP connection问题在网络层若输出Failed to establish connection而 TCP 检查通过问题在 gRPC/TLS 层若输出Failed to retrieve key from etcd通常是证书鉴权或权限配置问题。确认 etcd 配置内容可对照仓库中的 clustermesh-apiserver/etcd-config.yaml 与 clustermesh-apiserver/etcdinit 中生成的 etcd 配置格式。场景二ClusterMesh 多集群同步异常。执行cilium-operator-aws troubleshoot clustermesh --clustermesh-config /var/lib/cilium/clustermesh/按集群逐项输出诊断。如果输出Found 0 cluster configurations且提示 Cluster Mesh 未启用说明问题不在网络而在配置装载如果单个集群检查失败则结合--timeout调大超时以排除慢链路误报。--without-service-resolution可用于在 k8s Service 解析不可用如 kubeconfig 缺失时退化为纯 DNS 解析的连通性检查。场景三仅排查指定集群。传入集群名参数缩小范围cilium-operator-aws troubleshoot clustermesh cluster1 cluster2与其它 Operator 变体的关系同一套troubleshoot命令也被挂载到其它云厂商 Operator 变体上例如cilium-operator-alibabacloud、cilium-operator-azure与通用cilium-operator其命令文档分别位于 cilium-operator-alibabacloud_troubleshoot.md、cilium-operator-azure_troubleshoot.md、cilium-operator_troubleshoot.md以及 Agent 侧的 cilium-dbg_troubleshoot.md。这些变体的命令行为与参数保持一致仅随各自二进制的主命令参数如 AWS 的 ENI/IPAM 相关参数不同而有所区别掌握本文的命令即可在所有变体上通用排查。这些 cmdref 文档均由cilium-operator-aws cmdref自动生成因此与二进制实际行为严格一致可作为权威参考。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
