使用 cilium-dbg envoy admin certs 查看 Cilium 中 Envoy Proxy 的 TLS 证书配置【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本文围绕 Cilium 提供的诊断命令cilium-dbg envoy admin certs讲解如何通过本地 CLI 直接查询 Envoy Proxy 中已配置的 TLS 证书信息。该命令是 Cilium 数据面排障中检查 L7 策略、TLS 代理与双向 TLSmTLS配置是否生效的关键入口读完本文后你将掌握该命令的完整用法、输出含义、底层实现原理Unix Socket 直连 Envoy Admin API以及与之配套的证书下发链路k8s Secret / SDS / CiliumEnvoyConfig与兄弟诊断命令。命令概览一条命令列出 Envoy 已配置的 TLS 证书cilium-dbg envoy admin certs是cilium-dbg命令树中“Envoy 管理”子命令族的一员其功能定位在官方命令参考中只有一句话List configured TLS certificates of Envoy Proxy即列出 Envoy Proxy 当前已配置的 TLS 证书。cilium-dbg envoy admin certs [flags]该命令本身只有一个-h, --help选项没有业务参数。命令树结构为cilium-dbg # CLI for interacting with the local Cilium Agent └── envoy # Manage Envoy Proxy └── admin # Access Envoy Admin Interface ├── certs # List configured TLS certificates of Envoy Proxy ← 本文主角 ├── clusters # List configured clusters of Envoy Proxy ├── config # View config dump of Envoy Proxy ├── listeners # List configured listeners of Envoy Proxy ├── logging # List and change logging levels of Envoy Proxy ├── metrics # List Prometheus statistics of Envoy Proxy └── serverinfo # View server info of Envoy Proxy在 cilium-dbg 命令参考 中cilium-dbg被定位为 “CLI for interacting with the local Cilium Agent”因此envoy admin certs适用于在运行 Cilium Agent 的节点上就地排查 Envoy 代理状态。常用参数与输出格式继承自父命令的通用参数虽然certs子命令本身只有-h但它会继承cilium-dbg根命令的以下全局选项参数说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug输出调试信息-H, --host stringAgent 服务端 API 的 URI用于连接远程/非默认端点--log-driver strings日志输出端点示例syslog--log-opt map日志驱动选项示例formatjson输出内容命令输出直接取自 Envoy Admin API 的/certs端点返回的是 Envoy 的 certificates 列表每个证书条目包含ca_certCA 证书链含path或inline_bytes/inline_string中的内容、cert_chain指纹sha256等元数据cert_chain实际下发的叶子证书含 SAN 信息、过期时间valid_from/expiration_time证书名称name与所属的 Secret 名称通过secret_name字段与 k8s Secret/SDS 关联。具体字段以当前 Envoy 版本 Admin API 的 JSON 结构为准命令本身不做二次解析原样输出 Admin API 返回内容。底层实现Unix Socket 直连 Envoy Admin API从源码结构看该命令的实现非常精简。在 envoy_admin_certs.go 中var EnvoyAdminCertsCmd cobra.Command{ Use: certs, Short: List configured TLS certificates of Envoy Proxy, Run: func(cmd *cobra.Command, args []string) { envoyAdminClient : newEnvoyAdminClient() certs, err : envoyAdminClient.GetCerts() if err ! nil { Fatalf(cannot get certificates: %s\n, err) } cmd.Println(certs) }, }核心逻辑是newEnvoyAdminClient()创建客户端后调用GetCerts()而 envoy_adminclient.go 揭示了它的通信方式const envoySocketDirPath /var/run/cilium/envoy/sockets/ func newEnvoyAdminClient() *envoyAdminClient { return envoyAdminClient{ // Needs to be provided to envoy (received as :authority) - even though we Dial to a Unix domain socket. adminURL: fmt.Sprintf(http://%s/, envoy-admin), unixPath: filepath.Join(envoySocketDirPath, admin.sock), } }要点如下不走网络走 Unix Domain Socket客户端通过自定义 DialContext 直接拨号/var/run/cilium/envoy/sockets/admin.sockadminURL中的envoy-admin仅作为 HTTP 的:authority头提供给 Envoy实际连接不经过 TCP/IP因此只能在本机执行与“local Cilium Agent”的定位一致HTTP GET/certsGetCerts()实际请求路径为certs见 envoy_adminclient.goget()内部对响应体设置了100 * safeio.MB的读取上限见 envoy_adminclient.go防止异常大响应拖垮 CLI失败即退出任何请求错误都会以cannot get certificates: ...形式打印并退出便于脚本捕获失败状态。这也意味着运行该命令的进程必须与 Cilium Agent 在同一节点、且具备对/var/run/cilium/envoy/sockets/的访问权限才能读到 socket 文件。证书从哪来Cilium 的 Envoy TLS 证书链路要真正读懂certs的输出需要理解 Cilium 是如何把 TLS 证书交给 Envoy 的。从源码看证书配置主要沿两条链路进入 Envoy1. 策略驱动的 TLS ContextCiliumNetworkPolicy / CiliumClusterwideNetworkPolicyL7 策略中定义 TLS 规则如rules: tls、originating-tls时Cilium 会把策略中的TLSContext转换为 Envoy 的 TLS 配置。在 pkg/envoy/model.go 中toEnvoyOriginatingTLSContext负责将“策略 TLS 上下文”转成 Envoy 可消费的结构其中支持从k8s Secret 同步policySecretsNamespace指定命名空间支持SDSSecret Discovery Service动态下发当useSDS为真时证书通过 SDS 而非静态内联下发这正是certs端点里能看到动态 secret 的机制useFullTLSContext开关由EnvoyProxyConfig.UseFullTLSContext控制见 pkg/envoy/cell.go 与 pkg/envoy/config/config.go用于兼容旧行为旧逻辑可能把 Secret 中的ca.crt一并纳入 TLS 上下文。2. CiliumEnvoyConfig 自定义资源更通用的做法是通过CiliumEnvoyConfig/CiliumClusterwideEnvoyConfigCRD 声明完整的 Envoy 监听器、过滤器链与 TLS 配置。这一类配置同样经由 pkg/envoy 与 pkg/ciliumenvoyconfig 落盘到 Envoy并可在config dump与certs中观测到。因此cilium-dbg envoy admin certs查到的证书本质上就是k8s Secret →SDS/静态→ Envoy TLS Context这条链路的“最终落地状态”非常适合用来验证策略引用的 Secret 是否成功同步Secret 名、证书链 SAN 是否正确证书是否过期输出中的expiration_time字段CA 链与叶子证书的 sha256 指纹是否符合预期。配套诊断命令完整观察 Envoy 运行态证书只是 Envoy 状态的一个切面。围绕同一 Admin Interfacecilium-dbg envoy admin还提供一组配套子命令可用于组合排障子命令功能对应 Admin API 路径cilium-dbg envoy admin certs列出 TLS 证书certscilium-dbg envoy admin clusters列出集群支持-o输出格式见 envoy_admin_clusters.goclusters?format...cilium-dbg envoy admin config查看配置 dump可按资源类型过滤config_dump?include_eds[resource...][name_regex...]cilium-dbg envoy admin listeners列出监听器支持-o输出格式listeners?format...cilium-dbg envoy admin logging查看/调整日志级别含logging list/set子命令loggingcilium-dbg envoy admin metrics输出 Prometheus 格式统计支持--filter正则stats/prometheuscilium-dbg envoy admin serverinfo查看 Envoy 版本等服务器信息server_info其中config子命令比较有特色它支持按资源类型过滤 dump在 envoy_admin_config.go 中定义了资源类型映射all | clusters | endpoints | listeners | networkpolicies | routes | secrets并可通过-n, --name传入正则过滤资源名见 envoy_admin_config.go。排障时可以这样组合使用# 1. 查看当前下发的全部动态 secret含证书 cilium-dbg envoy admin config secrets # 2. 查看特定名字的证书细节 cilium-dbg envoy admin config secrets -n my-tls-secret # 3. 直接列出证书摘要 cilium-dbg envoy admin certs实操示例完整的排查流程假设要确认某条 L7 策略引用的 Secretdefault/nginx-tls是否正确下发到 Envoy# 步骤 1列出所有已配置证书观察是否存在 nginx-tls 对应条目 cilium-dbg envoy admin certs # 步骤 2按 secret 名过滤 config dump查看 TLS 上下文细节 cilium-dbg envoy admin config secrets -n nginx-tls # 步骤 3确认 listener 是否实际挂载了该证书链 cilium-dbg envoy admin listeners # 步骤 4检查连接级指标可选确认 TLS 握手是否成功 cilium-dbg envoy admin metrics --filter .*ssl.*handshake.*常见结论判读certs输出中找不到策略引用的 Secret → 证书未同步优先检查 Secret 是否存在、命名空间是否与策略policySecretsNamespace匹配certs输出中证书的expiration_time已过 → 证书过期更新 Secret 后 Cilium 会通过 SDS 重新下发certs中指纹与 Secret 中tls.crt不一致 → 中间可能存在证书轮换延迟或同步失败结合 Agent 日志进一步排查。适用前提与限制本机执行命令依赖节点上的 Unix Socket/var/run/cilium/envoy/sockets/admin.sock只能在运行 Cilium Agent 且启用了 EnvoyL7 策略/TLS 代理场景的节点上生效若 Agent 未启用 Envoysocket 不存在命令会直接报错退出权限要求执行用户需要对上述 socket 目录具有访问权限只读操作certs仅为查询命令不会修改 Envoy 状态如需调整日志级别才需要logging set一类写操作输出为 Envoy 原始 JSON字段结构随 Envoy 版本演进脚本化解析时应以实际输出为准。小结cilium-dbg envoy admin certs虽是一个无参数的“小命令”却是连通k8s Secret/SDS → Cilium TLS 上下文 → Envoy 运行时证书状态这条链路的关键观测点。结合其 Unix Socket 直连 Admin API 的实现cilium-dbg/cmd/envoy_adminclient.go与同族的config、listeners、metrics等命令即可完成从证书下发到 TLS 握手指标的完整闭环排查。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考