Traefik 与 Kubernetes Ingress¶

路由配置¶

Kubernetes Ingress 提供者监听传入的 Ingress 事件，例如下方示例，并据此生成对应的动态配置，进而创建相应的路由器、服务、处理器等组件。

配置示例¶

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web

spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

注解¶

在注解中引用资源

在注解中引用其他提供者定义的资源时，必须使用提供者命名空间语法。

启用 safeNaming 后，带命名空间的 @kubernetescrd 引用必须采用 namespace_name@kubernetescrd 格式，而不是 namespace-name@kubernetescrd，并使用与提供者生成的其他名称相同的 _ 分隔符。

Ingress 上的注解¶

注解	说明	值
`traefik.ingress.kubernetes.io/router.entrypoints`	更多信息请参阅入口点。	`ep1,ep2`
`traefik.ingress.kubernetes.io/router.middlewares`	更多信息请参阅中间件概述。	`auth@file,default-prefix@kubernetescrd`
`traefik.ingress.kubernetes.io/router.priority`	更多信息请参阅优先级。	`"42"`
`traefik.ingress.kubernetes.io/router.rulesyntax`	更多信息请参阅规则语法。已弃用： RuleSyntax 选项已弃用，将在下一个主版本中移除。请勿使用此字段，应将路由器规则改写为 v3 语法。	`"v2"`
`traefik.ingress.kubernetes.io/router.pathmatcher`	覆盖路径所使用的默认路由器规则类型。仅允许指定与路径有关的匹配器名称：`Path`、`PathPrefix` 或 `PathRegexp`。默认值：`PathPrefix`	`Path`
`traefik.ingress.kubernetes.io/router.tls`	为路由器启用 TLS。	`"true"`
`traefik.ingress.kubernetes.io/router.tls.certresolver`	指定 TLS 证书使用的证书解析器。	`myresolver`
`traefik.ingress.kubernetes.io/router.tls.domains.n.main`	定义 TLS 证书的主域名，其中 n 为域名索引。	`example.org`
`traefik.ingress.kubernetes.io/router.tls.domains.n.sans`	定义 TLS 证书的主体备用名称（SAN），其中 n 为域名索引。	`test.example.org,dev.example.org`
`traefik.ingress.kubernetes.io/router.tls.options`	更多信息请参阅 TLS 选项。 TLS 选项映射到 Ingress 规则的主机名，而不是 Ingress 本身。因此，无论处于哪个命名空间，如果一个 Ingress 服务的主机名已经由使用不同 TLS 选项的其他 Ingress 提供服务，就会发生冲突。更多信息请参阅 TLS 选项冲突。	`foobar@file`
`traefik.ingress.kubernetes.io/router.observability.accesslogs`	控制路由器是否生成访问日志。更多信息请参阅可观测性。	`true`
`traefik.ingress.kubernetes.io/router.observability.metrics`	控制路由器是否生成指标。更多信息请参阅可观测性。	`true`
`traefik.ingress.kubernetes.io/router.observability.tracing`	控制路由器是否生成追踪数据。更多信息请参阅可观测性。	`true`
`traefik.ingress.kubernetes.io/router.observability.traceVerbosity`	定义路由器的追踪详细程度。有效值：`minimal`、`detailed`。默认值：`minimal`。更多信息请参阅可观测性。	`detailed`

Service 上的注解¶

注解	说明	值
`traefik.ingress.kubernetes.io/service.nativelb`	创建负载均衡器时，控制其子节点是各 Pod IP，还是唯一的 Kubernetes Service clusterIP。具体而言，将 `nativelb` 设为 `true` 后，Traefik 会将流量路由到 Kubernetes Service，使用 kube-proxy、Cilium、Calico 等集群网络机制，并由 Kubernetes 自身执行负载均衡。将 `nativelb` 设为 `false` 时，Traefik 直接将流量路由到 Pod，并在内部作出负载均衡决策。无论 `nativelb` 如何配置，Traefik 默认都会为了性能复用已建立的后端连接。但连接复用与 `nativelb: true` 结合时可能造成负载不均。如果无法接受，可以将 `maxIdleConnsPerHost` 设为 `-1` 以禁用连接复用。默认值：`false`	`"true"`
`traefik.ingress.kubernetes.io/service.nodeportlb`	创建负载均衡器时，控制在服务类型为 NodePort 时是否直接以节点内部 IP 和 nodePort 作为子节点。这样，当 Traefik 运行在 Kubernetes 集群外部、但与节点位于同一网络时，仍能访问服务。默认值：`false`	`"true"`
`traefik.ingress.kubernetes.io/service.serversscheme`	覆盖默认协议。	`h2c`
`traefik.ingress.kubernetes.io/service.serverstransport`	更多信息请参阅 ServersTransport。	`foobar@file`
`traefik.ingress.kubernetes.io/service.passhostheader`	控制是否将 Host 请求头转发到后端。	`"true"`
`traefik.ingress.kubernetes.io/service.sticky.cookie`	通过 Cookie 启用粘性会话。更多信息请参阅粘性会话。	`"true"`
`traefik.ingress.kubernetes.io/service.sticky.cookie.name`	定义粘性会话的 Cookie 名称。更多信息请参阅粘性会话。	`foobar`
`traefik.ingress.kubernetes.io/service.sticky.cookie.secure`	为粘性会话 Cookie 设置 Secure 标志。更多信息请参阅粘性会话。	`"true"`
`traefik.ingress.kubernetes.io/service.sticky.cookie.samesite`	为粘性会话 Cookie 设置 SameSite 属性。更多信息请参阅粘性会话。	`"none"`
`traefik.ingress.kubernetes.io/service.sticky.cookie.domain`	为粘性会话 Cookie 设置 Domain 属性，定义将 Cookie 发送到的目标主机。更多信息请参阅粘性会话。	`"foo.com"`
`traefik.ingress.kubernetes.io/service.sticky.cookie.httponly`	为粘性会话 Cookie 设置 HttpOnly 标志。更多信息请参阅粘性会话。	`"true"`
`traefik.ingress.kubernetes.io/service.sticky.cookie.maxage`	为粘性会话 Cookie 设置 Max-Age 属性，单位为秒。更多信息请参阅粘性会话。	`42`
`traefik.ingress.kubernetes.io/service.sticky.cookie.path`	为粘性会话 Cookie 设置 Path 属性，定义请求 URL 中必须包含的路径。更多信息请参阅粘性会话。	`/foobar`

Service 注解与中间件

只有在 Kubernetes Service 被用作 Ingress 后端时，这些 service 注解才会配置该服务。对于 ErrorPages 等中间件引用的服务，这些注解不会生效：中间件的服务使用中间件定义进行配置，不读取 Kubernetes Service 上设置的注解。这种情况下，如果需要设置 serversTransport，应在中间件定义中声明它。

traefik.ingress.kubernetes.io/service.middlewares

更多信息请参阅服务中间件。

traefik.ingress.kubernetes.io/service.middlewares: auth@file,prefix@kubernetescrd

TLS¶

通过入口点的 HTTP 选项启用 TLS¶

可以通过入口点的 HTTP 选项启用 TLS：

命令行（CLI）

# Static configuration
--entryPoints.websecure.address=:443
--entryPoints.websecure.http.tls

文件（YAML）

# Static configuration
entryPoints:
  websecure:
    address: ':443'
    http:
      tls: {}

文件（TOML）

# Static configuration
[entryPoints.websecure]
  address = ":443"

    [entryPoints.websecure.http.tls]

这样，附加到该入口点的所有 Ingress 默认都会启用 TLS 终止。

在入口点上启用 TLS 来配置 Kubernetes Ingress 控制器

RBAC

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: traefik-ingress-controller
rules:
  - apiGroups:
      - ""
    resources:
      - services
      - secrets
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - discovery.k8s.io
    resources:
      - endpointslices
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - extensions
      - networking.k8s.io
    resources:
      - ingresses
      - ingressclasses
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - extensions
      - networking.k8s.io
    resources:
      - ingresses/status
    verbs:
      - update

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: traefik-ingress-controller
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: traefik-ingress-controller
subjects:
  - kind: ServiceAccount
    name: traefik-ingress-controller
    namespace: default

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure

spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

Traefik

apiVersion: v1
kind: ServiceAccount
metadata:
  name: traefik-ingress-controller

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: traefik
  labels:
    app: traefik

