Cilium Connectivity Check 全解析：从 YAML 部署到 CUE 模板化生成机制

Cilium Connectivity Check 全解析：从 YAML 部署到 CUE 模板化生成机制

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium

Cilium 仓库中的examples/kubernetes/connectivity-check提供了一套基于 Kubernetes Deployment 的连通性自检套件：它通过 liveness/readiness 探针执行真实的网络请求，任何未就绪（unready）的 Pod 都直接对应一个具体的连通性问题。本文将完整介绍这套检查的部署方法、七类 YAML 变体的差异、各检查项背后的网络路径与 CiliumNetworkPolicy 语义，并深入解读其基于 CUE 的模板化生成体系，帮助你在集群中快速定位 Cilium 数据面、策略引擎与服务负载均衡的实际工作状态。

快速开始：在 Kubernetes 集群中部署 Connectivity Check

官方安装文档 kubectl-connectivity-test.rst 给出了标准的部署流程。建议为检查创建独立命名空间，避免与业务资源混淆：

kubectl create ns cilium-test

应用标准检查清单（包含外部流量检查）：

kubectl apply -n cilium-test -f examples/kubernetes/connectivity-check/connectivity-check.yaml

随后观察 Pod 状态。所有 Pod 均应达到Running且READY列为1/1：

$ kubectl get pods -n cilium-test NAME READY STATUS RESTARTS AGE echo-a-76c5d9bd76-q8d99 1/1 Running 0 66s echo-b-795c4b4f76-9wrrx 1/1 Running 0 66s echo-b-host-6b7fc94b7c-xtsff 1/1 Running 0 66s host-to-b-multi-node-clusterip-85476cd779-bpg4b 1/1 Running 0 66s host-to-b-multi-node-headless-dc6c44cb5-8jdz8 1/1 Running 0 65s pod-to-a-79546bc469-rl2qq 1/1 Running 0 66s pod-to-a-allowed-cnp-58b7f7fb8f-lkq7p 1/1 Running 0 66s pod-to-a-denied-cnp-6967cb6f7f-7h9fn 1/1 Running 0 66s pod-to-b-intra-node-nodeport-9b487cf89-6ptrt 1/1 Running 0 65s pod-to-b-multi-node-clusterip-7db5dfdcf7-jkjpw 1/1 Running 0 66s pod-to-b-multi-node-headless-7d44b85d69-mtscc 1/1 Running 0 66s pod-to-b-multi-node-nodeport-7ffc76db7c-rrw82 1/1 Running 0 65s pod-to-external-1111-d56f47579-d79dz 1/1 Running 0 66s pod-to-external-fqdn-allow-google-cnp-78986f4bcf-btjn7 1/1 Running 0 66s

需要注意：若部署在单节点集群，multi-node相关的 Pod 会停留在Pending状态。这是符合预期的行为——这些 Pod 通过反亲和性（anti-affinity）被强制调度到与目标 echo 服务器不同的节点上，至少需要两个节点才能完成调度。测试结束后删除命名空间即可：

kubectl delete ns cilium-test

检查清单总览：多套 YAML 变体

目录 examples/kubernetes/connectivity-check 下按场景提供了多套 YAML，均由 CUE 脚本自动生成（文件头标注 "Automatically generated by Makefile. DO NOT EDIT"）：

工作原理：以就绪/存活探针承载连通性测试

这套检查的设计思想非常巧妙：没有独立的测试 runner，每个检查 Pod 自身就是测试本身。每个 Deployment 的容器都配置了readinessProbe与livenessProbe，探针命令就是真实的curl网络请求：

• 探针执行成功→ 容器就绪 → PodReady；
• 探针执行失败（curl 返回非零、超时）→ 容器不就绪 → 通过kubectl get pods即可一眼看到问题 Pod 及其对应的连通性场景。

以pod-to-a为例（见 connectivity-check.yaml），探针配置为：

readinessProbe: timeoutSeconds: 7 exec: command: - curl - -sS - --fail - --connect-timeout - "5" - -o - /dev/null - echo-a:8080/public

