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

Cilium Connectivity Check 全解析从 YAML 部署到 CUE 模板化生成机制【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/ciliumCilium 仓库中的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 EDITYAML 文件用途与适用前提connectivity-check.yaml标准连通性检查含外部流量https://1.1.1.1、www.google.com与完整策略、服务检查connectivity-check-internal.yaml与标准检查相同但不包含外部流量检查去掉 1.1.1.1、www.google.com 等目标。当前用于 GitHub Action 基于 kind IPv6 集群的 conformance 测试connectivity-check-hostport.yaml标准检查 HostPort 检查。前置条件启用 eBPF HostPort 能力或通过 portmap CNI 链式调用portmap CNI chaining支持 HostPortconnectivity-check-single-node.yaml标准检查减去所有要求多节点的检查项适合单节点集群/开发环境connectivity-check-proxy.yaml标准检查 针对 Layer 7 策略各种路径的额外检查connectivity-check-netpol-only.yaml与标准检查类似但不使用任何 Cilium CRD 网络策略仅依赖 Kubernetes 原生 NetworkPolicyconnectivity-check-quarantine.yaml仅包含标记为quarantine: true的检查项当前为 HostPort 相关的代理检查用于隔离验证已知不稳定场景connectivity-debug-tools.yaml调试工具型 Pod如query-dns-policy探针被覆盖为恒通过专为人工排障观察日志设计工作原理以就绪/存活探针承载连通性测试这套检查的设计思想非常巧妙没有独立的测试 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 probeTargetprobePath其中_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 服务器及其暴露方式Deployment服务暴露关键配置echo-aClusterIPecho-a:8080普通 ClusterIP 服务echo-bNodePort31414 Headlessecho-b-headless容器同时设置hostPort: 40000echo-b-hostHeadless 无端口服务echo-b-host-headlesshostNetwork: true监听 21000亲和echo-becho-cClusterIP Headless监听 8080容器hostPort: 40001挂载 ingress L7 策略echo-c-hostHeadlesshostNetwork: true监听 21002亲和echo-c无 ingress 策略echo-c关联的 ingress 策略定义在 echo-servers.cue仅允许GET /public$的 HTTP 请求访问 8080 端口这是 Layer 7 代理检查的基础。网络连通性检查network-check定义于 network.cuecomponent: network-check覆盖最基础的 Pod 间连通与出外网能力pod-to-aPod → Pod 直连目标echo-a:8080/public验证 Pod 间二层/三层连通与 DNS 解析pod-to-external-1111traffic: external目标https://1.1.1.1验证Pod 访问公网的能力需要 Cilium 正确配置 masquerading 与 egress 路径。策略检查policy-check允许、拒绝与 FQDN定义于 policy.cuecomponent: policy-check全部使用 CiliumNetworkPolicyCRDcilium.io/v2覆盖 Cilium 策略引擎的三个核心场景1. 拒绝场景pod-to-a-denied-cnpDeployment 设置_probeExpectFail: true其 CiliumNetworkPolicy 只放行 DNSkube-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-cnptraffic: 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-checkClusterIP、Headless 与宿主机网络定义于 services.cuecomponent: services-check覆盖 Kubernetes 服务负载均衡的各种形态pod-to-b-multi-node-clusterip跨节点访问 ClusterIP 服务echo-b:8080pod-to-b-multi-node-headless跨节点访问 Headless 服务echo-b-headless:8080直连 Pod IPhost-to-b-multi-node-clusterip/host-to-b-multi-node-headless宿主机网络hostNetwork: true下的 Pod 访问服务且设置dnsPolicy: ClusterFirstWithHostNet验证宿主机网络命名空间内 DNS 与服务的可用性。这些检查通过 Pod 反亲和性anti-affinity保证与echo-b分处不同节点从而真正覆盖跨节点的数据面路径。NodePort 与 HostPort 检查NodePortcomponent: nodeport-checkpod-to-b-multi-node-nodeport与pod-to-b-intra-node-nodeport访问echo-b-host-headless:31414覆盖 NodePort 服务在跨节点/同节点两种拓扑下的负载均衡HostPortcomponent: hostport-check仅存在于 hostport 变体清单中通过echo-b-host/echo-c-host的hostNetwork方式暴露 HostPort验证 eBPF HostPort 或 portmap 链式插件的正确性。基于 L7 策略的代理检查proxy-check定义于 proxy.cuecomponent: proxy-check专测 Cilium 的 Layer 7HTTP代理路径三种组合检查组场景pod-to-a-{intra,multi}-node-proxy-egress-policy仅egressL7 策略GET /public$→ echo-apod-to-c-{intra,multi}-node-proxy-ingress-policy仅ingressL7 策略echo-c自带见 echo-servers.cuepod-to-c-{intra,multi}-node-proxy-to-proxy-policyegress ingress 双向L7 策略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-*→ 设置_affinityPod 亲和性与目标 echo 服务器同节点验证同一节点内的数据面路径此时 Cilium 走本地路由/本地 BPF 路径名字含*-multi-node-*→ 设置_antiAffinityPod 反亲和性与目标 echo 服务器异节点强制跨节点调度验证 overlay 或原生路由下的跨节点转发。对应的亲和性字段由 resources.cue 模板渲染topologyKey固定为kubernetes.io/hostname。这也解释了为何单节点集群中 multi-node Pod 必然Pending——没有任何节点能满足与 echo-b 不同主机的反亲和约束。开发者文档CUE 模板化生成机制所有 YAML 并非手写而是用 CUE配置语言以声明式模板定义的。检查定义按职责拆分为多个.cue文件文件职责resources.cue核心模板Deployment、Service、CiliumNetworkPolicy 的完整结构定义、探针生成、亲和性渲染echo-servers.cue所有echo-*服务器及其服务暴露、ingress 策略的数据定义defaults.cue默认参数按命名模式推断探针目标echo-a:8080/echo-b:8080/echo-c:8080、默认镜像、拓扑标签与亲和性network.cue网络层检查定义Pod 直连、外部流量policy.cueL3/L4 与 FQDN 策略检查定义proxy.cueL7 代理检查定义注意L7 检查定义在proxy.cue而非policy.cueservices.cue服务层检查定义ClusterIP、Headless、HostPort、NodePortmain_tool.cue / ls_tool.cue / dump_tool.cueCUE 命令行工具过滤器流水线、ls列表与dump导出其中 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 trafficinternal dump $(HOSTPORT_OUT): $(SRC) # connectivity-check-hostport.yaml $(CUE) -t componentall dump $(SINGLE_OUT): $(SRC) # connectivity-check-single-node.yaml $(CUE) -t topologysingle-node dump $(PROXY_OUT): $(SRC) $(SERVERS_OUT) # connectivity-check-proxy.yaml $(CUE) -t componentproxy dump $(QUARANTINE_OUT): $(SRC) $(SERVERS_OUT) $(CUE) -t componentall -t quarantinetrue dump $(TOOLS_OUT): $(SRC) $(SERVERS_OUT) $(CUE) -t componentall -t typetool dumpCUE 工具链通过 Docker 容器docker.io/cuelang/cue:v0.2.2带 SHA 固定运行保证构建环境可复现。目录内可直接运行make help查看全部命令常用目标包括make all生成全部 YAMLmake deploykubectl apply -f connectivity-check-hostport.yaml将含 HostPort 检查的完整清单部署到当前 kubeconfig 指向的集群make evalcue 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 componentcomponent] [-t kindkind] [-t namename] [-t quarantinetrue] [-t topologytopology] [-t trafficany] [-t typetooltype] 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 componentall ls注意componentdefault的语义会排除hostport-check与proxy-check两类见 main_tool.cue这与标准清单默认不含 HostPort/L7 代理检查的定位一致。例如仅列出标准清单中的策略检查项$ cue -t componentpolicy -t kindCiliumNetworkPolicy ls排查与调试指南当kubectl get pods -n cilium-test中出现0/1或CrashLoopBackOff时按以下思路定位对照 Pod 名字定位场景Pod 名即检查场景名如pod-to-a-denied-cnp对应策略拒绝检查、pod-to-external-1111对应外部流量检查。结合本文件上述检查矩阵即可知道是哪条网络路径出了问题查看探针详情kubectl describe pod pod -n cilium-test查看Readiness/Liveness事件与探针失败原因Probe exec ... returned exit code探针失败本质是 curl 失败可用kubectl exec进入同命名空间其他 Pod 手动执行同样的 curl 命令复现区分预期行为单节点集群中multi-nodePodPending属正常pod-to-a-denied-cnp这类反探针 Pod 若长时间Ready反而说明拒绝预期落空应检查 CiliumNetworkPolicy 是否正确应用kubectl get cnp -n cilium-test检查策略导入状态用kubectl describe cnp name -n cilium-test确认策略处于 enforced 状态使用调试工具清单部署 connectivity-debug-tools.yaml通过make的-t typetool目标生成可获得探针恒通过的辅助 Pod便于人工跟进日志。例如 tools.cue 中的query-dns-policy会循环执行dig www.google.com并输出 DNS 解析结果可配合 FQDN 策略排障kubectl logs -l namequery-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考