minikube 启用 Kong Ingress Controller 插件：从 addon 部署到 Ingress 路由实战

minikube 启用 Kong Ingress Controller 插件：从 addon 部署到 Ingress 路由实战

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

本文以 minikube 的kongaddon 为线索，完整演示如何在本地 Kubernetes 环境中启用 Kong Ingress Controller（KIC）、通过 Service 暴露 Kong 代理入口、部署上游应用并创建 Ingress 路由规则，最终实现从宿主机到 Pod 的端到端 HTTP 转发。读完本文，你将掌握minikube addons enable kong的完整操作链路、KIC 在 minikube 中的组件构成（Proxy + Controller + 各类 Kong CRD），以及用curl验证路由是否生效的排查方法。

前置准备：启动 minikube 集群

KIC 运行在 minikube 集群内部，因此第一步是启动集群并确认节点就绪。执行：

minikube start

首次启动需要拉取镜像并预置组件，通常需要几分钟。启动完成后，用以下命令确认节点处于Ready状态：

kubectl get nodes

输出中应能看到类似minikube名称的节点，STATUS列为Ready。只有集群健康，后续 addon 资源（Namespace、CRD、RBAC、Deployment、Service）才能顺利创建。

部署 Kong Ingress Controller

minikube 将 Kong Ingress Controller 打包为名为kong的内置 addon，一条命令即可完成部署：

$ minikube addons enable kong 🌟 The 'kong' addon is enabled

注意：首次启用时，需要拉取 Kong 与 KIC 的容器镜像并创建全部依赖资源，整个过程最长可能耗时五分钟。

从 addon 注册表（pkg/minikube/assets/addons.go）可以看到，kongaddon 由 Kong 官方（Kong HQ）维护，对应的命令配置项定义在 pkg/addons/config.go 中（name: "kong"，启用回调为EnableOrDisableAddon）。addon 实际安装的镜像由注册表固定并校验摘要：

• kong:3（Kong Gateway 代理本体）
• kong/kubernetes-ingress-controller:3.5.13（KIC 控制器）

启用后，可以通过minikube addons list查看kong的状态；需要关闭时使用minikube addons disable kong（对应命令实现位于 cmd/minikube/cmd/config/disable.go）。

addon 部署了哪些资源

minikube addons enable kong执行的模板位于 deploy/addons/kong/kong-ingress-controller.yaml.tmpl，一次安装包含以下组件：

• Namespacekong：所有 KIC 相关资源都部署在独立的kong命名空间中，与用户应用隔离。
• 7 个 Kong CRD（configuration.konghq.comAPI 组）：
  • IngressClassParameters（v1alpha1）
  • KongClusterPlugin（短名kcp，集群级插件）
  • KongConsumer（短名kc）
  • KongIngress（短名ki，用于精细控制代理行为）
  • KongPlugin（短名kp，命名空间级插件）
  • TCPIngress（v1beta1，TCP 四层路由）
  • UDPIngress（v1beta1，UDP 路由）
• RBAC 权限：kong-serviceaccount服务账户，配合kong-ingress、kong-ingress-gateway（Gateway API）、kong-ingress-knative三个 ClusterRole 及对应绑定，控制器据此监听 Ingress、Service、Endpoint 以及 Kong CRD。
• 3 个 Service：
  • kong-proxy：LoadBalancer类型，入口80:8000、443:8443，即 KIC 对外流量入口；
  • kong-admin：ClusterIP: None（Headless），暴露 Kong Admin API（8444），供控制器同步配置；
  • kong-validation-webhook：提供 Admission Webhook（443→8080），用于校验 Ingress 等资源的合法性。
• 2 个 Deployment：
  • ingress-kong：控制器本体，通过环境变量CONTROLLER_KONG_ADMIN_SVC=kong/kong-admin与CONTROLLER_PUBLISH_SERVICE=kong/kong-proxy与 Kong 网关通信；
  • proxy-kong：Kong Gateway 数据面，以 DB-less（KONG_DATABASE=off）声明式模式运行，监听0.0.0.0:8000（HTTP）与0.0.0.0:8443（HTTPS），通过KONG_PORT_MAPS: 80:8000, 443:8443完成端口映射，路由引擎为traditional。