这一探针配置正是由 resources.cue 中的模板统一生成的。CUE 定义中_probeFailureTimeout: 5（单位秒），探针timeoutSeconds被固定为_probeFailureTimeout + 2，即 7 秒；允许类探针默认生成命令curl -sS --fail --connect-timeout 5 -o /dev/null <probeTarget><probePath>，其中_probePath默认为/public。

对于预期被拒绝的检查（如pod-to-a-denied-cnp），探针则反转逻辑——使用 shell 取反，要求 curl 失败才算就绪：

- ash - -c - '! curl -s --fail --connect-timeout 5 -o /dev/null echo-a:8080/private'

这正是 resources.cue 中_rejectProbe的默认形态：! curl ... <probeTarget>/private。它验证的是"在相应策略约束下，对/private路径的访问必须被拒绝"，若访问意外成功（策略失效），Pod 将永远不就绪。

检查 Pod 使用的容器镜像在 defaults.cue 中统一定义：

• 检查发起方（名字匹配pod-to-*/host-to-*）：quay.io/cilium/alpine-curl:v1.5.0，启动命令为/bin/ash -c sleep 1000000000（长驻等待探针执行）；
• echo 服务器：quay.io/cilium/json-mock:v1.4.1（见 echo-servers.cue），监听PORT环境变量指定的端口。

检查类型矩阵：网络、策略、服务、NodePort/HostPort 与代理

每一个检查 Deployment 的 labels 都带有component、topology、traffic、type、quarantine五类元数据（由 resources.cue 模板统一打标），这也是后续 CUE 过滤系统的核心依据。下面按component分类解读标准清单中的检查项。

echo 服务器拓扑

echo-servers.cue 定义了全部 echo 服务器及其暴露方式：

echo-c关联的 ingress 策略定义在 echo-servers.cue：仅允许GET /public$的 HTTP 请求访问 8080 端口，这是 Layer 7 代理检查的基础。

网络连通性检查（network-check）

定义于 network.cue，component: network-check，覆盖最基础的 Pod 间连通与出外网能力：

• pod-to-a：Pod → Pod 直连，目标echo-a:8080/public，验证 Pod 间二层/三层连通与 DNS 解析；
• pod-to-external-1111：traffic: external，目标https://1.1.1.1，验证Pod 访问公网的能力（需要 Cilium 正确配置 masquerading 与 egress 路径）。

策略检查（policy-check）：允许、拒绝与 FQDN

定义于 policy.cue，component: policy-check，全部使用 CiliumNetworkPolicy（CRDcilium.io/v2），覆盖 Cilium 策略引擎的三个核心场景：

1. 拒绝场景pod-to-a-denied-cnp：Deployment 设置_probeExpectFail: true，其 CiliumNetworkPolicy 只放行 DNS（kube-dns / node-local-dns / OpenShift DNS），没有到echo-a的规则。因此探针访问/private必然失败，Pod 通过"失败即就绪"的反向探针确认默认拒绝（default deny）生效。

2. 允许场景pod-to-a-allowed-cnp：其 CiliumNetworkPolicy 显式放行TCP 8080 → echo-a，并附带 DNS 放行。Pod 应正常就绪，验证策略允许路径可用。

3. FQDN 场景pod-to-external-fqdn-allow-google-cnp：traffic: external，目标www.google.com，其 CiliumNetworkPolicy 使用toFQDNs: [{matchPattern: "*.google.com"}]放行域名，同时自动附带 DNS 规则（rules: dns: [{matchPattern: "*"}]）。验证 Cilium FQDN 策略的 DNS 感知能力。

这里有一个值得注意的实现细节（resources.cue）：只要策略规则包含toFQDNs，模板就会自动把_enableDNSVisibility置为true，在 DNS 放行规则上附加matchPattern: "*"的 DNS 规则，从而让 Cilium 能追踪 DNS 应答并据此解析 FQDN 对应的 IP——这正是 FQDN 策略工作的前提。

服务检查（services-check）：ClusterIP、Headless 与宿主机网络

定义于 services.cue，component: services-check，覆盖 Kubernetes 服务负载均衡的各种形态：

