企业官网建设流程全解析

minikube Traefik Ingress Controller Addon 完整实战指南：启用、Ingress 路由、TLS 证书与 Nginx 迁移

【免费下载链接】minikubeRun Kubernetes locally项目地址: https://gitcode.com/gh_mirrors/mi/minikube

本篇技术指南以 minikube 官方 Traefik addon 为核心，完整讲解如何通过 Helm Chart 在kube-system命名空间部署 Traefik 反向代理与 Ingress Controller，并演示基于 Host 与 Path 的 Ingress 路由、Dashboard 访问、自签名与 mkcert 可信证书配置，以及从 nginx ingress addon 的迁移路径。读完本文，你将掌握在本地单节点集群中"开箱即用"地接入 Traefik，并具备结合 minikube 源码理解 addon 底层 helm 调用链的能力。

Traefik Addon 概览

Traefik 是一款 HTTP 反向代理与 Ingress Controller，用于将入站流量按规则路由到后端 Service。minikube 的 traefik addon 通过 Traefik 官方 Helm Chart 将 Traefik 安装到kube-system命名空间中，并绑定节点端口 80/443（hostPort），因此启用后即可直接用minikube ip访问集群中的应用。

从源码结构看，traefik addon 在 pkg/addons/config.go 中被注册为一个标准的布尔型 addon，其回调链为EnableOrDisableAddon与verifyAddonStatus：

• EnableOrDisableAddon负责在节点内执行实际的 helm 安装/卸载；
• verifyAddonStatus在启用后校验 addon 是否真正就绪；
• pkg/addons/config.go 将traefik的验证标签映射为app.kubernetes.io/name=traefik，即通过该标签查找 Traefik Pod 来确认状态。

前置条件

• minikube v1.39.0 或更高版本（traefik addon 在该版本引入）；
• kubectl（与集群交互）；
• 集群节点具备访问外网的出站能力：启用 addon 时需要在节点内下载 helm 与 Chart（集成测试会显式检测该条件，见后文）。

启用 Traefik Addon

启用命令：

minikube addons enable traefik

典型输出如下：

! traefik is a 3rd party addon and is not maintained or verified by minikube maintainers, enable at your own risk. * traefik is maintained by 3rd party (Traefik Labs) for any concerns contact traefik on GitHub. * Verifying traefik addon... * To open the Traefik dashboard: minikube addons open traefik For more information see https://minikube.sigs.k8s.io/docs/handbook/addons/traefik * The 'traefik' addon is enabled

底层执行原理：helm 调用链

启用过程中 minikube 会在 VM/容器内部依次完成三件事：

1. 检查/usr/bin/helm是否可用，若缺失、损坏或版本无效则自动下载并安装 helm 到/usr/bin（见 pkg/addons/addons.go 与 pkg/addons/helm.go）；
2. 执行helm upgrade --install安装 Chart（见 pkg/addons/helm.go）；
3. 通过app.kubernetes.io/name=traefik标签轮询 Pod 状态完成验证。

helm 命令的实际形态可以从 pkg/addons/helm_test.go 的断言中看到，例如启用时执行：

sudo KUBECONFIG=/var/lib/minikube/kubeconfig helm upgrade --install traefik <chart-repo>/traefik \ --create-namespace --namespace kube-system --set key=value --values /etc/kubernetes/addons/values.yaml

访问 Traefik Dashboard

Traefik 自带内置 Dashboard，可直观查看 routers、services 与 middlewares。

方式一：minikube addons open（推荐）

从宿主机访问 Dashboard 最直接的方式：

minikube addons open traefik

该命令会自动定位 Traefik Dashboard 服务并在默认浏览器中打开。其提示信息在源码中由 pkg/addons/addons.go 生成。

方式二：minikube service（无头环境）

在无图形界面环境，或浏览器未自动打开时，可手动获取服务 URL：

minikube service traefik -n kube-system

示例输出：

