IngressRoute

IngressRoute 是 Traefik HTTP 路由器的 CRD 实现。

创建 IngressRoute 对象前，需要将 Traefik Kubernetes CRD（例如定义和 RBAC）应用到 Kubernetes 集群。

这会注册 IngressRoute 类型及其他 Traefik 专用资源。

配置示例¶

可以按以下方式声明 IngressRoute：

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test-name
  namespace: apps

spec:
  ingressClassName: traefik-lb
  entryPoints:
    - web
  parentRefs:
    - name: parent-gateway
      namespace: default  # Optional - defaults to same namespace
  routes:
  - kind: Rule
    # Rule on the Host
    match: Host(`test.example.com`)
    # Attach a middleware
    middlewares:
    - name: middleware1
      namespace: apps
    # Enable Router observability
    observability:
      accessLogs: true
      metrics: true
      tracing: true
    # Set a priority
    priority: 10
    services:
    # Target a Kubernetes Support
    - kind: Service
      name: foo
      namespace: apps
      # Customize the connection between Traefik and the backend
      passHostHeader: true
      port: 80
      responseForwarding:
        flushInterval: 1ms
      scheme: https
      sticky:
        cookie:
          httpOnly: true
          name: cookie
          secure: true
      strategy: wrr
      weight: 10
  tls:
    # Generate a TLS certificate using a certificate resolver
    certResolver: foo
    domains:
    - main: example.net
      sans:
      - a.example.net
      - b.example.net
    # Customize the TLS options
    options:
      name: opt
      namespace: apps
    # Add a TLS certificate from a Kubernetes Secret
    secretName: supersecret

配置选项¶

字段	说明	默认值	必填
`ingressClassName`	指定使用的集群级 IngressClass 资源，取代已弃用的 `kubernetes.io/ingress.class` 注解。 spec 字段的优先级高于注解。		否
`entryPoints`	入口点名称列表。未指定时，HTTP 路由器接受默认入口点列表中所有入口点的请求。		否
`parentRefs`	用于多层路由的父 IngressRoute 资源引用列表。指定后，本 IngressRoute 的路由器会成为所引用父 IngressRoute 路由器的子路由器。详见使用 IngressRoute 实现多层路由。		否
`parentRefs[n].name`	所引用的父 IngressRoute 资源名称。		是
`parentRefs[n].namespace`	所引用的父 IngressRoute 资源所在的命名空间。未指定时，默认为子 IngressRoute 所在的命名空间。跨命名空间引用需要启用提供者的 `allowCrossNamespace` 选项。		否
`routes`	路由列表。		是
`routes[n].kind`	路由器匹配类型，目前仅支持 `Rule`。	"Rule"	否
`routes[n].match`	定义底层路由器使用的规则。		是
`routes[n].priority`	定义用于区分相同长度规则的路由匹配优先级。未设置时，优先级直接等于规则长度，因此最长规则的优先级最高。优先级值 `0` 会被忽略，使用默认的规则长度排序。支持负数。	0	否
`routes[n].middlewares`	附加到 IngressRoute 的中间件列表。详见中间件。	""	否
`routes[n].` `middlewares[m].` `name`	中间件名称。不允许使用字符 `@`。详见中间件。		是
`routes[n].` `middlewares[m].` `namespace`	中间件命名空间。中间件与 IngressRoute 位于同一命名空间时可以留空。详见中间件。		否
`routes[n].` `observability.` `accessLogs`	决定路由是否生成访问日志。详见路由可观测性。	false	否
`routes[n].` `observability.` `metrics`	决定路由是否生成指标。详见路由可观测性。	false	否
`routes[n].` `observability.` `tracing`	决定路由是否生成追踪数据。详见路由可观测性。	false	否
`routes[n].` `observability.` `traceVerbosity`	定义此路由的追踪详细程度，有效值为 `minimal` 和 `detailed`。详见路由可观测性。	minimal	否
`tls`	TLS 配置。允许使用空值（`{}`）：此时会生成自签名证书（如果定义了默认证书，则使用该证书）。		否
`routes[n].` `services`	由 TraefikService 和 Kubernetes 服务任意组合构成的列表。完整选项见 `Service` 文档。		否
`tls.secretName`	用于存储证书的 Secret 名称，必须与 `IngressRoute` 位于同一命名空间。	""	否
`tls.` `options.name`	使用的 `TLSOption` 名称。详见 TLS 选项。	""	否
`tls.` `options.namespace`	使用的 `TLSOption` 所在的命名空间。	""	否
`tls.certResolver`	用于自动生成 TLS 证书的证书解析器名称。	""	否
`tls.domains`	生成证书所覆盖的域名列表，一个 `tls.domain` 对应一张证书。详见域名定义。		否
`tls.` `domains[n].main`	主域名。	""	是
`tls.` `domains[n].sans`	备用域名（SAN）列表。		否

中间件¶

可以将一组中间件附加到每个 HTTP 路由器。
中间件仅在规则匹配时生效，并在请求转发给服务之前执行。
中间件按照其在路由器中的声明顺序执行。
在 Kubernetes 中，middleware 选项允许通过中间件的名称和命名空间引用它（如果中间件与 IngressRoute 位于同一命名空间，可以省略命名空间）。

为 IngressRoute 附加多个中间件

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps

spec:
  entryPoints:
    - websecure
  routes:
  - match: Host(`example.com`)
    kind: Rule
    middlewares:
    # same namespace as the IngressRoute
    - name: middleware01
    # default namespace
    - name: middleware02
      namespace: apps
    # Other namespace
    - name: middleware03
      namespace: other-ns
    services:
    - name: whoami
      port: 80

routes.services.kind

