Kubernetes Gateway API TLS路由使用及说明

更新时间：2026年03月03日 09:08:04 作者：文静小土豆

TLSRoute是GatewayAPI中的一个资源类型,用于处理TLS流量,可以根据主机名等TLS元数据将流量定向到不同的Kubernetes后端服务,通过配置Gateway和TLSRoute,可以实现TLS流量的透传和终止处理,满足不同的安全和管理需求

什么是 TLSRoute？

TLSRoute 是 Gateway API 中的一个资源类型，专门用于处理 TLS 流量。它可以根据主机名等 TLS 元数据，将流量定向到不同的 Kubernetes 后端服务。

Gateway 配置：TLS 流量的入口

要使用 TLSRoute，首先需要配置 Gateway 作为流量入口点。以下是一个同时支持两种 TLS 处理模式的 Gateway 配置示例：

apiVersion: gateway.networking.k8s.io/v1  # API版本
kind: Gateway                             # 资源类型
metadata:
  name: example-gateway                   # Gateway名称
spec:
  gatewayClassName: example-gateway-class  # Gateway控制器类型
  listeners:
  - name: tls                             # 监听器名称，用于TLSRoute引用
    protocol: TLS                         # 协议类型
    port: 443                             # 监听端口
    tls:
      mode: Passthrough                   # TLS处理模式：透传
  - name: tls-terminate                   # 监听器名称，用于TLSRoute引用
    protocol: TLS                         # 协议类型
    port: 8443                            # 监听端口
    tls:
      mode: Terminate                     # TLS处理模式：终止
      certificateRefs:
      - name: tls-terminate-certificate   # 证书名称

在这个配置中，我们定义了两个监听器：

443 端口：使用 Passthrough 模式，直接透传 TLS 流量
8443 端口：使用 Terminate 模式，在 Gateway 层面终止 TLS 连接

TLSRoute 配置：精细化的流量路由

透传模式（Passthrough）

当我们需要后端服务直接处理 TLS 连接时，可以使用透传模式：

apiVersion: gateway.networking.k8s.io/v1  # API版本
kind: TLSRoute                            # 资源类型
metadata:
  name: foo-route                         # TLSRoute名称
spec:
  parentRefs:
  - name: example-gateway                 # 引用的Gateway名称
    sectionName: tls                      # 引用的监听器名称
  hostnames:
  - "foo.example.com"                     # 匹配的主机名
  rules:
  - backendRefs:
    - name: foo-svc                       # 后端服务名称
      port: 443                           # 后端服务端口

这个配置会将 foo.example.com 的流量通过 443 端口的透传监听器，直接转发到 foo-svc 服务的 443 端口。

终止模式（Terminate）

当我们希望在 Gateway 层面集中管理 TLS 证书时，可以使用终止模式：

apiVersion: gateway.networking.k8s.io/v1  # API版本
kind: TLSRoute                            # 资源类型
metadata:
  name: bar-route                         # TLSRoute名称
spec:
  parentRefs:
  - name: example-gateway                 # 引用的Gateway名称
    sectionName: tls-terminate            # 引用的监听器名称
  hostnames:
  - "bar.example.com"                     # 匹配的主机名
  rules:
  - backendRefs:
    - name: bar-svc                       # 后端服务名称
      port: 8080                          # 后端服务端口

这个配置会将 bar.example.com 的流量通过 8443 端口的终止监听器，在 Gateway 层面终止 TLS 连接后，转发到 bar-svc 服务的 8080 端口。

两种 TLS 模式的对比

透传模式（Passthrough）

工作原理：Gateway 将加密的 TCP 流直接传递给后端服务，由后端服务负责 TLS 终止。

适用场景：

后端服务需要直接处理 TLS 连接
后端服务需要访问客户端证书信息
实现端到端加密

配置特点：不需要在 Gateway 上配置证书，简化了 Gateway 配置。

终止模式（Terminate）

工作原理：Gateway 首先使用指定的证书终止 TLS 流，然后将未加密的 TCP 流传递给后端服务。

适用场景：

集中管理 TLS 证书，减少证书维护成本
减少后端服务的 TLS 处理开销
需要在 Gateway 层进行流量检查或修改

配置特点：需要在 Gateway 上配置 certificateRefs 指定证书。

生产环境推荐配置

Gateway 生产环境配置

apiVersion: gateway.networking.k8s.io/v1  # API版本
kind: Gateway                             # 资源类型
metadata:
  name: production-gateway                # Gateway名称
  namespace: ingress                      # 建议使用单独的命名空间