• IngressClasskong：声明控制器标识为ingress-controllers.konghq.com/kong，Ingress 对象通过ingressClassName: kong与 KIC 绑定。

设置环境变量：获取 Kong 代理入口地址

addon 启用后，需要拿到 Kong 对外可访问的地址，用它向集群内发送请求。minikube 提供了便捷命令：

$ export PROXY_IP=$(minikube service -n kong kong-proxy --url | head -1) $ echo $PROXY_IP http://192.168.99.100:32728

minikube service -n kong kong-proxy --url会查询kong命名空间下kong-proxy这个 LoadBalancer Service 的对外 URL；head -1取第一行（HTTP 入口），得到形如http://<节点IP>:<映射端口>的地址并存入PROXY_IP。实际 IP 与端口取决于你的驱动与端口分配，示例中的192.168.99.100:32728仅为示意。

如果使用 Docker、HyperKit 等驱动，也可改用minikube tunnel为 LoadBalancer Service 分配本地回环地址：

# 另开一个终端窗口运行 minikube tunnel # 由于需要占用本机 80/443 端口，可能要求输入管理员密码

minikube tunnel运行期间，kong-proxy会被映射到localhost的 80/443 端口（这也是示例中直接用curl localhost即可访问的原因）。

验证 KIC 是否就绪

配置好入口后，先用一次 HTTP 请求确认 Kong 网关本身已经响应。由于此时还没有任何路由规则，Kong 会返回 404，这恰恰说明代理链路已经打通：

