Cilium 1.20 配置参数详解
Cilium 1.20 配置参数详解：三层配置体系（helm values → cilium-config ConfigMap → cilium config view 运行时值）的生效链路，按集群身份/数据面路由/IPAM/kube-proxy 替代/网络策略/Hubble/Envoy L7 与 DNS/eBPF 映射八组详解核心参数并附实测值，含 bpf.policyMapMax 修改→验证→回滚的完整实测闭环与键名映射排障实录。
Cilium 1.20 配置参数详解
目标：讲清 Cilium 1.20 的三层配置体系（helm values → cilium-config ConfigMap → 运行时生效配置），按主题详解核心参数并以实测环境真实值佐证，最后给出「改参数 → 验证生效 → 回滚」的完整实测闭环。全部键名与取值均取自本系列实测环境（k3s v1.36.5 单节点 + Cilium 1.20.4，安装与验证过程见《Cilium 1.20 部署指南：在 k3s 上安装与验证》）。
一、三层配置体系
Cilium 的配置链路分三层，理解层级关系是改对参数的前提：
helm values（安装/升级时传入，配置的"源头"）
│ helm 渲染
▼
ConfigMap cilium-config（kube-system，Agent 启动时读取的键值文件）
│ Agent 启动加载
▼
cilium config view（Agent 内存中的实际生效值，排障第一入口）
三条实践规则：
- 改参数只改 values（源头）：
helm upgrade --set ...后 helm 会重新渲染 ConfigMap 并滚动重启 Agent，新值才真正生效； - 直接手改 ConfigMap 不可靠：Agent 只在启动时读取，改完还得重启 Pod，且下一次 helm 操作会把手改内容整个覆盖回去；
- 验证只认
cilium config view：它显示 Agent 实际加载的值，是唯一可信的"生效证据"。
二、三个查看命令（实测回显）
2.1 helm values：安装时传了什么
export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml
helm get values cilium -n kube-system
实测输出（USER-SUPPLIED VALUES 即安装/升级时显式设置的键，与《Cilium 1.20 部署指南：在 k3s 上安装与验证》5.1 的 --set 清单一一对应）：
USER-SUPPLIED VALUES:
cluster:
name: default
hubble:
relay:
enabled: true
ipam:
operator:
clusterPoolIPv4PodCIDRList: 10.200.0.0/16
k8sServiceHost: 10.89.69.10
k8sServicePort: 6443
kubeProxyReplacement: true
operator:
replicas: 1
routingMode: tunnel
tunnelProtocol: vxlan
💡 注意：
helm get values只显示显式设置的键。想看 chart 全部键与默认值，用helm show values cilium/cilium --version 1.20.4（1.20.4 chart 约 7000 行，建议配合 grep 查询单个键）。
2.2 ConfigMap cilium-config：Agent 读什么
kubectl -n kube-system get cm cilium-config -o yaml
实测节选（结构与 2.3 完全一致，键为 kebab-case、值全为字符串）：
apiVersion: v1
data:
agent-not-ready-taint-key: node.cilium.io/agent-not-ready
auto-direct-node-routes: "false"
bpf-lb-map-max: "65536"
bpf-map-dynamic-size-ratio: "0.0025"
bpf-policy-map-max: "16384"
bpf-root: /sys/fs/bpf
cgroup-root: /run/cilium/cgroupv2
cluster-name: default
cluster-pool-ipv4-cidr: 10.200.0.0/16
cluster-pool-ipv4-mask-size: "24"
debug: "false"
enable-hubble: "true"
enable-ipv4: "true"
enable-ipv6: "false"
enable-l7-proxy: "true"
enable-policy: default
hubble-listen-address: :4244
ipam: cluster-pool
kube-proxy-replacement: "true"
routing-mode: tunnel
tunnel-protocol: vxlan
kind: ConfigMap
metadata:
name: cilium-config
namespace: kube-system
2.3 cilium config view：实际生效的是什么
cilium config view
本环境实测输出共 161 个键。以下按主题摘录相关键值（均为逐行照抄，分组组织见第三节详解）：
cluster-name default
cluster-id 0
ipam cluster-pool
cluster-pool-ipv4-cidr 10.200.0.0/16
cluster-pool-ipv4-mask-size 24
routing-mode tunnel
tunnel-protocol vxlan
datapath-mode veth
enable-tcx true
bpf-root /sys/fs/bpf
cgroup-root /run/cilium/cgroupv2
kube-proxy-replacement true
bpf-lb-map-max 65536
enable-policy default
enable-k8s-networkpolicy true
enable-l7-proxy true
enable-hubble true
hubble-listen-address :4244
bpf-policy-map-max 16384
bpf-map-dynamic-size-ratio 0.0025
debug false
⚠️
cilium config view同样依赖KUBECONFIG环境变量，未导出时会连不上集群。
三、核心参数分组详解
以下键名均为 cilium config view 的运行时键（kebab-case）；「对应 values 键」为 helm chart 的键（camelCase 嵌套），仅在本系列实测确认处标注。
3.1 集群身份
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| cluster-name | default | 集群名，ClusterMesh 多集群时必须全局唯一（values 键 cluster.name） |
| cluster-id | 0 | 集群编号，0 表示未启用 ClusterMesh（单集群默认） |
| max-connected-clusters | 255 | ClusterMesh 最大互联集群数上限 |
| identity-allocation-mode | crd | 安全身份的分配与存储模式（crd 存于 K8s CRD，与 kvstoremesh 区分） |
| identity-gc-interval | 15m0s | 身份垃圾回收周期 |
| synchronize-k8s-nodes | true | Agent 与 K8s 节点状态保持同步 |
3.2 数据面与路由
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| routing-mode | tunnel | 跨节点组网模式：tunnel（隧道）或 native（原生路由）（values 键 routingMode，实测确认） |
| tunnel-protocol | vxlan | 隧道协议，可选 vxlan / geneve（values 键 tunnelProtocol，实测确认） |
| datapath-mode | veth | 本地数据面形态：veth（Pod veth 对） |
| enable-tcx | true | 使用 TCX 挂载 eBPF 程序（内核 6.6+ 的改进挂载点） |
| auto-direct-node-routes | false | 是否自动向路由表注入节点间直连路由（native 模式常用） |
| bpf-root | /sys/fs/bpf | eBPF 文件系统挂载点 |
| cgroup-root | /run/cilium/cgroupv2 | cgroup v2 挂载点（socket 级程序挂载用） |
| enable-ipv4 / enable-ipv6 | true / false | 双栈开关，本环境仅 IPv4 |
| enable-ipv4-masquerade | true | 出节点流量做 SNAT 伪装 |
💡 技术拓展：跨节点组网的 tunnel 与 native 两路线对比——
模式 原理 适用 tunnel（VXLAN/Geneve） 节点间打隧道封装 Pod 流量 不要求底层网络可路由 Pod 网段，通用性最好 native（原生路由） 底层网络直接路由 Pod 网段（配合 BGP 或静态路由） 少一层封装性能更好，需网络团队配合 本系列实测环境节点在独立网段、底层无 Pod 网段路由能力，采用默认 tunnel + vxlan。
3.3 IPAM 地址分配
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| ipam | cluster-pool | 地址管理模式：cluster-pool（Cilium 自管地址池）/ kubernetes / eni 等 |
| cluster-pool-ipv4-cidr | 10.200.0.0/16 | 集群 Pod 总网段（values 键 ipam.operator.clusterPoolIPv4PodCIDRList，实测确认） |
| cluster-pool-ipv4-mask-size | 24 | 节点分片掩码，每节点从总池切一个 /24 |
| ipam-cilium-node-update-rate | 15s | CiliumNode 对象的同步周期 |
| k8s-require-ipv4-pod-cidr | false | 是否强制要求 K8s 节点提供 podCIDR |
节点分片与端点分配可通过 CRD 验证（实测回显见《Cilium 1.20 部署指南：在 k3s 上安装与验证》6.5 节：CiliumNode 持有 /24 分片，CiliumEndpoint 展示每个 Pod 的实配 IP）。
3.4 kube-proxy 替代与负载均衡
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| kube-proxy-replacement | true | eBPF 全面接管 kube-proxy（values 键 kubeProxyReplacement，实测确认） |
| bpf-lb-map-max | 65536 | Service/后端映射的 eBPF 表容量上限 |
| bpf-lb-external-clusterip | false | 是否允许集群外部访问 ClusterIP |
| node-port-bind-protection | true | 保护 NodePort 端口段不被其他进程占用 |
| enable-auto-protect-node-port-range | true | 自动保护 NodePort 范围配置 |
| default-lb-service-ipam | lbipam | LoadBalancer Service IP 的分配方式（lbipam 由 LB-IPAM 分配） |
| enable-lb-ipam | true | 启用 LB-IPAM（为 LoadBalancer Service 分配 IP） |
| service-no-backend-response | reject | Service 无后端时的响应方式（reject/drop） |
| enable-service-topology | false | 服务拓扑感知路由 |
3.5 网络策略
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| enable-policy | default | 策略执行模式：default（被策略选中的端点执行）/ always / never（values 键 policyEnforcementMode，实测确认） |
| enable-k8s-networkpolicy | true | 执行标准 K8s NetworkPolicy（networking.k8s.io/v1） |
| enable-non-default-deny-policies | true | 支持非默认 deny 型策略（allow 列表式） |
| enable-l7-proxy | true | L7 层策略经 Envoy 代理执行 |
| policy-deny-response | none | deny 时的响应包策略（none=静默丢弃） |
| enable-policy-secrets-sync | true | 策略引用的 TLS Secret 同步 |
| policy-secrets-namespace | cilium-secrets | 策略 Secret 的专用命名空间 |
| enable-endpoint-lockdown-on-policy-overflow | false | 策略映射溢出时是否锁死端点（安全加固项） |
3.6 Hubble 可观测
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| enable-hubble | true | 启用 Hubble（本环境 values 键 hubble.relay.enabled=true 部署 Relay，实测确认） |
| hubble-listen-address | :4244 | 本机 Hubble gRPC 监听地址 |
| hubble-disable-tls | false | Relay 访问本机 Hubble 时启用 mTLS |
| hubble-tls-cert-file / key-file / client-ca-files | /var/lib/cilium/tls/hubble/... | mTLS 证书三件套路径 |
| hubble-network-policy-correlation-enabled | true | 流日志关联命中的 NetworkPolicy |
| enable-metrics | true | 输出 Prometheus 指标 |
| monitor-aggregation | medium | 流事件聚合级别：none/low/medium/max（values 键 bpf.monitorAggregation，实测确认） |
| monitor-aggregation-flags | all | 聚合维度（按 TCP 标志位等） |
| monitor-aggregation-interval | 5s | 聚合时间窗 |
| envoy-access-log-enabled | true | Envoy 访问日志（L7 流量记录） |
💡 说明：
monitor-aggregation越高，流事件越少、Agent 内存开销越小；做精细流量分析时用cilium config配合hubble observe查看详情（命令实战见《Cilium 1.20 CLI 命令详解：cilium 与 hubble》）。
3.7 Envoy/L7 代理与 DNS 策略
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| external-envoy-proxy | true | Envoy 以独立 DaemonSet 部署（cilium-envoy） |
| proxy-cluster-max-connections | 1024 | Envoy 集群最大连接数 |
| proxy-connect-timeout | 2 | 代理上游连接超时（秒） |
| proxy-idle-timeout-seconds | 60 | 空闲连接超时（秒） |
| proxy-use-original-source-address | true | 代理保留客户端原始源地址 |
| dnsproxy-enable-transparent-mode | true | DNS 代理透明模式（FQDN 策略拦截 DNS） |
| tofqdns-endpoint-max-ip-per-hostname | 1000 | FQDN 策略下每个域名缓存的 IP 上限 |
| tofqdns-proxy-response-max-delay | 100ms | DNS 代理响应最大延迟 |
| tofqdns-dns-reject-response-code | refused | FQDN 策略拒绝时返回的 DNS 响应码 |
3.8 eBPF 映射与性能
| 运行时键 | 实测值 | 说明 |
|---|---|---|
| bpf-map-dynamic-size-ratio | 0.0025 | 动态 map 内存比例（占系统内存的比例） |
| bpf-policy-map-max | 16384 | 策略映射表上限（本系列实测修改过该值，见第四节） |
| bpf-policy-stats-map-max | 65536 | 策略统计表上限 |
| bpf-lb-map-max | 65536 | 服务负载均衡表上限 |
| preallocate-bpf-maps | false | 是否预分配 map（true 启动更快、内存占用更高） |
| bpf-distributed-lru | false | 分布式 LRU（大规模节点可开） |
| enable-ipv4-big-tcp | false | IPv4 BIG TCP（大帧特性，100G 级网络才需要） |
| unmanaged-pod-watcher-interval | 15s | 未托管 Pod 的检测周期 |
四、修改参数实测闭环（改 → 验 → 回滚）
4.1 键名映射规则与排障实录
helm values 键与运行时键不是同一套命名：values 是 camelCase 嵌套结构，渲染后变成 ConfigMap 的 kebab-case 扁平键。先用 helm show values 确认目标键的准确路径再改。
本系列实测踩过的坑：把运行时键名直接当 values 键传——
# ❌ 错误示范：顶层 kebab 键不是 chart 认识的 values 键
helm upgrade cilium cilium/cilium -n kube-system --reuse-values \
--set bpf-policy-map-max=32768 --version 1.20.4
执行后 helm get values 能看到值写进了 release，但 chart 模板不渲染未知键，cilium config view 中 bpf-policy-map-max 仍是 16384，即改了等于没改。正确键路径为 bpf.policyMapMax（bpf: 组下的 policyMapMax，chart 默认值 16384）。
4.2 实测：调大策略映射上限到 32768
export KUBECONFIG=/etc/rancher/k3s/server/k3s.yaml
helm upgrade cilium cilium/cilium -n kube-system \
--reuse-values --set bpf.policyMapMax=32768 --version 1.20.4 --wait
--wait 等待滚动更新完成；随后等待 Agent 全部就绪并验证生效值：
cilium status --wait
cilium config view | grep '^bpf-policy-map-max'
实测输出：
bpf-policy-map-max 32768
同时确认 helm get values cilium -n kube-system 中出现：
bpf:
policyMapMax: 32768
⚠️ 涉及 Agent 参数的修改都会触发 cilium DaemonSet 滚动重启（节点上的 eBPF 程序重载），期间新建 Pod 会短暂 Pending，生产环境请在维护窗口操作并先用
cilium status --wait确认滚动完成。
4.3 实测：回滚到默认值 16384
helm upgrade cilium cilium/cilium -n kube-system \
--reuse-values --set bpf.policyMapMax=16384 --version 1.20.4 --wait
cilium status --wait
cilium config view | grep '^bpf-policy-map-max'
实测输出：
bpf-policy-map-max 16384
4.4 cilium CLI 的等价方式
cilium upgrade 同样支持 --set（底层就是 helm upgrade），例如：
cilium upgrade --version 1.20.4 --set bpf.policyMapMax=32768
适用性建议：一次性小改动用 helm upgrade --set（与本系列实测一致）；长期配置建议固化到 values 文件（-f cilium-values.yaml）纳入版本管理，避免 --reuse-values 带来的隐式继承。
五、常见配置场景速查
| 场景 | values 键（helm） | 生效验证 |
|---|---|---|
| 更换 Pod 网段 | ipam.operator.clusterPoolIPv4PodCIDRList | cilium config view | grep cluster-pool-ipv4-cidr |
| 换隧道协议为 Geneve | tunnelProtocol: geneve | cilium config view | grep tunnel-protocol |
| 切换原生路由 | routingMode: native + autoDirectNodeRoutes: true | cilium config view | grep -E 'routing-mode|auto-direct' |
| 关闭 Hubble | hubble.relay.enabled=false + hubble.enabled=false | cilium status 中 Hubble Relay 消失 |
| 调策略映射上限 | bpf.policyMapMax | cilium config view | grep bpf-policy-map-max |
| 调流事件聚合 | bpf.monitorAggregation: low | cilium config view | grep monitor-aggregation |
| 打开调试日志 | debug.enabled: true | cilium config view | grep '^debug' |
（表中命令均为本系列实测命令形态；改后必滚动重启 Agent，验证前先 cilium status --wait。）
六、常见问题
6.1 为什么 cilium config view 的值和 helm values 对不上
两个原因：一是键名映射没对上（4.1 的排障实录，未知键被静默忽略）；二是 values 改了但 Agent 还没滚动重启，cilium config view 显示的仍是旧值——用 kubectl -n kube-system rollout status ds/cilium 看滚动进度，完成后旧值才会刷新。
6.2 直接改 ConfigMap 行不行
临时排障可以（改完 kubectl -n kube-system rollout restart ds/cilium 重启 Agent 生效），但下次任何 helm 操作都会覆盖手改内容，且配置漂移无迹可循。正确做法一律走 helm values。
6.3 config view 里有些键是空的（如 devices）
空值表示该项使用自动探测或未启用：devices 为空时 Agent 自动探测承载流量的网卡；kube-proxy-replacement-healthz-bind-address 为空表示未开启健康检查端点。这类键一般不需要显式设置。
6.4 改了参数 Pod 全部 Pending
Agent 滚动重启期间 CNI 未就绪，新 Pod 无法分配网络。等待滚动完成即可自愈；长时间未恢复按《Cilium 1.20 部署指南：在 k3s 上安装与验证》常见问题节排查 Agent 日志。
七、参考链接
- Cilium chart values（1.20）：https://github.com/cilium/cilium/blob/v1.20.4/install/kubernetes/cilium/values.yaml
- 官方 Configuration 文档：https://docs.cilium.io/en/stable/operations/configuration/
- helm 安装参考：https://docs.cilium.io/en/stable/installation/k8s-install-helm/
- Cilium CLI 参考：https://docs.cilium.io/en/stable/reference/cmdref/（cilium-config 相关子命令）
本系列导航
- 上一篇：《Cilium 1.20 部署指南：在 k3s 上安装与验证》——从零安装与完整验证回显
- 本篇：Cilium 1.20 配置参数详解
- 《Cilium 1.20 CLI 命令详解：cilium 与 hubble》——cilium config view 等命令的完整实战