CCE NodeLocal DNSCache 说明
更新时间：2025-08-21
组件介绍
CCE NodeLocal DNSCache 组件是基于社区开源项目 NodeLocal DNSCache 的一套 DNS 本地缓存解决方案。在 CCE 集群中部署 NodeLocalDNS 可以提升服务发现的稳定性和性能，NodeLocal DNSCache 通过在集群节点上作为 DaemonSet 运行 DNS 缓存代理来提高集群DNS性能。该组件由两部分组成，分别是：NodeLocal DNSCache 本地缓存的 DaemonSet 和 用于 DNSConfig 注入的动态注入控制器 Deployment。
- NodeLocal DNSCache 本地缓存会在每个 Node 上创建一个 Pod 用于监听 Local IP（默认 IP 为 169.254.20.10），通过注入的 DNSConfig 配置， Pod 上的 DNS 请求会被 Local DNS 本地缓存所代理。
Node Local DNS 服务是基于CoreDNS提供的服务，但其仅具有代理和缓存的功能。
- 用于 DNSConfig 注入的动态注入控制器是基于 Admission Webhook 机制拦截 Pod 创建的请求，自动为新建 Pod 注入 DNSConfig 配置信息。
如果没有启用该 Webhook，则需要您手动添加 DNSConfig 配置。
NodeLocal DNSCache 工作原理图
- 在 Pod 创建流程中，新增了 Admission Webhook 为 Pod 注入 DNSConfig。
- 在 Pod 的域名解析流程中，数据链路如下：
| 编号 | 描述 |
|---|---|
| 1 | 对于已经注入 DNSCofig 的 Pod，默认请求 NodeLocal DNSCache 在节点上监听的 IP 实现域名解析。 |
| 2 | 如果 NodeLocal DNSCache 无缓存应答解析请求，则会根据域名是否为集群内域名，转发对应请求到 CoreDNS 或 VPC DNS 进行解析。 |
| 3 | CoreDNS对于解析失败的域名，会继续通过 VPC DNS 服务器进行解析。 |
| 4 | 对于已经注入 DNSCofig 的 Pod，默认优先使用 local DNS，在连接失败后请求 CoreDNS。但如果 Pod 本身使用的 DNS 请求库没有超时继续请求的设计，则只会使用localDNS。 |
| 5 | 未注入DNSConfig 的 Pod，会请求标准的 kube-dns 服务请求 CoreDNS 进行解析。 |
NodeLocal DNSCache 使用方式
为了使用 NodeLocal DNSCache，将请求 CoreDNS 的流量转到由本地 NodeLocal DNSCache 的 DaemonSet 代理，您需要在 Pod 内部注入 DNSConfig 配置，三种方式可供选择：
- 方式一：安装 CCE Node Local DNS 组件，通过组件中的 Webhook 实现 DNSConfig 注入，推荐使用该方式。
- 方式二：手动给 Pod 添加 DNSConfig
- 方式三：修改 kubelet 参数，并重启kubelet使其生效，不推荐该方式，业务存在中断风险。
方式一：DNSConfig 自动注入
前置条件：
- 集群安装 CCE NodeLocal DNSCache 组件
DNSConfig 动态注入控制器可实现在 Pod 新建时，自动注入 DNSConfig，无需手动添加配置。该 Webhook 默认会监听带有cce.baidu.com/node-local-dns-injection=enabled标签的命名空间中新建 Pod 的请求，您可以通过以下命令给命名空间打上Label标签:
Shell
1kubectl label namespace default cce.baidu.com/node-local-dns-injection=enabled请注意：
- 上述命令仅给 default 命名空间打上自动注入标签，这意味着只有在 default 命名空间下新建的 Pod 才会触发 Webhook 实现 DNSConfig 自动注入。如需修改命名空间，需要您将 default 替换成目标命名空间。
- 在满足上述条件下，如果您需要对部分 Pod 进行豁免（即不注入 DNSConfig），您可以给 Pod 添加标签：
cce.baidu.com/node-local-dns-injection=disabled。
DNSConfig自动注入生效后，您新建的 Pod 将会被添加以下字段：
YAML
1dnsConfig:
2 nameservers:
3 - 169.254.20.10
4 - 172.21.0.10
5 options:
6 - name: ndots
7 value: "3"
8 - name: attempts
9 value: "2"
10 - name: timeout
11 value: "1"
12 searches:
13 - default.svc.cluster.local
14 - svc.cluster.local
15 - cluster.local
16dnsPolicy: None说明：
- nameservers：配置成169.254.20.10（默认值）和 kube-dns 的 ClusterIP 对应的IP地址，其中 ClusterIP 将作为备份的DNS服务器地址
- searches：设置搜索域，保证集群内部域名能够被正常解析，默认为 default.svc.cluster.local、svc.cluster.local 和 cluster.local
- ndots：默认为3，可以适当降低 ndots 以提升解析效率
- attempts：默认为2，尝试解析次数
- timeout：默认为1，超时时间
在 方式一 下，如果您新建的 Pod 未被注入 DNSConfig，请检查以下条件（只有当以下条件全部满足时，才会实现 Pod 自动注入）：
- Pod 所在 Namespace 包含 label：cce.baidu.com/node-local-dns-injection=enabled
- Pod 所在 Namespace 不为: kube-system、cce-monitor 或 cprom-system
- Pod 不包含 label：cce.baidu.com/node-local-dns-injection=disabled
- Pod 不包含要求调度到 VirtualKubelet 节点的调度配置（如节点选择、节点亲和性等配置）
- Pod 的 hostNetwork 为 false 且 DNSPolicy 为 ClusterFirst 或 none，或 hostNetwork 为 true 且 DNSPolicy 为 ClusterFirstWithHostNet
方式二：手动添加DNSConfig
在不采用 方式一 的情况下，您需要手动添加 DNSConfig，参考案例如下：
YAML
1apiVersion: v1
2kind: Pod
3metadata:
4 name: test01
5 namespace: default
6spec:
7 containers:
8 - image: registry.baidubce.com/cce-plugin-pro/cce-cni/netshoot:latest
9 command:
10 - sleep
11 - "100000"
12 imagePullPolicy: Always
13 name: net-debug-container
14 dnsPolicy: None
15 dnsConfig:
16 nameservers: ["169.254.20.10","172.21.0.10"]
17 searches:
18 - default.svc.cluster.local
19 - svc.cluster.local
20 - cluster.local
21 options:
22 - name: ndots
23 value: "3"
24 - name: attempts
25 value: "2"
26 - name: timeout
27 value: "1"请注意：
- dnsPolicy必须为 None
- 其他参数介绍请参考
方式一说明
方式三：配置 kubelet 启动参数
您可以通过修改 kubelet 启动参数来全局控制Pod DNSConfig，详情请参考：Using NodeLocal DNSCache in Kubernetes Clusters。
组件功能
- 通过DNSConfig动态注入控制器Deployment，可以自动给新建 Pod 添加 DNSConfig 配置
- 通过在集群节点上以 Daemonset 的形式运行 NodeLocal DNS Cache，能够大幅提升集群内 DNS 解析性能
使用场景
通过在集群节点上作为 DaemonSet 运行 NodeLocal DNSCache 来提高集群DNS性能。
使用限制
- 集群版本在 1.18 以上
- CCE NodeLocal DNSCache 不支持 ARM 集群、边缘集群
- 能够使用 kubectl 访问集群，操作步骤见：通过kubectl连接集群
安装组件
安装 CCE NodeLocal DNSCache 组件有两种方式，分别是：组件管理安装 和 Helm 模版安装，建议您通过组件管理安装该组件。
方式一：通过组件管理安装 CCE Node Local DNS
- 登录百度智能云官网，并进入管理控制台。
- 选择“产品服务 > 云原生 > 容器引擎 CCE”，单击进入容器引擎管理控制台。
- 单击左侧导航栏中的 集群管理 > 集群列表。
- 在集群列表页面中，单击目标集群名称进入集群管理页面。
- 在集群管理页面单击 组件管理 。
- 在组件管理列表中选择 NodeLocal DNSCache 组件单击“安装”。
- 点击“确定”按钮完成组件的安装。
方式二：通过 Helm 模版安装 CCE NodeLocal DNSCache
- 登录百度智能云官网，并进入管理控制台。
- 选择“产品服务>云原生>容器引擎CCE”，单击进入容器引擎管理控制台。
- 单击左侧导航栏中的 “Helm > Helm 模版”。
- 在 Helm 模版页面中，单击 百度智能云模版 进入模版管理页面。
- 在模版管理页面中选择模版名称 cce-node-local-dns，然后单击 “安装”。
- 在 安装模版 页面中完成相关配置填写，点击 “确定” 按钮完成组件的安装。
相关配置填写说明如下表：
| 参数 | 是否必填 | 描述 | 获取路径 |
|---|---|---|---|
| ClusterDNSAddr | 是 | kube-system命名空间下 是kube-dns的ClusterIP对应的IP地址。NodeLocal DNSCache通过该服务与CoreDNS通信来解析集群内域名。 | 通过kubectl连接集群， 输入 kubectl get service kube-dns -n kube-system 命令可以获取对应的 IP 地址信息。如果您需要指定不同的上游DNS服务器，可以修改此参数。无默认值，从集群中获取。 |
| LocalDNSAddr | 否 | LocalDNSAddr 是 cce-node-local-dns 选择的本地侦听 IP 地址 | 默认为 169.254.20.10 ，可修改。 |
| searchDomains | 否 | 搜索域名，保证集群内部域名能够被正常解析 | 默认为 default.svc.cluster.local,svc.cluster.local,cluster.local，可修改。 |
| ndots | 否 | 可以适当降低ndots以提升解析效率 | 默认为 3，可修改。 |
| attempts | 否 | 解析尝试次数 | 默认为 2，可修改。 |
| timeout | 否 | 超时时间 | 默认为 1，可修改。 |
| forbiddenNamespace | 否 | 禁止 Pod 注入 DNSConfig 的 Namespace 列表 | 默认为 kube-system,cprom-system,cce-monitor，可修改。 |
部署情况
安装 CCE NodeLocal DNSCache 组件，将在 Kubernetes 集群中部署以下对象:
| 资源名称 | 类型 |
|---|---|
| node-local-dns | ServiceAccount |
| cce-node-local-dns-cce-reserved | ConfigMap |
| node-local-dns | ConfigMap |
| cce-node-local-dns | ClusterRole |
| cce-node-local-dns | ClusterRoleBinding |
| kube-dns-upstream | Service |
| node-local-dns | Service |
| node-local-dns-webhook | Service |
| node-local-dns | DaemonSet |
| cce-node-local-dns-webhook | Deployment |
| pod-mutating.node-local-dns.cce.baidu.com | MutatingWebhookConfiguration |
可观测性
您可以通过抓取 NodeLocal DNSCache 暴漏的指标接口，观测 NodeLocal DNSCache 组件的工作情况。
- 在集群中获取指标数据可以通过该方式：
Shell
1curl http://<local ip>:9253/metrics # 默认为 169.254.20.10下面是常见的 NodeLocal DNSCache 指标介绍：
| 指标 | 含义 | 类型 | 单位 |
|---|---|---|---|
| coredns_build_info | CoreDNS的版本，修订和构建的 goversion | Gauge | / |
| coredns_cache_entries | 缓存中的元素数量 | Gauge | 个 |
| coredns_cache_hits_total | 缓存命中的数量 | Counter | 次 |
| coredns_cache_misses_total | 缓存未命中的数量 | Counter | 次 |
| coredns_cache_requests_total | 缓存请求的数量 | Counter | 次 |
| coredns_dns_request_duration_seconds | 每个请求在每个区域所花费的时间的直方图 | Histogram | 秒 |
| coredns_dns_request_size_bytes | EDNS0 UDP缓冲区的大小（对于TCP为64K） | Gauge | 字节 |
| coredns_dns_requests_total | DNS请求的数量 | Counter | 次 |
| coredns_dns_response_size_bytes | 返回的响应的大小 | Gauge | 字节 |
| coredns_dns_responses_total | 响应状态代码的数量 | Counter | 次 |
| coredns_plugin_enabled | 某插件在每个服务器和区域基础上是否启动 | Gauge | / |
| coredns_reload_failed_total | 重新加载失败的次数 | Counter | 次 |
在 CProm 中添加对 CCE NodeLocal DNSCache 的指标采集任务
在 CProm 中添加对 Node-Problem-Detector 的指标采集规则之前，需要先为 CCE 集群关联 CProm 实例，并添加指标采集任务。 操作参考：
添加如下指标采集任务：
YAML
1job_name: 'localdns'
2scheme: http
3static_configs:
4- targets: [<local ip>:9253']版本记录
| 版本号 | 适配集群版本 | 更新时间 | 更新内容 | 影响 |
|---|---|---|---|---|
| 1.1.0 | CCE/v1.18/v1.20 | 2023.11.20 | 首次上线 | - |
| 1.1.1 | CCE/v1.18/v1.20 | 2023.12.21 | 缺陷修复：修正 DNSConfig 注入搜索域错误的问题 | - |
| 1.1.2 | CCE/v1.18/v1.20 | 2023.12.22 | 缺陷修复：修正 Webhook 拦截规则 | - |