Kubernetes Ingress

Ingress、Ingress Controller、Gateway API、七层路由和入口流量排查。

Kubernetes Ingress 与 Gateway

Ingress 用于管理集群外部访问集群内 Service 的七层 HTTP / HTTPS 规则。Ingress 资源本身只描述路由规则，真正处理流量的是 Ingress Controller，例如 NGINX Ingress Controller、Traefik、APISIX、Kong、HAProxy 等。

Kubernetes 官方已经推荐新场景优先评估 Gateway API。Ingress 仍然是稳定 API，但功能不再继续扩展；Gateway API 更适合多团队、复杂路由和角色分离的入口治理。

Kubernetes Ingress 入口流量链路

入口链路

典型访问链路：

client
  -> load balancer / node port
  -> ingress controller
  -> ingress rule
  -> service
  -> endpointslice
  -> pod

排查入口问题时，也建议按这个顺序逐层确认。

Ingress Controller

Ingress 生效前必须先安装 Ingress Controller。

kubectl get pods -A | grep -i ingress
kubectl get ingressclass

常见控制器：

控制器	说明
NGINX Ingress Controller	使用广泛，配置成熟
Traefik	动态配置能力强，适合边缘入口
APISIX Ingress	API 网关能力较强
Kong Ingress	API 管理、鉴权、插件生态
HAProxy Ingress	基于 HAProxy 的入口控制

IngressClass

多个 Ingress Controller 共存时，需要用 IngressClass 指定由哪个控制器处理。

# API 版本。IngressClass 使用 networking.k8s.io/v1。
apiVersion: networking.k8s.io/v1
# 资源类型。这里表示创建 IngressClass。
kind: IngressClass
metadata:
  # IngressClass 名称，Ingress 通过 ingressClassName 引用。
  name: nginx
spec:
  # 控制器标识，表示由哪个 Ingress Controller 实现。
  controller: k8s.io/ingress-nginx

Ingress 中引用：

spec:
  # 指定处理该 Ingress 的 IngressClass。
  ingressClassName: nginx

基础 Ingress

# API 版本。Ingress 使用 networking.k8s.io/v1。
apiVersion: networking.k8s.io/v1
# 资源类型。这里表示创建 Ingress。
kind: Ingress
metadata:
  # Ingress 名称。
  name: order-api
  # Ingress 所属命名空间。
  namespace: default
spec:
  # 指定处理该 Ingress 的控制器类别。
  ingressClassName: nginx
  # HTTP 路由规则列表。
  rules:
    # 访问域名。
    - host: order.example.com
      http:
        # 路径规则列表。
        paths:
          # 匹配根路径。
          - path: /
            # Prefix 表示前缀匹配。
            pathType: Prefix
            # 后端服务。
            backend:
              service:
                # 后端 Service 名称。
                name: order-api
                port:
                  # 后端 Service 端口。
                  number: 80

字段说明：

字段	说明
`ingressClassName`	指定处理该 Ingress 的控制器
`rules.host`	访问域名
`paths.path`	匹配路径
`pathType`	路径匹配方式，常用 `Prefix`
`backend.service.name`	后端 Service 名称
`backend.service.port.number`	后端 Service 端口

TLS 配置

创建证书 Secret：

kubectl create secret tls order-example-com-tls \
  --cert=tls.crt \
  --key=tls.key \
  -n default

Ingress 引用 TLS：

# API 版本。Ingress 使用 networking.k8s.io/v1。
apiVersion: networking.k8s.io/v1
# 资源类型。这里表示创建 Ingress。
kind: Ingress
metadata:
  name: order-api
  namespace: default
spec:
  ingressClassName: nginx
  # TLS 配置列表。
  tls:
    # 证书覆盖的域名。
    - hosts:
        - order.example.com
      # 保存 TLS 证书和私钥的 Secret 名称。
      secretName: order-example-com-tls
  # HTTP 路由规则列表。
  rules:
    - host: order.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: order-api
                port:
                  number: 80

证书建议：

证书 Secret 和 Ingress 放在同一命名空间。
证书过期时间需要监控。
多域名证书要确认 SAN 是否覆盖。
生产环境建议使用 cert-manager 或统一证书平台管理。

常见注解

不同控制器支持的注解不同，下面以 NGINX Ingress Controller 常见场景为例：

metadata:
  # 控制器特定注解，不同 Ingress Controller 支持的注解不同。
  annotations:
    # 请求体大小上限。
    nginx.ingress.kubernetes.io/proxy-body-size: "20m"
    # 后端响应读取超时时间。
    nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
    # 向后端发送请求的超时时间。
    nginx.ingress.kubernetes.io/proxy-send-timeout: "60"

注解属于控制器扩展能力，迁移控制器时需要重新评估。

Gateway API

Gateway API 将入口流量拆成多个角色对象：

对象	说明
GatewayClass	定义网关类型，由哪个控制器实现
Gateway	网关实例，通常由平台或基础设施团队管理
HTTPRoute	HTTP 路由规则，通常由应用团队管理
GRPCRoute	gRPC 路由规则

HTTPRoute 示例：

# API 版本。HTTPRoute 属于 Gateway API。
apiVersion: gateway.networking.k8s.io/v1
# 资源类型。这里表示创建 HTTPRoute。
kind: HTTPRoute
metadata:
  # HTTPRoute 名称。
  name: order-api
  # HTTPRoute 所属命名空间。
  namespace: default
spec:
  # 绑定到哪个 Gateway。
  parentRefs:
    # Gateway 名称。
    - name: public-gateway
      # Gateway 所在命名空间。
      namespace: gateway-system
  # 路由匹配的域名列表。
  hostnames:
    - order.example.com
  # 路由规则列表。
  rules:
    # 匹配条件。
    - matches:
        - path:
            # PathPrefix 表示路径前缀匹配。
            type: PathPrefix
            # 匹配根路径。
            value: /
      # 后端 Service 引用列表。
      backendRefs:
        # 后端 Service 名称。
        - name: order-api
          # 后端 Service 端口。
          port: 80

Gateway API 更适合复杂路由、流量权重、Header 匹配和多团队协作。

排查命令

kubectl get ingress -A
kubectl describe ingress order-api -n default
kubectl get ingressclass
kubectl get svc,endpointslice -n default
kubectl get pods -n default -l app=order-api -o wide

查看控制器：

kubectl get pods -n ingress-nginx
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=100
kubectl describe svc -n ingress-nginx ingress-nginx-controller

从集群内测试：

kubectl run netshoot --image=nicolaka/netshoot -it --rm -- bash
curl -H "Host: order.example.com" http://<ingress-controller-service-ip>

从集群外测试：

curl -v http://order.example.com
curl -vk https://order.example.com

常见问题

现象	排查方向
Ingress 不生效	检查 Ingress Controller、IngressClass、控制器日志
404	检查 host、path、pathType、后端 Service
502 / 503	检查 Service、EndpointSlice、Pod Ready、targetPort
HTTPS 证书错误	检查 TLS Secret、域名、证书链和过期时间
上传失败	检查控制器 body size 限制
长连接断开	检查 read timeout、send timeout 和负载均衡超时