2. Ingress资源定义：Ingress API版本、YAML结构、annotations、rules、tls字段详解

Ingress 是 Kubernetes 中管理集群外部访问集群内服务的 API 对象，通常提供 HTTP 和 HTTPS 路由。理解 Ingress 的资源定义是构建流量入口模型的基础。本节将系统拆解 Ingress 的 API 版本演进、核心 YAML 骨架、关键注解、路由规则以及 TLS 配置。

2.1 API 版本演进与选择

Kubernetes Ingress API 经历了从 extensions/v1beta1 到 networking.k8s.io/v1 的演进。生产环境应始终使用稳定版本。

2.2 YAML 结构骨架

一个完整的 Ingress 资源定义包含四个主要部分：元数据、注解、路由规则 和 TLS 配置。以下是最小化但完整的 YAML 结构：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  tls:
  - hosts:
      - myapp.example.com
    secretName: myapp-tls-secret
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 8080
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-service
            port:
              number: 80

2.3 annotations：控制 Ingress Controller 行为

Annotations 是 Ingress 的“配置开关”，不同 Ingress Controller 支持的注解不同。以下以 nginx-ingress 为例，列出最常用的注解类别：

2.4 rules：路由规则详解

rules 字段定义了流量如何从外部到达后端 Service。每个规则包含一个可选的 host 和一个 http 路径列表。

2.4.1 pathType 三种模式

2.4.2 多主机与通配符

Ingress 支持在同一个资源中定义多个主机名，也支持通配符域名：

rules:
- host: app.example.com
  http:
    paths:
    - path: /
      pathType: Prefix
      backend:
        service:
          name: app-service
          port:
            number: 80
- host: api.example.com
  http:
    paths:
    - path: /
      pathType: Prefix
      backend:
        service:
          name: api-service
          port:
            number: 8080
- host: "*.dev.example.com"
  http:
    paths:
    - path: /
      pathType: Prefix
      backend:
        service:
          name: dev-service
          port:
            number: 3000

2.5 tls：HTTPS 配置

tls 字段用于将 TLS 证书绑定到指定的主机名。证书以 Kubernetes Secret 形式存储，类型必须为 kubernetes.io/tls。

2.5.1 TLS Secret 结构

apiVersion: v1
kind: Secret
metadata:
  name: myapp-tls-secret
  namespace: production
type: kubernetes.io/tls
data:
  tls.crt: <base64 编码的证书文件>
  tls.key: <base64 编码的私钥文件>

2.5.2 多证书与默认证书

Ingress 支持为不同主机配置不同证书：

spec:
  tls:
  - hosts:
      - app.example.com
    secretName: app-tls
  - hosts:
      - api.example.com
    secretName: api-tls
  - hosts:
      - "*.wildcard.example.com"
    secretName: wildcard-tls

2.6 Ingress 资源模型架构图

下图展示了 Ingress 资源定义中各字段与外部流量、后端 Service 之间的映射关系：

2.7 完整配置示例：生产级 Ingress

以下是一个综合了 annotations、多规则、TLS 的生产级 Ingress 配置：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: production-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/limit-rps: "100"
    nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8, 172.16.0.0/12"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://frontend.example.com"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
      - api.example.com
    secretName: api-tls
  - hosts:
      - app.example.com
    secretName: app-tls
  rules:
  - 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
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 80