┌─────────────┬─────────┬───────────────┬───────────────────────────┐ │ NAMESPACE │ NAME │ TARGET PORT │ URL │ ├─────────────┼─────────┼───────────────┼───────────────────────────┤ │ kube-system │ traefik │ traefik/8080 │ http://192.168.64.3:31918 │ │ │ │ web/80 │ http://192.168.64.3:30455 │ │ │ │ websecure/443 │ http://192.168.64.3:31425 │ └─────────────┴─────────┴───────────────┴───────────────────────────┘ ...

Service 暴露三个端点：

1. traefik/8080：Traefik 管理 Dashboard（始终是第一个 URL）；
2. web/80：标准 HTTP 流量的入口；
3. websecure/443：HTTPS 安全流量的入口。

注意：web/80与websecure/443返回的 URL 并非必需。Traefik 通过hostPort直接绑定节点的 80/443 端口，因此可以直接用 minikube IP 访问应用，例如http://$(minikube ip)。

只打印 Dashboard URL：

minikube service traefik -n kube-system --url | head -n 1

示例输出：

http://192.168.64.3:31918

实战：部署应用并通过 Ingress 暴露服务

下面以一个 echo server 为例，演示标准 Kubernetes Ingress 资源如何被 Traefik 消费。

Step 1：部署应用

创建示例命名空间并部署一个简单的 echo server：

cat <<'EOF' | kubectl apply -f - apiVersion: v1 kind: Namespace metadata: name: traefik-example --- apiVersion: apps/v1 kind: Deployment metadata: name: app namespace: traefik-example labels: app: traefik-app spec: replicas: 1 selector: matchLabels: app: traefik-app template: metadata: labels: app: traefik-app spec: containers: - name: echo-server image: kicbase/echo-server:1.0 ports: - containerPort: 8080 --- apiVersion: v1 kind: Service metadata: name: app namespace: traefik-example spec: ports: - port: 8080 targetPort: 8080 selector: app: traefik-app EOF

示例输出：

namespace/traefik-example created deployment.apps/app created service/app created

等待 Deployment 完成滚动：

kubectl rollout status deployment app -n traefik-example

示例输出：

deployment "app" successfully rolled out

Step 2：创建 Ingress

创建同时包含 host 与 path 两种路由规则的 Ingress，便于分别测试两种匹配方式：

cat <<'EOF' | kubectl apply -f - apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app namespace: traefik-example spec: ingressClassName: traefik rules: - host: traefik.example http: paths: - path: / pathType: Prefix backend: service: name: app port: number: 8080 - http: paths: - path: /app pathType: Prefix backend: service: name: app port: number: 8080 EOF

示例输出：

ingress.networking.k8s.io/app created

注意ingressClassName: traefik是显式指定 IngressClass 的写法；若省略该字段，Traefik 也会自动接管，因为 traefik addon 注册的 IngressClass 设置了ingressClass.isDefaultClass=true（详见下文"迁移"一节）。

Step 3：测试 Ingress

Traefik 通过hostPort绑定节点 80/443，因此直接用 minikube IP 即可发起请求。

Host 路由测试

携带Host: traefik.example请求头访问：

curl -H "Host: traefik.example" http://$(minikube ip)

示例输出：

Request served by app-7c5b849f45-vld2k HTTP/1.1 GET / Host: traefik.example Accept: */* Accept-Encoding: gzip User-Agent: curl/8.7.1 X-Forwarded-For: 192.168.64.1 X-Forwarded-Host: traefik.example X-Forwarded-Port: 80 X-Forwarded-Proto: http X-Forwarded-Server: traefik-59b65cb4f6-zr4d4 X-Real-Ip: 192.168.64.1

Path 路由测试

访问/app路径：

curl http://$(minikube ip)/app

示例输出：

Request served by app-7c5b849f45-kf2l4 HTTP/1.1 GET /app Host: 192.168.64.3 Accept: */* Accept-Encoding: gzip User-Agent: curl/8.7.1 X-Forwarded-For: 192.168.64.1 X-Forwarded-Host: 192.168.64.3 X-Forwarded-Port: 80 X-Forwarded-Proto: http X-Forwarded-Server: traefik-59b65cb4f6-khztt X-Real-Ip: 192.168.64.1

