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-config

Ingress 资源定义

基于 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: 80

pathType 类型说明：

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: 80

Nginx 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/123

Traefik 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:
      - /api

Gateway 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: production

Ingress 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。

贡献者

withesse

更新日志

2026/3/14 13:09

查看所有更新日志

9f6c2-feat: organize wiki content and refresh site setup于 2026/3/14