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

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/443hostPort因此启用后即可直接用minikube ip访问集群中的应用。从源码结构看traefik addon 在 pkg/addons/config.go 中被注册为一个标准的布尔型 addon其回调链为EnableOrDisableAddon与verifyAddonStatusEnableOrDisableAddon负责在节点内执行实际的 helm 安装/卸载verifyAddonStatus在启用后校验 addon 是否真正就绪pkg/addons/config.go 将traefik的验证标签映射为app.kubernetes.io/nametraefik即通过该标签查找 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/容器内部依次完成三件事检查/usr/bin/helm是否可用若缺失、损坏或版本无效则自动下载并安装 helm 到/usr/bin见 pkg/addons/addons.go 与 pkg/addons/helm.go执行helm upgrade --install安装 Chart见 pkg/addons/helm.go通过app.kubernetes.io/nametraefik标签轮询 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 keyvalue --values /etc/kubernetes/addons/values.yaml访问 Traefik DashboardTraefik 自带内置 Dashboard可直观查看 routers、services 与 middlewares。方式一minikube addons open推荐从宿主机访问 Dashboard 最直接的方式minikube addons open traefik该命令会自动定位 Traefik Dashboard 服务并在默认浏览器中打开。其提示信息在源码中由 pkg/addons/addons.go 生成。方式二minikube service无头环境在无图形界面环境或浏览器未自动打开时可手动获取服务 URLminikube 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 暴露三个端点traefik/8080Traefik 管理 Dashboard始终是第一个 URLweb/80标准 HTTP 流量的入口websecure/443HTTPS 安全流量的入口。注意web/80与websecure/443返回的 URL 并非必需。Traefik 通过hostPort直接绑定节点的 80/443 端口因此可以直接用 minikube IP 访问应用例如http://$(minikube ip)。只打印 Dashboard URLminikube service traefik -n kube-system --url | head -n 1示例输出http://192.168.64.3:31918实战部署应用并通过 Ingress 暴露服务下面以一个 echo server 为例演示标准 Kubernetes Ingress 资源如何被 Traefik 消费。Step 1部署应用创建示例命名空间并部署一个简单的 echo servercat 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 outStep 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.isDefaultClasstrue详见下文迁移一节。Step 3测试 IngressTraefik 通过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.1Path 路由测试访问/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.1HTTPS 访问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 中的路由与服务打开 Dashboardminikube addons open traefikHTTP RoutersTraefik 会自动为应用创建两个 HTTP Router一个对应 host 路由规则traefik.example一个对应 path 路由规则/app。HTTP Services流量最终被路由到traefik-example命名空间中的 Kubernetes Serviceapp。Step 5配置自定义 TLS 证书可选默认自签名证书会导致浏览器安全告警。如需在本地开发中使用受信任证书可借助 mkcert 为域名签发证书安装并初始化本地 CAmkcert -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.pemmacOS~/Library/Application Support/mkcert/rootCA-key.pemWindows%LocalAppData%\mkcert\rootCA-key.pem若该私钥泄露攻击者可签发任意域名的可信证书从而实施针对本机的中间人MITM攻击。生成证书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 创建 Secretkubectl create secret tls app-tls -n traefik-example \ --certtraefik.example.pem --keytraefik.example-key.pem示例输出secret/app-tls created更新 Ingress为 Ingress 打补丁加入tls配置kubectl patch ingress app -n traefik-example --typemerge \ -p {spec:{tls:[{hosts:[traefik.example],secretName:app-tls}]}}示例输出ingress.networking.k8s.io/app patched配置 DNS将主机名映射到 minikube IPecho $(minikube ip) traefik.example | sudo tee -a /etc/hosts完成后即可在浏览器直接访问https://traefik.example证书完全受信任。Step 6清理示例删除示例命名空间即可移除应用及其关联资源kubectl delete namespace traefik-example从 ingressnginxaddon 迁移警告默认的ingressnginxaddon 已不再维护minikube 推荐改用traefikaddon。注意ingress与traefik两个 addon不能同时启用因为两者都绑定 80/443 端口。启用traefik前必须先禁用ingressminikube addons disable ingress minikube addons enable traefik若已有应用从 nginx addon 迁移到 traefik addon需要处理两处差异更新 IngressClass如果现有 Ingress 显式声明了ingressClassName: nginx请改为ingressClassName: traefik或直接删除该字段。省略该字段时Traefik 会自动接管该 Ingress因为 traefik addon 将自身注册为默认 IngressClassingressClass.isDefaultClasstrue。替换 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 Addonminikube 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/nametraefik示例输出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/nametraefik示例输出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其验证逻辑与本文实战步骤一致启动带--memory3072的 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.goaddon 注册、验证标签与启用提示的源码实现pkg/addons/helm.go 与 pkg/addons/helm_test.gohelm 安装/卸载命令的底层构造与测试断言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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考