K8s Ingress实战：从零配置Nginx Ingress Controller，实现基于路径和域名的灵活路由

K8s Ingress实战：从零配置Nginx Ingress Controller，实现基于路径和域名的灵活路由

当你的Kubernetes集群需要对外暴露多个Web服务时，直接使用LoadBalancer或NodePort会面临端口管理混乱、SSL终止繁琐等问题。这时，Ingress就像一位智能交通指挥员，它能根据HTTP请求的路径或域名，将流量精准路由到不同的后端服务。本文将带你从零开始，手把手搭建Nginx Ingress Controller，并通过实际案例演示如何实现灵活的路由规则。

1. 理解Ingress的核心组件

在Kubernetes中，Ingress并不是一个独立的服务，而是一套由多个组件协作的解决方案。要正确使用Ingress，首先需要理清三个核心概念：

• Ingress资源：定义路由规则的K8s对象，相当于"交通规则手册"
• Ingress Controller：实际执行路由的代理服务，相当于"交通警察"
• 后端服务(Service)：最终处理请求的应用，相当于"目的地"

常见误区：很多初学者会混淆Ingress资源与Ingress Controller。前者只是声明式的规则定义，后者才是真正处理流量的实体。这就好比交通规则手册本身不会指挥交通，需要交警来具体执行。

目前主流的Ingress Controller实现包括：

• Nginx Ingress Controller（官方维护）
• Traefik
• HAProxy Ingress
• Istio Ingress Gateway

我们选择Nginx版本，因为它：

1. 由Kubernetes社区官方维护
2. 功能全面且稳定
3. 有丰富的注解(Annotation)支持高级配置

2. 部署Nginx Ingress Controller

2.1 快速安装方案

对于大多数生产环境，推荐使用Helm进行安装：

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm install ingress-nginx ingress-nginx/ingress-nginx \ --namespace ingress-nginx \ --create-namespace \ --set controller.service.type=LoadBalancer

如果集群没有LoadBalancer支持（如本地测试环境），可以改用NodePort：

helm install ingress-nginx ingress-nginx/ingress-nginx \ --namespace ingress-nginx \ --create-namespace \ --set controller.service.type=NodePort \ --set controller.service.nodePorts.http=30080 \ --set controller.service.nodePorts.https=30443

2.2 验证安装

检查Pod状态：

kubectl get pods -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

预期输出应显示READY状态为1/1。

获取外部访问地址：

kubectl get svc -n ingress-nginx

如果是云环境，EXTERNAL-IP列会显示负载均衡器的地址；本地环境则使用任意节点IP加NodePort端口。

2.3 重要配置参数

安装时可通过--set调整的关键参数：

提示：生产环境建议配置资源请求/限制，如--set controller.resources.requests.cpu=500m

3. 配置Ingress路由规则

3.1 基础路径路由

假设我们有两个服务：

• frontend：处理/web路径的流量
• backend：处理/api路径的流量

对应的Ingress配置如下：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: example-ingress spec: rules: - http: paths: - path: /web pathType: Prefix backend: service: name: frontend port: number: 80 - path: /api pathType: Prefix backend: service: name: backend port: number: 80

关键字段说明：

• pathType：支持Exact(精确匹配)、Prefix(前缀匹配)和ImplementationSpecific
• backend：指定目标Service及其端口

3.2 基于域名的虚拟主机

如果需要支持多个域名，可以这样配置：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: multi-host-ingress spec: rules: - host: shop.example.com http: paths: - path: / pathType: Prefix backend: service: name: shop port: number: 80 - host: blog.example.com http: paths: - path: / pathType: Prefix backend: service: name: blog port: number: 80

3.3 路径重写实战案例

当后端服务的URL路径与Ingress路径不一致时，需要使用重写功能。例如，将/app请求转发到后端的/路径：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: rewrite-example annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 spec: rules: - http: paths: - path: /app(/|$)(.*) pathType: Prefix backend: service: name: my-app port: number: 80

这个配置会：

1. 匹配以/app开头的请求
2. 将请求路径中的/app替换为/
3. $2表示捕获的第二个分组(.*)

4. 高级配置与优化

4.1 常用注解(Annotations)

Nginx Ingress提供了丰富的注解来实现高级功能：

配置片段示例：

annotations: nginx.ingress.kubernetes.io/configuration-snippet: | if ($host = 'example.com') { return 301 https://www.example.com$request_uri; }

4.2 流量切分与金丝雀发布

通过注解可以实现按权重的流量分配：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: canary-demo annotations: nginx.ingress.kubernetes.io/canary: "true" nginx.ingress.kubernetes.io/canary-weight: "30" spec: rules: - http: paths: - path: / pathType: Prefix backend: service: name: new-version port: number: 80

这会将30%的流量路由到new-version服务，剩余70%走默认Ingress规则。

4.3 性能优化实践

对于高流量场景，建议调整以下参数：

controller: config: # 每个worker进程保持的最大连接数 worker-connections: "10000" # 启用长连接 keep-alive: "75" # 缓冲区大小 proxy-buffer-size: "16k" # 最大请求体大小 proxy-body-size: "20m" resources: limits: cpu: "2" memory: "2Gi" requests: cpu: "1" memory: "1Gi"

5. 常见问题排查指南

5.1 诊断工具与命令

查看Ingress事件：

kubectl describe ingress <ingress-name>

检查Nginx配置：

kubectl exec -n ingress-nginx <ingress-pod> -- cat /etc/nginx/nginx.conf

实时日志监控：

kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx --tail=100 -f

5.2 典型问题解决方案

问题1：404错误但后端服务正常

• 检查Ingress的pathType是否匹配预期
• 验证后端服务的健康检查路径是否正确

问题2：SSL证书不生效

• 确保证书Secret与Ingress在同一命名空间
• 检查证书是否过期
• 验证Ingress的tls字段配置正确

问题3：上传大文件失败

• 增加proxy-body-size注解值
• 调整client_max_body_size配置

问题4：WebSocket连接断开

• 添加以下注解：

  annotations: nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" nginx.ingress.kubernetes.io/websocket-services: "my-websocket-svc"

5.3 监控与告警配置

建议为Ingress Controller配置以下监控指标：

• 请求率(nginx_ingress_controller_requests)
• 响应时间(nginx_ingress_controller_response_duration_seconds)
• 错误率(nginx_ingress_controller_requests)

示例Prometheus告警规则：

- alert: HighErrorRate expr: rate(nginx_ingress_controller_requests{status=~"5.."}[1m]) / rate(nginx_ingress_controller_requests[1m]) > 0.05 for: 5m labels: severity: critical annotations: summary: "High error rate on {{ $labels.ingress }}" description: "5xx error rate is {{ printf \"%.2f\" $value }}%"

在实际项目中，我发现最常遇到的问题往往是路径匹配规则配置不当。例如，忘记设置pathType导致路径匹配不符合预期，或者重写规则写错导致后端收到错误的URL。建议在测试环境充分验证路由规则后再部署到生产环境。