• pod-to-b-multi-node-clusterip：跨节点访问 ClusterIP 服务echo-b:8080；
• pod-to-b-multi-node-headless：跨节点访问 Headless 服务echo-b-headless:8080（直连 Pod IP）；
• host-to-b-multi-node-clusterip/host-to-b-multi-node-headless：宿主机网络（hostNetwork: true）下的 Pod 访问服务，且设置dnsPolicy: ClusterFirstWithHostNet，验证宿主机网络命名空间内 DNS 与服务的可用性。

这些检查通过 Pod 反亲和性（anti-affinity）保证与echo-b分处不同节点，从而真正覆盖跨节点的数据面路径。

NodePort 与 HostPort 检查

• NodePort（component: nodeport-check）：pod-to-b-multi-node-nodeport与pod-to-b-intra-node-nodeport访问echo-b-host-headless:31414，覆盖 NodePort 服务在跨节点/同节点两种拓扑下的负载均衡；
• HostPort（component: hostport-check，仅存在于 hostport 变体清单中）：通过echo-b-host/echo-c-host的hostNetwork方式暴露 HostPort，验证 eBPF HostPort 或 portmap 链式插件的正确性。

基于 L7 策略的代理检查（proxy-check）

定义于 proxy.cue，component: proxy-check，专测 Cilium 的 Layer 7（HTTP）代理路径，三种组合：

L7 规则统一由 proxy.cue 中的_egressL7Policy生成，限定 HTTP 方法GET、路径/public$。这类检查的 Deployment 设置_enableMultipleContainers: true，即一个 Pod 内同时运行"允许"与"拒绝"两个容器（resources.cue），一个探针访问/public期望成功，另一个探针访问/private期望失败，一条 Pod 同时覆盖 L7 策略的正反两个方向。

拓扑调度：intra-node 与 multi-node 的亲和性设计

topology标签（any/intra-node/multi-node）不是摆设，它直接影响调度策略。查看 defaults.cue 的命名约定：

• 名字含*-intra-node-*→ 设置_affinity（Pod 亲和性）：与目标 echo 服务器同节点，验证同一节点内的数据面路径（此时 Cilium 走本地路由/本地 BPF 路径）；
• 名字含*-multi-node-*→ 设置_antiAffinity（Pod 反亲和性）：与目标 echo 服务器异节点，强制跨节点调度，验证 overlay 或原生路由下的跨节点转发。

对应的亲和性字段由 resources.cue 模板渲染，topologyKey固定为kubernetes.io/hostname。这也解释了为何单节点集群中 multi-node Pod 必然Pending——没有任何节点能满足"与 echo-b 不同主机"的反亲和约束。

开发者文档：CUE 模板化生成机制

所有 YAML 并非手写，而是用 CUE（配置语言）以声明式模板定义的。检查定义按职责拆分为多个.cue文件：

其中 main_tool.cue 定义了完整的过滤流水线：filterComponent → filterType → filterQuarantine → filterTopology → filterKind → filterName → filterTraffic，六个过滤器逐级收窄资源集合，最终由dump命令以 YAML 流格式导出（见 dump_tool.cue）。

Makefile 工作流：生成、部署与检查

在 examples/kubernetes/connectivity-check/Makefile 中，SRC := $(wildcard *.cue)，每个 YAML 输出目标都对应一条带特定-t标签参数的cue dump命令：

$(DEFAULT_OUT): $(SRC) # connectivity-check.yaml $(CUE) dump $(INTERNAL_TRAFFIC_OUT): $(SRC) # connectivity-check-internal.yaml $(CUE) -t traffic=internal dump $(HOSTPORT_OUT): $(SRC) # connectivity-check-hostport.yaml $(CUE) -t component=all dump $(SINGLE_OUT): $(SRC) # connectivity-check-single-node.yaml $(CUE) -t topology=single-node dump $(PROXY_OUT): $(SRC) $(SERVERS_OUT) # connectivity-check-proxy.yaml $(CUE) -t component=proxy dump $(QUARANTINE_OUT): $(SRC) $(SERVERS_OUT) $(CUE) -t component=all -t quarantine=true dump $(TOOLS_OUT): $(SRC) $(SERVERS_OUT) $(CUE) -t component=all -t type=tool dump