spec:
  replicas: 1
  selector:
    matchLabels:
      app: traefik
  template:
    metadata:
      labels:
        app: traefik
    spec:
      serviceAccountName: traefik-ingress-controller
      containers:
        - name: traefik
          image: traefik:v3.7
          args:
            - --entryPoints.websecure.address=:443
            - --entryPoints.websecure.http.tls
            - --providers.kubernetesingress
          ports:
            - name: websecure
              containerPort: 443

---
apiVersion: v1
kind: Service
metadata:
  name: traefik
spec:
  type: LoadBalancer
  selector:
    app: traefik
  ports:
    - protocol: TCP
      port: 443
      name: websecure
      targetPort: 443

Whoami

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  labels:
    app: traefiklabs
    name: whoami

spec:
  replicas: 2
  selector:
    matchLabels:
      app: traefiklabs
      task: whoami
  template:
    metadata:
      labels:
        app: traefiklabs
        task: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: whoami

spec:
  ports:
    - name: http
      port: 80
  selector:
    app: traefiklabs
    task: whoami

通过注解启用 TLS¶

要为根据 Ingress 创建的底层路由器启用 TLS，应通过注解进行配置：

traefik.ingress.kubernetes.io/router.tls: "true"

更多选项请参阅可用注解。

为 Kubernetes Ingress 控制器配置 TLS

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"

spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

证书管理¶

使用 Secret

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo
  namespace: production

spec:
  rules:
  - host: example.net
    http:
      paths:
      - path: /bar
        pathType: Exact
        backend:
          service:
            name:  service1
            port:
              number: 80
  # Only selects which certificate(s) should be loaded from the secret, in order to terminate TLS.
  # Doesn't enable TLS for that ingress (hence for the underlying router).
  # Please see the TLS annotations on ingress made for that purpose.
  tls:
  - secretName: supersecret

Secret

apiVersion: v1
kind: Secret
metadata:
  name: supersecret

data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

TLS 证书可以通过 Secret 对象管理。

提示

Kubernetes Secret 只能存储用户提供的 TLS 证书。目前还无法通过 Kubernetes Secret 管理 Let's Encrypt 证书。

Traefik 与 Pod 之间的通信¶

直接路由到 Kubernetes 服务

如果希望直接路由到 Kubernetes 服务，可以在 Kubernetes 服务上使用 traefik.ingress.kubernetes.io/service.nativelb 注解。它控制创建负载均衡器时，子节点是各 Pod IP，还是唯一的 Kubernetes Service clusterIP。

另一种方式是使用 ExternalName 服务，通过 DNS 将请求转发到 Kubernetes 服务。为此，必须允许 ExternalName 服务。

Traefik 会根据 Ingress spec 中提供的服务，自动请求端点信息。虽然 Traefik 会直接连接端点（Pod），它仍会检查服务端口，以确定是否需要使用 TLS 通信。

以下三种方式可以配置 Traefik 使用 HTTPS 与 Pod 通信：

Ingress spec 中定义的服务端口为 443。请注意，仍可通过 targetPort 在 Pod 上使用其他端口。
Ingress spec 中定义的服务端口名称以 https 开头，例如 https-api、https-web 或 https。
Service spec 包含 traefik.ingress.kubernetes.io/service.serversscheme: https 注解。

只要存在其中任一配置，就会将后端通信协议视为 TLS，并自动通过 TLS 建立连接。

提示

请注意，启用 Traefik 与 Pod 之间的 TLS 通信后，必须使用具有正确证书信任链和 IP 主体名称的受信任证书。如果无法做到，可能需要跳过 TLS 证书验证。更多信息请参阅 insecureSkipVerify TLSOption 设置。

全局默认后端 Ingress¶

可以创建如下形式的 Ingress：

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: cheese

spec:
  defaultBackend:
    service:
      name: stilton
      port:
        number: 80

该 Ingress 使用了 Ingress 的全局默认后端属性。这允许用户创建一个“默认路由器”，匹配所有尚未匹配的请求。

提示

由于 Traefik 使用优先级机制，可能需要将此 Ingress 的优先级设置为低于环境中的其他 Ingress，避免该全局 Ingress 接收本可匹配到其他 Ingress 的请求。

为此，应在 Ingress 上相应设置 traefik.ingress.kubernetes.io/router.priority 注解，详见 Ingress 上的注解。

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。