从Nginx ConfigMap到Higress路由：一个‘Hello World’服务在K8s里的完整流量旅程
从Nginx ConfigMap到Higress路由：一个‘Hello World’服务在K8s里的完整流量旅程
当你在浏览器中输入192.168.21.223:1105并按下回车时，背后发生了什么？这个简单的HTTP请求如何在Kubernetes集群中穿越层层组件，最终从Nginx Pod返回那个熟悉的"Hello World"？让我们跟随这个请求的脚步，揭开云原生网关Higress路由配置的神秘面纱。
1. 请求的起点：Higress Gateway入口
想象你是一名邮递员，正站在Higress Gateway的大门前。这个大门由Kubernetes的NodePort服务开放，地址是192.168.21.223:1105。当你（客户端）发送请求时：
- 网络层拦截：请求首先到达集群节点的1105端口
- Service路由：Kubernetes的kube-proxy将这个端口映射到Higress Gateway Pod的实际端口
- Ingress Controller接收：Higress的Ingress Controller组件监听到这个请求
提示：在本地测试环境中，我们通常使用NodePort暴露服务，生产环境则更推荐LoadBalancer或Ingress Controller
此时，Higress Gateway就像机场的安检通道，它需要决定：
- 这个请求是否被允许进入？
- 应该将它转发到哪个后端服务？
2. 路由匹配：寻找正确的目的地
Higress的路由规则就像机场的航班信息显示屏。在我们的例子中，路由配置非常简单：
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: demo-nginx-ingress spec: ingressClassName: higress rules: - host: "" http: paths: - pathType: Prefix path: "/" backend: service: name: demo-nginx-svc port: number: 8080这段配置告诉Higress：
- 匹配所有Host头（
host: ""） - 匹配所有路径（
path: "/"） - 将流量转发到
demo-nginx-svc服务的8080端口
路由决策过程：
| 检查项 | 配置值 | 实际请求值 | 是否匹配 |
|---|---|---|---|
| Host头 | 空(任意) | 无/任意 | 是 |
| 路径 | / | / | 是 |
| 路径类型 | Prefix | - | - |
3. 后端服务：从Service到Pod
请求通过路由检查后，现在需要找到真正的处理者。Kubernetes的Service系统就像机场的行李转运带：
- Service发现：Higress查询Kubernetes API，找到名为
demo-nginx-svc的Service - Endpoint选择：Service通过标签选择器找到对应的Pod
- 负载均衡：如果有多个Pod，Service会选择一个合适的（本例只有1个Pod）
我们的demo-nginx-svc配置如下：
apiVersion: v1 kind: Service metadata: name: demo-nginx-svc spec: ports: - port: 8080 targetPort: 8080 selector: app: demo-nginx关键点：
targetPort: 8080必须与Pod中容器暴露的端口一致selector确保流量只会转发到带有app: demo-nginx标签的Pod
4. Nginx Pod：请求的最终目的地
现在请求到达了目的地——运行Nginx的Pod。这个Pod的特殊之处在于它的配置完全来自ConfigMap：
apiVersion: v1 kind: ConfigMap metadata: name: demo-nginx-configmap data: nginx.conf: | server { listen 8080; location / { default_type application/json; return 200 '{"status":"success","result":"nginx json"}'; } }ConfigMap如何挂载到Pod：
- Deployment中定义了volume来自ConfigMap：
volumes: - name: nginx-config configMap: name: demo-nginx-configmap - 容器挂载这个volume到
/etc/nginx/nginx.conf：volumeMounts: - name: nginx-config mountPath: /etc/nginx/nginx.conf subPath: nginx.conf
当请求到达Nginx时：
- 监听8080端口的server块接收请求
- 匹配
location /规则 - 返回预定义的JSON响应
5. 日志与可观测性：追踪请求全过程
一个完整的流量旅程离不开日志记录。我们的Nginx配置了详细的JSON格式日志：
log_format logsjson '{ "@timestamp":"$time_iso8601", "client_ip":"$remote_addr", "request_method":"$request_method", "request_uri":"$request_uri", "status":"$status" }'; access_log /var/log/nginx/access.log logsjson;关键日志字段解析：
| 字段 | 说明 | 示例值 |
|---|---|---|
| @timestamp | 请求时间 | 2023-07-20T15:04:05+08:00 |
| client_ip | 客户端IP | 192.168.1.100 |
| request_method | HTTP方法 | GET |
| request_uri | 请求路径 | /api/test |
| status | HTTP状态码 | 200 |
6. 两种路由配置方式对比
Higress提供了灵活的路由配置方式，满足不同用户需求：
方式一：Ingress CRD（YAML声明式）
优点：
- 适合GitOps工作流
- 方便版本控制
- 易于批量修改
典型使用场景：
- 基础设施即代码(IaC)环境
- CI/CD流水线中自动部署
方式二：Higress Console（图形界面）
优点：
- 操作直观，无需编写YAML
- 实时生效，无需kubectl apply
- 适合快速测试和调试
操作步骤：
- 访问Higress Console（通常通过NodePort 39474）
- 导航到路由管理页面
- 填写路由规则表单
- 保存并立即生效
7. 常见问题排查指南
当"Hello World"没有如期而至时，可以按照以下步骤排查：
检查Higress Gateway是否就绪
kubectl get pods -n higress-system确保所有Pod状态为Running
验证路由规则是否正确应用
kubectl get ingress kubectl describe ingress demo-nginx-ingress检查后端服务是否可达
# 获取Pod IP kubectl get pods -o wide # 从集群内测试访问 kubectl run -it --rm debug --image=curlimages/curl -- sh curl http://<pod-ip>:8080查看Nginx日志
kubectl logs <nginx-pod-name>
典型错误案例：
返回502 Bad Gateway：
- 检查Service的selector是否匹配Pod标签
- 验证targetPort与容器端口是否一致
返回404 Not Found：
- 检查Ingress的path配置
- 确认Nginx的location规则
8. 进阶配置建议
当你熟悉了基础路由后，可以尝试这些增强配置：
多路径路由：
paths: - path: /api backend: service: api-service - path: /static backend: service: static-service基于Host的路由：
rules: - host: "app.example.com" http: paths: - path: / backend: service: app-service流量镜像（用于测试新版本）：
metadata: annotations: higress.io/canary: "true" higress.io/canary-weight: "10"在实际项目中，我们通常会结合监控系统（如Prometheus）来观察路由流量，确保每个请求都能找到回家的路。