spec:
  gatewayClassName: production-gateway-class  # 生产环境专用Gateway控制器
  listeners:
  - name: https                           # 监听器名称
    protocol: TLS                         # 协议类型
    port: 443                             # 标准HTTPS端口
    tls:
      mode: Terminate                     # 生产环境推荐使用终止模式
      certificateRefs:
      - name: production-tls              # 生产环境证书
        kind: Secret                      # 证书存储类型
        group: core                       # API组
  - name: tls-passthrough                 # 透传模式监听器
    protocol: TLS                         # 协议类型
    port: 8443                            # 透传模式端口
    tls:
      mode: Passthrough                   # 透传模式

TLSRoute 生产环境配置

apiVersion: gateway.networking.k8s.io/v1  # API版本
kind: TLSRoute                            # 资源类型
metadata:
  name: production-app-route              # TLSRoute名称
  namespace: app-namespace                # 应用命名空间
spec:
  parentRefs:
  - name: production-gateway              # 引用生产环境Gateway
    namespace: ingress                    # Gateway所在命名空间
    sectionName: https                    # 引用终止模式监听器
  hostnames:
  - "app.example.com"                     # 生产环境域名
  rules:
  - backendRefs:
    - name: app-service                   # 后端服务名称
      port: 8080                          # 后端服务端口
      weight: 100                         # 流量权重

常见问题及解决方案

路由不生效：检查 TLSRoute 的 parentRefs 是否正确引用了 Gateway 和监听器
TLS 握手失败：检查证书配置是否正确，特别是在 Terminate 模式下
后端服务不可达：检查网络连接和后端服务状态
主机名匹配失败：确保 TLSRoute 中的 hostnames 配置与实际请求的主机名匹配

总结

TLSRoute 为 Kubernetes 集群中的 TLS 流量管理提供了强大而灵活的解决方案。通过选择合适的 TLS 处理模式，我们可以根据实际需求构建安全、高效的服务暴露架构。

无论是需要端到端加密的场景，还是希望集中管理证书的场景，TLSRoute 都能满足我们的需求，帮助我们构建更加可靠的 Kubernetes 网络架构。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:

Podman开机自启容器实现过程及与Docker对比
这篇文章主要为大家介绍了Podman开机自启容器实现过程，通过示例代码的形式进行演绎过程，有需要的朋友可以参考下，希望可以有所帮助
2021-09-09
基于云服务MRS构建DolphinScheduler2调度系统的案例详解
这篇文章主要介绍了基于云服务MRS构建DolphinScheduler2调度系统,本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下
2022-05-05
k8s证书有效期时间修改的方法详解
K8S集群有证书的概念,之前一直是使用默认的,默认都是1年和10年的,1年有效期这显然对于生产环境是不合适的,下面这篇文章主要给大家介绍了关于k8s证书有效期时间修改的相关资料,需要的朋友可以参考下
2022-08-08
ragflow k8s部署过程图文详解
这篇文章主要介绍了ragflow k8s部署详细过程,本文将使用ragflow-0.18.0,来进行演示详细部署过程,需要的朋友可以参考下
2025-04-04
K8S Node异常问题排查过程
文章介绍了使用kubectl命令行对K8S集群中的Node异常进行初步定位的方法,包括查看NotReady发生时间、异常event、NodeConditions以及kubelet日志,文章还详细描述了常见问题的解决方法,如Kubelet停止汇报心跳、PLEG不可用和Node被驱逐等情况
2026-01-01
k8s容器状态Terminating无法删除的问题及解决
这篇文章主要介绍了k8s容器状态Terminating无法删除的问题及解决,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2025-07-07
Rainbond网络治理插件ServiceMesh官方文档说明
这篇文章主要为大家介绍了Rainbond网络治理插件ServiceMesh官方文档说明，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2022-04-04
K8s创建资源的两种方法实例
而在我看来,在学习K8S之前,有必要对K8S的资源对象有个全局的概念,下面这篇文章主要给大家介绍了关于K8s创建资源的两种方法,需要的朋友可以参考下
2022-05-05
kubernetes存储之GlusterFS集群详解
最近工作中用到了GlusterFS作为Kubernetes的存储,这篇文章主要给大家介绍了关于kubernetes存储之GlusterFS集群的相关资料,文中通过示例代码介绍的非常详细,需要的朋友可以参考下
2022-04-04
不同k8s集群间服务如何相互访问实现详解
这篇文章主要为大家介绍了不同k8s集群间服务如何相互访问实现详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-04-04