HTTPS 访问

Traefik 默认使用自签名证书，可用--insecure跳过校验做 host 维度的 HTTPS 测试：

curl --insecure -H "Host: traefik.example" https://$(minikube ip)

示例输出：

Request served by app-7c5b849f45-vld2k HTTP/1.1 GET / Host: traefik.example Accept: */* Accept-Encoding: gzip User-Agent: curl/8.7.1 X-Forwarded-For: 192.168.64.1 X-Forwarded-Host: traefik.example X-Forwarded-Port: 443 X-Forwarded-Proto: https X-Forwarded-Server: traefik-59b65cb4f6-zr4d4 X-Real-Ip: 192.168.64.1

注意响应中的X-Forwarded-Proto: https与X-Forwarded-Port: 443，这是 Traefik 在 TLS 终止后透传给后端的真实链路信息。

浏览器访问 HTTPS

在浏览器访问https://$(minikube ip)/app时会看到证书告警（如"您的连接不是私密连接"），因为默认证书是自签名的。本地开发阶段可以安全地跳过该告警：

• 跳过告警：点击高级，然后选择继续前往 <IP>（不安全）。

Step 4：查看 Dashboard 中的路由与服务

打开 Dashboard：

minikube addons open traefik

HTTP Routers

Traefik 会自动为应用创建两个 HTTP Router：一个对应 host 路由规则（traefik.example），一个对应 path 路由规则（/app）。

HTTP Services

流量最终被路由到traefik-example命名空间中的 Kubernetes Service（app）。

Step 5：配置自定义 TLS 证书（可选）

默认自签名证书会导致浏览器安全告警。如需在本地开发中使用受信任证书，可借助 mkcert 为域名签发证书：

1. 安装并初始化本地 CA：

   mkcert -install

   示例输出：

   The local CA is now installed in the system trust store! ⚡️ The local CA is now installed in the Firefox trust store (requires browser restart)! 🦊

   警告：在系统信任库安装本地 CA 会提升其信任级别。请务必保管好根 CA 私钥，其存放位置为：

   • Linux：~/.local/share/mkcert/rootCA-key.pem
   • macOS：~/Library/Application Support/mkcert/rootCA-key.pem
   • Windows：%LocalAppData%\mkcert\rootCA-key.pem

   若该私钥泄露，攻击者可签发任意域名的可信证书，从而实施针对本机的中间人（MITM）攻击。

2. 生成证书：

   mkcert traefik.example

   示例输出：

   Created a new certificate valid for the following names 📜 - "traefik.example" The certificate is at "./traefik.example.pem" and the key at "./traefik.example-key.pem" ✅ It will expire on 16 October 2028 🗓

3. 创建 Secret：

   kubectl create secret tls app-tls -n traefik-example \ --cert=traefik.example.pem --key=traefik.example-key.pem

   示例输出：

   secret/app-tls created

4. 更新 Ingress：为 Ingress 打补丁，加入tls配置：

   kubectl patch ingress app -n traefik-example --type=merge \ -p '{"spec":{"tls":[{"hosts":["traefik.example"],"secretName":"app-tls"}]}}'

   示例输出：

   ingress.networking.k8s.io/app patched

5. 配置 DNS：将主机名映射到 minikube IP：

   echo "$(minikube ip) traefik.example" | sudo tee -a /etc/hosts

完成后即可在浏览器直接访问https://traefik.example，证书完全受信任。

Step 6：清理示例

删除示例命名空间即可移除应用及其关联资源：

kubectl delete namespace traefik-example

从 ingress（nginx）addon 迁移

警告：默认的ingress（nginx）addon 已不再维护，minikube 推荐改用traefikaddon。

注意：ingress与traefik两个 addon不能同时启用，因为两者都绑定 80/443 端口。启用traefik前必须先禁用ingress：

minikube addons disable ingress minikube addons enable traefik

若已有应用从 nginx addon 迁移到 traefik addon，需要处理两处差异：

1. 更新 IngressClass：如果现有 Ingress 显式声明了ingressClassName: nginx，请改为ingressClassName: traefik，或直接删除该字段。省略该字段时，Traefik 会自动接管该 Ingress，因为 traefik addon 将自身注册为默认 IngressClass（ingressClass.isDefaultClass=true）。

2. 替换 nginx 专属注解：nginx.ingress.kubernetes.io/前缀的注解（如 rewrite target、自定义 header、SSL 重定向等）会被 Traefik 忽略。基础路由场景下这些注解通常可以直接删除；需要高级路由或中间件能力时，请改用 Traefik 的 Middlewares 或 Traefik 专属注解。

从源码看，ingress与traefik两个 addon 在 pkg/addons/config.go 与 pkg/addons/config.go 中各自独立注册，但其回调链均包含EnableOrDisableAddon，且都通过 Helm Chart 部署到集群，正是端口冲突导致二者无法共存。

禁用 Traefik Addon

minikube addons disable traefik

该命令会在节点内执行helm uninstall traefik -n kube-system（对应 pkg/addons/helm.go 的实现），移除全部 Traefik 资源。helm_test.go 中断言卸载命令形态为：

sudo KUBECONFIG=/var/lib/minikube/kubeconfig helm uninstall traefik --namespace kube-system

故障排查

确认 Traefik Pod 处于 Running 状态：

kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik

示例输出：

NAME READY STATUS RESTARTS AGE traefik-6b5d4cb8f7-x9z2k 1/1 Running 0 2m

确认 Traefik Service 已创建并暴露端口：

kubectl get svc -n kube-system -l app.kubernetes.io/name=traefik

示例输出：

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE traefik LoadBalancer 10.96.123.45 <pending> 8080:31808/TCP,80:31080/TCP,443:31443/TCP 2m

注意EXTERNAL-IP为<pending>属正常现象：Traefik 依赖hostPort绑定节点端口，并不依赖 LoadBalancer 分配外部 IP。

仓库内的集成测试佐证

minikube 仓库自带针对该 addon 的集成测试 test/integration/addon_traefik_test.go，其验证逻辑与本文实战步骤一致：

• 启动带--memory=3072的 minikube profile；
• 先通过minikube ssh curl探测 guest VM 的外网出站能力（下载 helm/chart 所需），无外网则跳过测试；
• 执行minikube addons enable traefik；
• 通过 kustomize 部署测试资源（见 test/integration/testdata/traefik/：ns.yaml、pod.yaml、service.yaml、ingress.yaml与kustomization.yaml），其中 Ingress 使用ingressClassName: traefik与/test前缀路径；
• 等待traefik-nginxPod 就绪后，用http://<minikube-ip>/test轮询请求（指数退避重试），断言响应体为it works。

这套测试用例可视为官方对"启用 addon → 部署应用 → 经 Traefik 路由访问"全链路的最小可复现样本，也印证了前文所有命令与配置的真实性与可运行性。

延伸阅读

• pkg/addons/config.go 与 pkg/addons/addons.go：addon 注册、验证标签与启用提示的源码实现；
• pkg/addons/helm.go 与 pkg/addons/helm_test.go：helm 安装/卸载命令的底层构造与测试断言；
• test/integration/addon_traefik_test.go 与 test/integration/testdata/traefik/：官方集成测试及其 kustomize 清单；
• site/content/en/docs/handbook/addons/traefik.md：本文对应的官方英文文档原文；
• 更多 addon 清单与配置项可查阅 deploy/addons 目录。

【免费下载链接】minikubeRun Kubernetes locally项目地址: https://gitcode.com/gh_mirrors/mi/minikube