使用 cilium-dbg envoy admin certs 查看 Cilium 中 Envoy Proxy 的 TLS 证书配置

使用 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 代理与双向 TLS（mTLS）配置是否生效的关键入口；读完本文后，你将掌握该命令的完整用法、输出含义、底层实现原理（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根命令的以下全局选项：

输出内容

命令输出直接取自 Envoy Admin API 的/certs端点，返回的是 Envoy 的 certificates 列表，每个证书条目包含：

• ca_cert：CA 证书链，含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"), } }

要点如下：

1. 不走网络，走 Unix Domain Socket：客户端通过自定义 DialContext 直接拨号/var/run/cilium/envoy/sockets/admin.sock，adminURL中的envoy-admin仅作为 HTTP 的:authority头提供给 Envoy，实际连接不经过 TCP/IP，因此只能在本机执行（与“local Cilium Agent”的定位一致）；
2. HTTP GET/certs：GetCerts()实际请求路径为certs（见 envoy_adminclient.go），get()内部对响应体设置了100 * safeio.MB的读取上限（见 envoy_adminclient.go），防止异常大响应拖垮 CLI；
3. 失败即退出：任何请求错误都会以cannot get certificates: ...形式打印并退出，便于脚本捕获失败状态。

这也意味着：运行该命令的进程必须与 Cilium Agent 在同一节点、且具备对/var/run/cilium/envoy/sockets/的访问权限，才能读到 socket 文件。

证书从哪来：Cilium 的 Envoy TLS 证书链路

要真正读懂certs的输出，需要理解 Cilium 是如何把 TLS 证书交给 Envoy 的。从源码看，证书配置主要沿两条链路进入 Envoy：

1. 策略驱动的 TLS Context（CiliumNetworkPolicy / CiliumClusterwideNetworkPolicy）

L7 策略中定义 TLS 规则（如rules: tls、originating-tls）时，Cilium 会把策略中的TLSContext转换为 Envoy 的 TLS 配置。在 pkg/envoy/model.go 中，toEnvoyOriginatingTLSContext负责将“策略 TLS 上下文”转成 Envoy 可消费的结构，其中：

• 支持从k8s Secret 同步（policySecretsNamespace指定命名空间）；
• 支持SDS（Secret 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 Interface，cilium-dbg envoy admin还提供一组配套子命令，可用于组合排障：

其中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 且启用了 Envoy（L7 策略/TLS 代理场景）的节点上生效；若 Agent 未启用 Envoy，socket 不存在，命令会直接报错退出；
• 权限要求：执行用户需要对上述 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