基于K3s搭建GitOps环境3-配置内网域名

发表于 更新于

一、核心定位

本文作为GitOps环境搭建系列的第三篇，聚焦CoreDNS内网域名解析的配置与优化。CoreDNS是K3s集群默认集成的DNS服务器，负责处理集群内部的域名解析（如Service域名、Pod域名等）。

在GitOps环境中，CoreDNS扮演”域名解析中枢”角色，为所有组件（Traefik、Gitea、ArgoCD、Tekton、Harbor等）提供统一的内网域名解析服务。通过配置自定义域名映射，可以实现通过易记的域名访问各组件，替代复杂的IP地址访问方式，提升运维效率和可维护性。

二、部署前置检查

部署前需验证K3s集群状态及CoreDNS基础运行情况：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 验证K3s集群状态
kubectl get nodes

# 2. 验证CoreDNS是否已运行（K3s默认集成）
kubectl get pods -n kube-system -l k8s-app=kube-dns

# 3. 查看CoreDNS Service
kubectl get svc -n kube-system kube-dns

# 4. 测试默认DNS解析功能
kubectl run test-dns --image=busybox:1.28 --rm -it --restart=Never -- nslookup kubernetes.default

# 5. 验证内网IP可达性（替换为实际IP）
ping -c 3 192.168.1.100

前置条件检查清单：

  • K3s集群运行正常
  • CoreDNS Pod处于Running状态
  • 内网IP地址可达且稳定
  • 已规划好内网域名体系（统一使用example.io）
  • 具备kube-system命名空间操作权限

三、持久化配置CoreDNS

K3s启动时会自动部署CoreDNS组件，但直接修改CoreDNS配置文件（如编辑ConfigMap或修改/var/lib/rancher/k3s/server/manifests/coredns.yaml）存在明显缺陷——K3s重启、升级时会自动初始化CoreDNS配置，所有手动修改的内容会被覆盖。因此，需采用K3s官方推荐的coredns-custom ConfigMap持久化配置方案。

3.1 创建coredns-custom ConfigMap

创建coredns-custom.yaml配置文件，定义内网域名解析规则：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# coredns-custom.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  # 可选配置：开启CoreDNS解析日志，便于调试
  log.override: |
    log
  # 自定义内网域名解析规则（CoreDNS会自动加载后缀为.server的配置片段）
  gitops.server: |
    example.io {
      errors          # 输出域名解析错误日志
      cache 30        # 解析结果缓存30秒
      hosts {
        # GitOps组件域名映射（替换为实际IP地址）
        192.168.1.100 traefik.example.io    # Traefik反向代理
        192.168.1.101 harbor.example.io     # Harbor镜像仓库
        192.168.1.102 gitea.example.io      # Gitea代码仓库
        192.168.1.103 tekton.example.io     # Tekton CI流水线
        192.168.1.104 argocd.example.io     # ArgoCD GitOps核心
        fallthrough   # 无匹配域名时转发至下一级解析器
      }
      prometheus :9153  # 开启Prometheus监控
      forward . /etc/resolv.conf  # 非内网域名转发至宿主机DNS
      loop             # 防止解析环路
      reload           # 配置变更自动重载
      loadbalance      # 开启负载均衡
    }

关键配置详解：

  • gitops.server：CoreDNS约定，后缀为.server的配置片段会被自动加载
  • example.io：内网根域名，所有GitOps组件域名基于此配置
  • hosts段：核心的域名-IP映射区域，按实际网络环境配置
  • fallthrough：当hosts中无匹配域名时，转发至forward指定的解析器
  • forward . /etc/resolv.conf：非内网域名转发至宿主机DNS

3.2 应用ConfigMap配置

1
2
3
4
5
# 应用CoreDNS自定义配置
kubectl apply -f coredns-custom.yaml

# 验证ConfigMap创建
kubectl get configmap coredns-custom -n kube-system -o yaml

3.3 重启CoreDNS使配置生效

1
2
3
4
5
6
7
8
# 重启CoreDNS Pod加载新配置
kubectl delete pods -n kube-system -l k8s-app=kube-dns

# 监控Pod重启过程
kubectl get pods -n kube-system -l k8s-app=kube-dns -w

# 验证CoreDNS运行状态
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=20

四、验证内网DNS解析

4.1 创建测试环境