由于 name 字段可以引用不同类型的对象，请使用 kind 字段消除歧义。 kind 字段允许以下值：

Service（默认值）：引用 Kubernetes Service
TraefikService：引用 TraefikService 对象

TLS 选项¶

options 字段支持对 TLS 参数进行精细控制。它引用一个 TLSOption，并且仅在定义了 Host 规则时应用。

服务器名称关联¶

TLS 选项引用始终映射到规则中 Host 部分指定的主机名，而不是映射到路由器或路由器规则。一个规则也可能包含多个 Host 部分。此时，TLS 选项引用会映射到所有这些主机名。

系统根据 TLS 握手期间提供的服务器名称，从上述映射中选择 TLS 选项，所有这些操作都发生在实际路由之前。

发生域名前置时，如果 Host 请求头与 SNI 关联的 TLS 选项不同， Traefik 会返回状态码 421。

TLS 选项冲突¶

由于 TLS 选项引用映射到主机名，如果配置导致同一个主机名（来自 Host 规则）匹配到两个 TLS 选项引用，就会发生冲突，如下例所示。

冲突检测不局限于命名空间：只要任意命名空间中定义的 IngressRoute，甚至来自其他提供者的路由器，在同一入口点上服务同一个主机名，就会与该配置发生冲突。

示例

IngressRoute01

  apiVersion: traefik.io/v1alpha1
  kind: IngressRoute
  metadata:
    name: IngressRoute01
    namespace: apps

  spec:
    entryPoints:
      - foo
    routes:
    - match: Host(`example.net`)
      kind: Rule
    tls:
      options: foo
      ...

IngressRoute02

  apiVersion: traefik.io/v1alpha1
  kind: IngressRoute
  metadata:
    name: IngressRoute02
    namespace: apps

  spec:
    entryPoints:
      - foo
    routes:
    - match: Host(`example.net`)
      kind: Rule
    tls:
      options: bar
    ...

发生这种情况时，两个映射都会被丢弃，这些路由器的主机名（示例中为 example.net）会改为关联到默认 TLS 选项。

默认 TLS 选项

default TLS 选项是冲突解决时的回退配置，因此其安全性不应低于可能被它替代的选项。

更多信息请参阅 TLS 选项冲突一节。

使用 IngressRoute 实现多层路由¶

多层路由允许在 IngressRoute 之间建立层级关系，父 IngressRoute 可以先应用中间件，再由子 IngressRoute 进行路由决策。

这特别适合基于身份认证的路由：父 IngressRoute 验证请求并添加上下文（例如通过请求头传递用户角色），子 IngressRoute 再根据这些上下文进行路由。

当子 IngressRoute 引用一个具有多条路由的父 IngressRoute 时，所有父路由器都会成为所有子路由器的父级。

完整的多层路由文档

多层路由概念、验证规则和使用场景的详细说明，请参阅专门的多层路由页面。

配置要求¶

根 IngressRoute¶

没有 parentRefs，位于层级顶端
可以配置 entryPoints、tls 和 observability
可以是带子级的父 IngressRoute，也可以是带服务的独立 IngressRoute

中间层 IngressRoute¶

通过 parentRefs 引用父 IngressRoute
具有一个或多个子 IngressRoute
不得定义 service
不得配置 entryPoints、tls 或 observability

叶级 IngressRoute¶

通过 parentRefs 引用父 IngressRoute
必须定义 service
不得配置 entryPoints、tls 或 observability

跨命名空间引用

跨命名空间的父级引用需要启用提供者的 allowCrossNamespace 选项。如果未启用，将跳过子 IngressRoute 的创建并记录错误日志。

示例：基于身份认证的路由¶

带 ForwardAuth 的父 IngressRoute 与子 IngressRoute

父 IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-parent
  namespace: default
spec:
  entryPoints:
    - websecure
  tls:
    certResolver: letsencrypt
  routes:
    # Parent route with authentication - no services
    - match: Host(`api.example.com`) && PathPrefix(`/api`)
      kind: Rule
      middlewares:
        - name: auth-middleware
          namespace: default
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: auth-middleware
  namespace: default
spec:
  forwardAuth:
    address: "http://auth-service.default.svc.cluster.local:8080/auth"
    authResponseHeaders:
      - X-User-Role
      - X-User-Name

子 IngressRoute

# Child IngressRoute for admin users
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-admin
  namespace: default
spec:
  parentRefs:
    - name: api-parent
      namespace: default  # Optional - defaults to same namespace
  routes:
    - match: HeadersRegexp(`X-User-Role`, `admin`)
      kind: Rule
      services:
        - name: admin-service
          port: 80
---
# Child IngressRoute for regular users
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-user
  namespace: default
spec:
  parentRefs:
    - name: api-parent
  routes:
    - match: HeadersRegexp(`X-User-Role`, `user`)
      kind: Rule
      services:
        - name: user-service
          port: 80

服务

apiVersion: v1
kind: Service
metadata:
  name: auth-service
  namespace: default
spec:
  ports:
    - port: 8080
  selector:
    app: auth-service
---
apiVersion: v1
kind: Service
metadata:
  name: admin-service
  namespace: default
spec:
  ports:
    - port: 80
  selector:
    app: admin-backend
---
apiVersion: v1
kind: Service
metadata:
  name: user-service
  namespace: default
spec:
  ports:
    - port: 80
  selector:
    app: user-backend

工作流程：

对 https://api.example.com/api/endpoint 的请求匹配父路由器
auth-middleware（ForwardAuth）通过 auth-service 验证请求
auth-service 返回 200 OK，并携带 X-User-Role 响应头，例如 admin 或 user
子路由器根据修改后的请求（含 X-User-Role 请求头）评估规则
根据角色，将请求路由到 admin-service 或 user-service