$ curl -v localhost * Trying 127.0.0.1:80... * Connected to localhost (127.0.0.1) port 80 (#0) > GET / HTTP/1.1 > Host: localhost > User-Agent: curl/7.86.0 > Accept: */* > * Mark bundle as not supporting multiuse < HTTP/1.1 404 Not Found < Date: Wed, 03 May 2023 01:34:31 GMT < Content-Type: application/json; charset=utf-8 < Connection: keep-alive < Content-Length: 48 < X-Kong-Response-Latency: 0 < Server: kong/3.2.2 < * Connection #0 to host localhost left intact {"message":"no Route matched with those values"}%

响应头中的Server: kong/3.2.2与X-Kong-Response-Latency表明请求确实经过了 Kong；{"message":"no Route matched with those values"}是预期行为——还没有任何 Ingress 与之匹配。

创建 Ingress 对象：部署上游应用

要让 Kong 代理请求，必须先有一个上游应用。这里部署一个 echo 服务器，它会返回请求落在哪个 Pod 以及 Pod 的相关信息，非常适合验证路由链路。执行：

echo " apiVersion: v1 kind: Service metadata: labels: app: echo name: echo spec: ports: - port: 1025 name: tcp protocol: TCP targetPort: 1025 - port: 1026 name: udp protocol: TCP targetPort: 1026 - port: 1027 name: http protocol: TCP targetPort: 1027 selector: app: echo --- apiVersion: apps/v1 kind: Deployment metadata: labels: app: echo name: echo spec: replicas: 1 selector: matchLabels: app: echo strategy: {} template: metadata: creationTimestamp: null labels: app: echo spec: containers: - image: kong/go-echo:latest name: echo ports: - containerPort: 1027 env: - name: NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: POD_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: POD_IP valueFrom: fieldRef: fieldPath: status.podIP resources: {} " | kubectl apply -f -

清单包含两部分：

• Serviceecho：将app: echo标签的 Pod 聚合为服务，暴露1025（TCP）、1026（UDP）、1027（HTTP）三个端口；其中1027是接下来 Ingress 路由的目标端口。
• Deploymentecho：基于kong/go-echo:latest镜像运行单个副本，容器监听1027端口，并通过fieldRef注入NODE_NAME、POD_NAME、POD_NAMESPACE、POD_IP四个环境变量，echo 响应内容即来自这些变量。

配置 Ingress 路由规则

接下来创建 Ingress，把/echo路径的请求转发到上面的 echo Service：

echo " apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: echo annotations: konghq.com/strip-path: 'true' spec: ingressClassName: kong rules: - host: kong.example http: paths: - path: /echo pathType: ImplementationSpecific backend: service: name: echo port: number: 1027 " | kubectl apply -f -

关键字段说明：

• ingressClassName: kong：与 addon 安装的 IngressClass 同名，KIC 才会接管这条路由。
• host: kong.example：路由匹配的域名，请求时必须携带Host: kong.example头才会命中。
• path: /echo与pathType: ImplementationSpecific：KIC 支持的正则/前缀匹配语义，ImplementationSpecific表示匹配行为由控制器定义。
• konghq.com/strip-path: 'true'：Kong 特有注解，转发时剥离开头的/echo前缀，使上游 echo 服务直接收到/请求。更多类似konghq.com/*注解（如konghq.com/methods、konghq.com/preserve-host）可参阅模板内KongIngressCRD 的 schema 定义（deploy/addons/kong/kong-ingress-controller.yaml.tmpl）。

端到端测试路由

Ingress 生效后，携带虚拟域名发起请求：

$ curl -i localhost/echo -H "Host: kong.example" HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Content-Length: 133 Connection: keep-alive Date: Wed, 03 May 2023 01:59:25 GMT X-Kong-Upstream-Latency: 1 X-Kong-Proxy-Latency: 1 Via: kong/3.2.2 Welcome, you are connected to node minikube. Running on Pod echo-f4fdf987c-qdv7s. In namespace default. With IP address 10.244.0.6.

HTTP/1.1 200 OK表示整条链路已经打通：curl → Kong Proxy (8000/80) → Ingress 规则匹配 → echo Service:1027 → echo Pod。响应正文中的Running on Pod echo-f4fdf987c-qdv7s与With IP address 10.244.0.6正是 echo 容器通过环境变量读到的运行时信息，可用于确认请求实际到达的目标副本。响应头中的X-Kong-Upstream-Latency、X-Kong-Proxy-Latency分别记录了上游耗时与 Kong 自身耗时。

进阶说明与排查建议

• 替换 PROXY_IP 场景：如果不使用minikube tunnel，应把测试命令中的localhost换成$PROXY_IP，例如curl -i $PROXY_IP/echo -H "Host: kong.example"。
• HTTP 与 HTTPS：kong-proxy同时暴露 80/443，若需测试 HTTPS 转发，可在 Ingress 中配置tls段并创建对应 Secret。
• 四层（TCP/UDP）路由：模板中内置了TCPIngress与UDPIngress两个 CRD，适用于需要按端口转发非 HTTP 流量的场景；从源码结构看，KIC 会监听configuration.konghq.com组下的全部 CRD（见模板中的kong-ingressClusterRole 规则）。
• 故障定位顺序：先用kubectl get pods -n kong确认proxy-kong与ingress-kong均处于Running；再用kubectl get ingress echo查看是否被 KIC 接受；最后回到curl验证 Host 头与路径是否与 Ingress 规则一致。
• Webhook 校验：kong-validation-webhook会对 Ingress 等资源做准入校验，若配置有误会在kubectl apply阶段直接报错，是排查书写错误的第一道防线。
• 更多用法：Kong 的插件体系（限流、认证等）可通过KongPlugin/KongClusterPluginCRD 接入，相关字段（plugin、config、protocols、ordering等）均可在仓库模板的 CRD schema 中查阅，本文不再展开。

小结

在 minikube 上启用 Kong Ingress Controller 只需要三步：minikube start启动集群 →minikube addons enable kong安装 KIC → 部署应用并创建ingressClassName: kong的 Ingress 对象。addon 内部由 Kong Gateway（DB-less 数据面）与 KIC 控制器协同工作，所有清单集中在 deploy/addons/kong/kong-ingress-controller.yaml.tmpl，镜像与维护信息见 pkg/minikube/assets/addons.go，addon 命令的注册与校验逻辑见 pkg/addons/config.go。掌握这套链路后，你可以直接在本地复现基于 Kong 的流量治理、插件扩展与七层/四层路由实验。

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