1
2
3
4
5
# 创建测试Pod
kubectl create deploy dns-test --image=busybox:1.28 --replicas=1 -- sleep 3600

# 等待Pod启动
kubectl get pods -l app=dns-test -w

4.2 执行解析测试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 进入测试Pod
kubectl exec -it $(kubectl get pod -l app=dns-test -o jsonpath='{.items[0].metadata.name}') -- /bin/sh

# 容器内执行解析测试
# 1. 测试GitOps组件域名解析
nslookup traefik.example.io
nslookup harbor.example.io
nslookup gitea.example.io
nslookup tekton.example.io
nslookup argocd.example.io

# 2. 测试ping连通性
ping -c 3 traefik.example.io
ping -c 3 harbor.example.io

# 3. 测试外网域名解析（验证forward功能）
nslookup google.com
nslookup github.com

# 退出容器
exit

4.3 验证解析结果

解析结果应显示对应的IP地址：

  • traefik.example.io → 192.168.1.100
  • harbor.example.io → 192.168.1.101
  • gitea.example.io → 192.168.1.102
  • 外网域名应正常解析

4.4 清理测试资源

1
2
# 清理测试Pod
kubectl delete deploy dns-test

五、进阶配置：暴露CoreDNS供集群外访问

若需让K3s集群外的设备（如开发机、其他服务器）使用CoreDNS解析内网域名，可通过Traefik暴露CoreDNS的UDP 53端口。

5.1 配置Traefik UDP入口点

首先确保Traefik已启用UDP支持，编辑Traefik配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 在Traefik HelmChartConfig中添加UDP入口点
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    ports:
      dns-udp:
        port: 53
        expose: true
        exposedPort: 53
        protocol: UDP

5.2 创建IngressRouteUDP规则

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# coredns-external.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRouteUDP
metadata:
  name: coredns-external
  namespace: kube-system
spec:
  entryPoints:
    - dns-udp
  routes:
    - match: HostSNI(`*`)
      services:
        - name: kube-dns
          port: 53

应用配置：

1
kubectl apply -f coredns-external.yaml

5.3 集群外设备配置

在集群外设备上配置DNS服务器：

1
2
3
4
5
6
# Linux系统
sudo echo "nameserver <K3s节点IP>" > /etc/resolv.conf

# 或编辑/etc/resolv.conf
# nameserver <K3s节点IP>
# search example.io

六、生产环境配置建议

6.1 高可用配置

1
2
3
4
5
# 配置多个DNS服务器
forward . 8.8.8.8 8.8.4.4 /etc/resolv.conf {
  max_concurrent 1000  # 最大并发查询数
  expire 10s  # 连接过期时间
}

6.2 性能优化

1
2
3
4
5
6
7
# 调整缓存和性能参数
cache {
  success 9984 3600  # 成功响应缓存
  denial 9984 30     # 否定响应缓存
  prefetch 10 60s    # 预取设置
}
ready :8181  # 就绪检查端点

6.3 安全配置

1
2
3
4
5
# 限制访问范围
acl {
  allow net 192.168.1.0/24  # 只允许内网访问
  block
}

七、常见问题修复

问题现象 排查方向 修复方案
域名解析失败 CoreDNS配置/网络 检查coredns-custom ConfigMap，验证网络连通性
解析结果不正确 hosts映射错误 检查IP地址是否正确，确认网络可达
CoreDNS Pod重启失败 配置语法错误 检查CoreDNS日志：kubectl logs -n kube-system <coredns-pod>
外网域名无法解析 forward配置 检查/etc/resolv.conf内容，测试外网连通性
配置修改不生效 未重启CoreDNS 重启CoreDNS Pod：kubectl delete pods -n kube-system -l k8s-app=kube-dns

八、配置参考

所有CoreDNS配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops/coredns

该目录包含：

  • CoreDNS自定义配置模板
  • 生产环境优化配置
  • 外部访问配置示例
  • 监控和日志配置

总结

本文完成了CoreDNS在K3s集群中的持久化配置，实现了GitOps组件内网域名解析功能。通过coredns-custom ConfigMap方案，确保配置在K3s重启、升级后不丢失，保障域名解析服务的稳定性。

配置完成后，所有GitOps组件（Traefik、Gitea、ArgoCD、Tekton、Harbor）均可通过统一的example.io域名访问，极大简化了运维操作。下一篇文章将部署cert-manager证书管理，为所有组件配置HTTPS安全访问。