Ingress & IngressClass 深度解析

Ingress 的作用

Ingress 是 HTTP/HTTPS 流量的 L7 路由规则，将外部请求路由到集群内的 Service：

外部请求
    │
    ▼
Ingress Controller（Nginx/Traefik/HAProxy）
    │ 根据 Host/Path 路由
    ├── /api/* → api-service:8080
    ├── /web/* → web-service:3000
    └── blog.example.com → blog-service:80

基础配置

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
  ingressClassName: nginx  # 指定 IngressClass

  # TLS 配置
  tls:
  - hosts:
    - api.example.com
    - www.example.com
    secretName: example-tls  # TLS 证书 Secret

  rules:
  # 基于 Host 路由
  - host: api.example.com
    http:
      paths:
      - path: /v1
        pathType: Prefix
        backend:
          service:
            name: api-v1-service
            port:
              number: 8080
      - path: /v2
        pathType: Prefix
        backend:
          service:
            name: api-v2-service
            port:
              number: 8080

  # 基于 Path 路由
  - host: www.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 3000
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 8080

PathType 说明

PathType	说明	示例
Exact	精确匹配	/foo 只匹配 /foo
Prefix	前缀匹配	/foo 匹配 /foo、/foo/bar
ImplementationSpecific	由 IngressClass 决定	-

IngressClass

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"  # 设为默认
spec:
  controller: k8s.io/ingress-nginx

Nginx Ingress 常用注解

annotations:
  # 限流
  nginx.ingress.kubernetes.io/limit-rps: "100"
  nginx.ingress.kubernetes.io/limit-connections: "10"

  # 超时
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "60"

  # 认证
  nginx.ingress.kubernetes.io/auth-type: basic
  nginx.ingress.kubernetes.io/auth-secret: basic-auth
  nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"

  # CORS
  nginx.ingress.kubernetes.io/enable-cors: "true"
  nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"

  # 白名单
  nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8,192.168.0.0/16"

  # 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"  # 20% 流量到金丝雀

cert-manager 自动 TLS

# 安装 cert-manager 后，自动申请 Let's Encrypt 证书
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - api.example.com
    secretName: api-tls  # cert-manager 自动创建并更新
  rules:
  - host: api.example.com
    ...

常用操作

# 查看 Ingress
kubectl get ingress
kubectl describe ingress my-ingress

# 查看 Nginx Ingress Controller 日志
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller

# 测试路由
curl -H "Host: api.example.com" http://<node-ip>:<nodeport>/v1/users