基于K3s搭建GitOps环境2-配置Traefik

发表于 更新于

一、核心定位

本文作为GitOps环境搭建系列的第二篇，聚焦Traefik反向代理的配置与优化。Traefik是K3s集群默认集成的云原生反向代理与负载均衡工具，具备动态配置、服务自动发现等核心特性，无需重启即可实时更新路由规则。

在GitOps环境中，Traefik扮演”流量入口网关”角色，为所有组件（Gitea、ArgoCD、Tekton、Harbor等）提供统一的HTTPS访问入口，实现域名路由、负载均衡、TLS终结等核心功能。通过Traefik的IngressRoute资源，可以灵活配置HTTP/HTTPS/TCP/UDP等多种协议的路由规则。

二、部署前置检查

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

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# 1. 验证K3s集群状态
kubectl get nodes

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

# 3. 查看Traefik Service
kubectl get svc -n kube-system traefik

# 4. 验证Helm可用性
helm version --short

# 5. 验证域名解析（替换为实际域名）
nslookup traefik.example.io
````

**前置条件检查清单：**

- [ ] K3s集群运行正常
- [ ] Traefik Pod处于Running状态
- [ ] 域名`traefik.example.io`已解析至K3s节点IP
- [ ] Helm工具可用
- [ ] 具备kube-system命名空间操作权限

## 三、启用Traefik Dashboard

K3s集群（版本≥1.21）默认集成Traefik，但未启用其Dashboard功能。需注意的是，直接修改`/var/lib/rancher/k3s/server/manifests/traefik.yaml`配置文件，会在K3s重启后被系统自动覆盖，因此推荐通过`HelmChartConfig`自定义配置的方式，安全稳定地启用Dashboard。

### 3.1 创建HelmChartConfig配置文件

在Master节点创建持久化配置：