CUE 工具链通过 Docker 容器docker.io/cuelang/cue:v0.2.2（带 SHA 固定）运行，保证构建环境可复现。目录内可直接运行make help查看全部命令，常用目标包括：

• make all：生成全部 YAML；
• make deploy：kubectl apply -f connectivity-check-hostport.yaml，将含 HostPort 检查的完整清单部署到当前 kubeconfig 指向的集群；
• make eval：cue eval -c ./...校验 CUE 定义一致性；
• make generate_all：为每个 Deployment 单独导出独立 YAML 文件，便于逐个审查；
• make inspect：将最新 CUE 导出结果与集群中已部署资源做kubectl diff，检查配置漂移；
• make list/make fmt：列出资源 / 格式化 CUE 源码。

make help输出的命令行帮助（定义于 main_tool.cue）如下，全部过滤器参数均可在ls/dump时使用：

Usage: cue [-t component=<component>] [-t kind=<kind>] [-t name=<name>] [-t quarantine=true] [-t topology=<topology>] [-t traffic=any] [-t type=<tooltype>] <command> Available Commands: dump Generate connectivity-check YAMLs from the cuelang scripts ls List connectivity-check resources specified in this directory Available filters: component { all | default | network | policy | services | hostport | proxy } (default excludes hostport, proxy) kind { Deployment | Service | CiliumNetworkPolicy } (default: all) quarantine { true | false } (default: false) topology { any | single-node } (default: any) traffic { any | internal | external } (default: any) type { autocheck | tool } (default: autocheck) Example command: $ cue -t component=all ls

注意component=default的语义：会排除hostport-check与proxy-check两类（见 main_tool.cue），这与标准清单默认不含 HostPort/L7 代理检查的定位一致。例如，仅列出标准清单中的策略检查项：

$ cue -t component=policy -t kind=CiliumNetworkPolicy ls

排查与调试指南

当kubectl get pods -n cilium-test中出现0/1或CrashLoopBackOff时，按以下思路定位：

1. 对照 Pod 名字定位场景：Pod 名即检查场景名（如pod-to-a-denied-cnp对应"策略拒绝"检查、pod-to-external-1111对应"外部流量"检查）。结合本文件上述检查矩阵即可知道是哪条网络路径出了问题；
2. 查看探针详情：kubectl describe pod <pod> -n cilium-test查看Readiness/Liveness事件与探针失败原因（Probe exec ... returned exit code）；探针失败本质是 curl 失败，可用kubectl exec进入同命名空间其他 Pod 手动执行同样的 curl 命令复现；
3. 区分预期行为：单节点集群中multi-nodePodPending属正常；pod-to-a-denied-cnp这类反探针 Pod 若长时间Ready，反而说明"拒绝"预期落空，应检查 CiliumNetworkPolicy 是否正确应用（kubectl get cnp -n cilium-test）；
4. 检查策略导入状态：用kubectl describe cnp <name> -n cilium-test确认策略处于 enforced 状态；
5. 使用调试工具清单：部署 connectivity-debug-tools.yaml（通过make的-t type=tool目标生成）可获得探针恒通过的辅助 Pod，便于人工跟进日志。例如 tools.cue 中的query-dns-policy会循环执行dig www.google.com并输出 DNS 解析结果，可配合 FQDN 策略排障：

kubectl logs -l name=query-dns-policy --timestamps -f

总结

examples/kubernetes/connectivity-check是一个把"测试即 Deployment、探针即断言"思想贯彻到底的连通性验证套件：标准清单（connectivity-check.yaml）一条命令即可覆盖 Pod 直连、外部流量、L3/L4 策略、FQDN、ClusterIP/Headless/NodePort 服务、跨节点拓扑等核心数据面路径；HostPort、L7 代理、纯 NetPol、单节点等场景则通过 Makefile 的标签化 CUE 模板按需生成。其 CUE 模板体系（resources.cue 与 defaults.cue）同时是理解 Cilium 网络策略与调度语义的一份高质量可读参考。结合官方安装文档 kubectl-connectivity-test.rst 与 e2e 测试体系（Documentation/contributing/testing/e2e.rst），你可以将这套检查无缝接入自己的 CI/CD 流水线，持续守护集群网络健康。

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium