Kubernetes Ingress控制器
约 1209 字大约 4 分钟
kubernetesingress
2025-06-11
Ingress 是 Kubernetes 中管理外部 HTTP/HTTPS 流量路由到集群内 Service 的资源。Ingress Controller 是实际执行路由规则的组件。本文将详解 Ingress 资源定义、主流控制器实现以及与新一代 Gateway API 的对比。
架构概览
IngressClass
IngressClass 指定使用哪个 Ingress Controller 来处理 Ingress 资源。集群中可以同时存在多个 Controller:
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: nginx
annotations:
ingressclass.kubernetes.io/is-default-class: "true" # 标记为默认
spec:
controller: k8s.io/ingress-nginx
parameters:
apiGroup: k8s.example.net
kind: IngressParameters
name: nginx-configIngress 资源定义
基于 Host 的路由
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: multi-host-ingress
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
spec:
ingressClassName: nginx
tls:
- hosts:
- api.example.com
- web.example.com
secretName: example-tls-secret
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: api-service
port:
number: 80
- host: web.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-service
port:
number: 80基于 Path 的路由
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: path-based-ingress
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api-service
port:
number: 80
- path: /api/v2
pathType: Prefix # 更长的路径优先匹配
backend:
service:
name: api-v2-service
port:
number: 80
- path: /exact-match
pathType: Exact # 精确匹配
backend:
service:
name: exact-service
port:
number: 80
- path: /
pathType: Prefix # 兜底规则
backend:
service:
name: frontend-service
port:
number: 80pathType 类型说明:
- Exact:精确匹配路径,区分尾部
/ - Prefix:前缀匹配,按
/分隔的路径元素匹配 - ImplementationSpecific:匹配规则由 IngressClass 决定
TLS 终止
# 创建 TLS Secret
# kubectl create secret tls example-tls-secret \
# --cert=tls.crt --key=tls.key -n default
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: tls-ingress
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.3"
spec:
ingressClassName: nginx
tls:
- hosts:
- secure.example.com
secretName: example-tls-secret
rules:
- host: secure.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: secure-app
port:
number: 80配合 cert-manager 自动管理证书:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: auto-tls-ingress
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
ingressClassName: nginx
tls:
- hosts:
- app.example.com
secretName: app-tls-auto # cert-manager 自动创建此 Secret
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app
port:
number: 80Nginx Ingress Controller
Nginx Ingress Controller 是最广泛使用的实现,基于 Nginx 反向代理:
常用注解:
metadata:
annotations:
# 速率限制
nginx.ingress.kubernetes.io/limit-rps: "10"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "5"
# URL 重写
nginx.ingress.kubernetes.io/rewrite-target: /$2
nginx.ingress.kubernetes.io/use-regex: "true"
# CORS
nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"
# 认证
nginx.ingress.kubernetes.io/auth-type: basic
nginx.ingress.kubernetes.io/auth-secret: basic-auth
# WebSocket
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
# 灰度发布
nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-weight: "20"URL 重写示例:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: rewrite-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /$2
nginx.ingress.kubernetes.io/use-regex: "true"
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /api(/|$)(.*)
pathType: ImplementationSpecific
backend:
service:
name: api-service
port:
number: 80
# /api/users -> /users
# /api/orders/123 -> /orders/123Traefik Ingress Controller
Traefik 是另一个流行的 Ingress Controller,特点是自动服务发现和丰富的中间件:
# Traefik IngressRoute (CRD)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: app-route
spec:
entryPoints:
- websecure
routes:
- match: Host(`app.example.com`) && PathPrefix(`/api`)
kind: Rule
services:
- name: api-service
port: 80
middlewares:
- name: rate-limit
- name: strip-prefix
tls:
certResolver: letsencrypt
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: rate-limit
spec:
rateLimit:
average: 100
burst: 50
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: strip-prefix
spec:
stripPrefix:
prefixes:
- /apiGateway API
Gateway API 是 Ingress 的下一代替代方案,提供更强大、更规范化的流量管理能力:
# GatewayClass - 由基础设施提供者管理
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: istio
spec:
controllerName: istio.io/gateway-controller
---
# Gateway - 由集群管理员管理
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: production-gateway
spec:
gatewayClassName: istio
listeners:
- name: https
port: 443
protocol: HTTPS
tls:
mode: Terminate
certificateRefs:
- name: prod-tls-cert
allowedRoutes:
namespaces:
from: Selector
selector:
matchLabels:
gateway-access: "true"
---
# HTTPRoute - 由应用开发者管理
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: app-route
spec:
parentRefs:
- name: production-gateway
hostnames:
- "app.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: api-service
port: 80
weight: 90
- name: api-service-canary
port: 80
weight: 10 # 10% 流量灰度
filters:
- type: RequestHeaderModifier
requestHeaderModifier:
add:
- name: X-Gateway
value: productionIngress vs Gateway API 对比
| 特性 | Ingress | Gateway API |
|---|---|---|
| HTTP 路由 | 支持 | 支持 |
| TCP/UDP 路由 | 不支持 | 支持 |
| 流量分割 | 依赖注解 | 原生支持 |
| Header 修改 | 依赖注解 | 原生支持 |
| 角色分离 | 无 | GatewayClass/Gateway/Route |
| 跨命名空间 | 不支持 | 支持 |
| 可移植性 | 注解不通用 | 标准化 API |
总结
Ingress 仍然是大多数场景下的可靠选择,Nginx Ingress Controller 生态成熟、文档丰富。对于需要更高级流量管理能力(如流量分割、TCP/UDP 路由、跨命名空间引用)的场景,建议采用 Gateway API。在迁移路径上,可以先从 Ingress 开始,逐步过渡到 Gateway API。
贡献者
更新日志
2026/3/14 13:09
查看所有更新日志
9f6c2-feat: organize wiki content and refresh site setup于