```bash
# 创建HelmChartConfig配置文件
sudo cat > /var/lib/rancher/k3s/server/manifests/traefik-config.yaml << EOF
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    dashboard:
      enabled: true
      domain: traefik.example.io  # 统一使用example.io域名
    ports:
      traefik:
        expose: true
    logs:
      access:
        enabled: true
EOF

# 重启K3s使配置生效
sudo systemctl restart k3s

3.2 配置Service与IngressRoute

创建traefik-dashboard.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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# traefik-dashboard.yaml
apiVersion: v1
kind: Service
metadata:
  name: traefik
  namespace: kube-system 
spec:
  allocateLoadBalancerNodePorts: true
  ports:
  - name: web
    nodePort: 80
    port: 80
    protocol: TCP
    targetPort: web
  - name: websecure
    nodePort: 443
    port: 443
    protocol: TCP
    targetPort: websecure
  selector:
    app.kubernetes.io/instance: traefik-kube-system
    app.kubernetes.io/name: traefik
  type: LoadBalancer

---

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard-web
  namespace: kube-system
spec:
  entryPoints:
    - web
  routes:
    - kind: Rule
      match: Host(`traefik.example.io`) && PathPrefix(`/dashboard`) || PathPrefix(`/api`)
      services:
        - name: api@internal
          kind: TraefikService

---

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard-websecure
  namespace: kube-system
spec:
  entryPoints:
    - websecure
  routes:
    - kind: Rule
      match: Host(`traefik.example.io`) && PathPrefix(`/dashboard`) || PathPrefix(`/api`)
      services:
        - name: api@internal
          kind: TraefikService
  tls:
    secretName: traefik-dashboard-tls

应用配置：

1
kubectl apply -f traefik-dashboard.yaml

注意：访问Dashboard时URL末尾必须添加/，正确格式为https://traefik.example.io/dashboard/。

四、配置IngressRoute实现服务代理

4.1 创建测试环境

1
2
3
# 创建测试应用
kubectl create deploy whoami --image=traefik/whoami --replicas=2
kubectl expose deploy whoami --port=80

4.2 HTTP路由配置

创建HTTP路由规则，通过指定路径访问服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# whoami-http-ingress-route.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami-ingress-web
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`traefik.example.io`) && PathPrefix(`/whoami`)
      kind: Rule
      services:
        - name: whoami
          port: 80

4.3 HTTPS路由配置

生成自签名证书（测试环境）：

1
2
3
4
5
6
7
8
# 生成自签名证书
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=traefik.example.io" \
  -addext "subjectAltName=DNS:traefik.example.io"

# 创建TLS Secret
kubectl create secret tls whoami-tls --cert=tls.crt --key=tls.key

配置HTTPS路由：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# whoami-https-ingress-route.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami-ingress-websecure
  namespace: default
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`traefik.example.io`) && PathPrefix(`/secure/whoami`)
      kind: Rule
      services:
        - name: whoami
          port: 80
  tls:
    secretName: whoami-tls

生产环境建议：使用cert-manager自动管理证书，详见基于K3s搭建GitOps4-证书管理。

4.4 TCP/UDP路由配置

Traefik支持代理MySQL、Redis等TCP/UDP服务，需通过IngressRouteTCP或IngressRouteUDP配置。

以Redis服务为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# redis-tcp-ingress-route.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: redis
  namespace: devops
spec:
  entryPoints:
    - redis  # 需在Traefik配置中启用redis入口点
  routes:
  - match: HostSNI(`*`)
    services:
    - name: redis
      port: 6379

TCP与HTTP路由差异：

  1. TCP路由使用HostSNI('*')匹配，HTTP路由使用Host()匹配
  2. TCP路由仅代理TCP协议，无法处理HTTP请求
  3. 同一入口点上，TCP路由优先级高于HTTP路由

五、验证部署结果

5.1 验证Traefik组件状态

1
2
3
4
5
6
7
8
9
10
11
# 查看Traefik Pod状态
kubectl get pods -n kube-system -l app=traefik

# 查看Traefik Service
kubectl get svc -n kube-system traefik

# 查看IngressRoute资源
kubectl get ingressroute -A

# 查看Traefik日志
kubectl logs -n kube-system -l app=traefik --tail=50

5.2 验证路由功能

1
2
3
4
5
6
7
8
9
10
# 测试HTTP访问
curl -v http://traefik.example.io/dashboard/
curl -v http://traefik.example.io/whoami

# 测试HTTPS访问（跳过证书验证）
curl -k -v https://traefik.example.io/dashboard/
curl -k -v https://traefik.example.io/secure/whoami

# 查看路由配置
kubectl describe ingressroute traefik-dashboard-websecure -n kube-system

5.3 清理测试资源

1
2
3
4
5
6
7
# 清理测试应用
kubectl delete deploy whoami
kubectl delete svc whoami

# 清理路由配置
kubectl delete ingressroute whoami-ingress-web whoami-ingress-websecure
kubectl delete secret whoami-tls

六、生产环境配置建议

6.1 启用访问日志

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 在HelmChartConfig中添加日志配置
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    logs:
      access:
        enabled: true
        format: json  # 使用JSON格式便于日志分析
        fields:
          general:
            defaultMode: keep
          headers:
            defaultMode: keep

6.2 配置中间件

Traefik中间件可用于实现路径重写、请求限流、认证等高级功能：

1
2
3
4
5
6
7
8
9
10
# 路径重写中间件示例
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: strip-prefix
  namespace: default
spec:
  stripPrefix:
    prefixes:
      - /api/v1

6.3 启用指标监控

1
2
3
4
5
6
7
8
9
10
11
12
13
# 启用Prometheus指标
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    metrics:
      prometheus:
        enabled: true
        addEntryPointsLabels: true
        addServicesLabels: true

七、常见问题修复

问题现象 排查方向 修复方案
Dashboard访问404 路由配置/路径格式 确认访问URL以/结尾，检查IngressRoute配置
HTTPS证书警告 证书配置/TLS Secret 检查证书Secret是否存在，确认域名匹配
服务无法访问 服务发现/端口映射 检查Service selector是否匹配Pod标签
TCP路由不生效 入口点配置 确认Traefik已启用对应TCP入口点
配置被覆盖 HelmChartConfig位置 确认配置文件在/var/lib/rancher/k3s/server/manifests/目录

八、配置参考

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

该目录包含：

  • Traefik Dashboard配置
  • IngressRoute示例
  • 中间件配置
  • 生产环境优化配置
  • 监控和日志配置

总结

本文完成了Traefik在K3s集群中的完整配置，包括Dashboard启用、HTTP/HTTPS路由配置、TCP/UDP服务代理等核心功能。Traefik作为GitOps环境的流量入口网关，为后续组件（Gitea、ArgoCD、Tekton、Harbor）提供了统一的访问入口和安全的路由能力。

配置完成后，建议通过测试应用验证各项功能正常。下一篇文章将配置CoreDNS内网域名解析，实现通过域名访问所有GitOps组件。