Knative Serving 服务 HTTP 协议配置指南:HTTPS 重定向与 HTTP/1 全双工详解

原创2026-10-15 12:43:001,928 阅读
文章标签:文档教程云原生

Knative Serving 服务 HTTP 协议配置指南:HTTPS 重定向与 HTTP/1 全双工详解

导读:本文围绕 Knative Serving 的 HTTP 协议配置展开,面向平台管理员(administrator),讲解如何为集群内所有 Knative Service 强制 HTTPS 重定向,以及如何按工作负载启用 HTTP/1 全双工(full duplex)支持。读完本文,你将掌握 http-protocol 全局键、networking.knative.dev/http-protocol 注解与 features.knative.dev/http-full-duplex 注解的完整用法,并能在真实集群中安全落地 HTTPS 强制策略与双向流式传输场景。

一、HTTP 协议配置在整个请求链路中的位置

Knative Serving 通过 Kubernetes 中的 Ingress 控制器(如 Kourier、Contour、Istio、Gateway API)将外部流量路由到用户容器。集群管理员对 HTTP 协议行为的控制点主要有两个:

  • HTTPS 重定向:决定 Service 是否允许纯 HTTP 流量,还是统一将 HTTP 请求以 301 重定向到 HTTPS。该行为由 config-network ConfigMap 中的 http-protocol 键(全局)或 Service/Revision 上的 networking.knative.dev/http-protocol 注解(按工作负载)控制。
  • HTTP/1 全双工:决定数据面(Data Path)上的反向代理(Queue-Proxy)与应用容器之间是否启用 HTTP/1 双向并发读写能力,由 Revision 上的 features.knative.dev/http-full-duplex 注解控制。

这两类配置都定义在 serving.knative.dev/v1 的 Service 对象或 knative-serving 命名空间下的 ConfigMap 中,属于 Knative 文档中「服务与网络配置」的一部分。相关背景可参考 Knative 网络配置总览 与 Knative Services 概述。

二、HTTPS 重定向:强制所有 Service 走 HTTPS

2.1 为什么需要 HTTPS 重定向

当集群通过 配置外部域名加密 为外部域名(例如 application.example.com)启用 TLS 证书后,Knative Service 的 URL 会变为 https:// 前缀。此时如果仍允许客户端通过明文 HTTP 访问,会带来两个问题:

  1. 敏感数据(凭据、业务数据)在传输过程中以明文暴露;
  2. 用户可能缓存 http:// 地址,导致后续访问始终停留在不安全协议上。

Knative 提供的 http-protocol 配置允许管理员强制对所有 Service 执行 HTTPS 重定向,客户端一旦发起 HTTP 请求,即收到 301 响应并被引导改用 HTTPS。

2.2 配置键与取值速查

原文档明确给出了以下配置要素,本文补充默认值与作用域说明:

配置项 键名 作用域 取值 默认值
全局键 http-protocol(位于 config-network ConfigMap) 集群级 enabled / redirected enabled
按 Revision 注解 networking.knative.dev/http-protocol Service / Revision 级 enabled / redirected 继承全局

取值语义:

  • enabled:Service 接受 HTTP 流量,明文 HTTP 请求照常处理;
  • redirected:Service 对所有 HTTP 连接返回 301 重定向,要求客户端改用 HTTPS 访问。

2.3 按 Service 覆盖默认行为(Per Service)

在 serving.knative.dev/v1 的 Service 元数据上直接添加注解,即可让单个 Service 独立于集群默认策略:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: example
  namespace: default
  annotations:
    networking.knative.dev/http-protocol: "redirected"
spec:
  ...

需要注意两点:

  • 注解作用于 Service 创建的 Revision,因此修改注解会触发新 Revision 的生成;
  • 注解值需使用字符串形式("redirected"),与 ConfigMap 中的写法保持一致。

从 Knative v1.4 版本起,该注解同样支持在 DomainMapping CRD 上使用,用于按域名覆盖默认 HTTP 行为(参见 Knative v1.4 发布说明 中关于 networking.knative.dev/http-protocol 注解的说明)。若你使用自定义域名映射,可以查看 自定义域名(DomainMapping) 了解更多。

2.4 全局覆盖:通过 config-network ConfigMap

集群管理员可在 knative-serving 命名空间的 config-network ConfigMap 中设置全局默认值,影响所有未单独覆盖的 Service:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-network
  namespace: knative-serving
data:
  http-protocol: "redirected"

修改后,通常需要重启 controller Deployment 使其生效(与外部域名 TLS 配置中的做法一致):

kubectl rollout restart deploy/controller -n knative-serving

2.5 全局覆盖:通过 Knative Operator

如果集群通过 Knative Operator 管理,则可在 KnativeServing 自定义资源中声明全局配置,由 Operator 负责同步到 ConfigMap:

apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
  name: knative-serving
spec:
  config:
    network:
      http-protocol: "redirected"

注意 Operator 写法中 spec.config.network 下的键与 ConfigMap data 下的键一一对应,http-protocol 的值同样为 enabled 或 redirected。

2.6 与外部域名 TLS 的联动配置

http-protocol 的最佳实践通常与 external-domain-tls 配合使用。在 配置外部域名加密 文档中给出了完整示例:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-network
  namespace: knative-serving
data:
  ...
  external-domain-tls: Enabled
  http-protocol: Redirected
  ...
  • external-domain-tls: Enabled 使集群开始自动为 Service 申请并续期外部域名证书;
  • http-protocol: Redirected 确保已有证书后,所有明文 HTTP 请求被重定向到 HTTPS。

若需要对个别 Service 或 Route 关闭自动证书签发(例如仅用于内部测试),可在其元数据上添加注解 networking.knative.dev/disable-external-domain-tls: "true",此时该 Service 的 URL 仍保持 http:// 前缀。完整的信任链、证书轮换与手动签发说明,请参见 配置外部域名加密。

2.7 验证 HTTPS 重定向效果

部署一个 Service 后,通过 kubectl get ksvc 检查其 URL:

kubectl get ksvc -n <your-namespace>

启用外部域名 TLS 且 http-protocol: Redirected 时,输出应类似:

NAME           URL                                          LATEST               AGE     CONDITIONS   READY   REASON
autoscale-go   https://autoscale-go.default.1.example.com   autoscale-go-dd42t   8m17s   3 OK / 3     True
  • URL 前缀为 https:// 表示证书链路已就绪;
  • 此时使用 curl -i http://autoscale-go.default.1.example.com 访问,应收到 301 重定向响应,Location 指向对应的 https:// 地址。

三、HTTP/1 全双工支持:按工作负载开启双向流

3.1 什么是 HTTP/1 全双工,为什么需要它

HTTP/1 协议本身允许客户端与服务端在同一 TCP 连接上双向并发读写(全双工)。但在 Knative 的数据面上,请求先经过反向代理(Queue-Proxy 与 Ingress 层)再转发到应用容器。某些应用服务器在反向代理尚未读完整个请求体时,就开始向代理写回响应数据,此时代理若按"先读完整请求再写响应"的串行方式处理,就会出现双向同时读写被阻塞的问题。这正是 Go 语言社区在 issue #40747 中记录的场景:应用服务器向代理写回数据,而代理尚未消费完整个请求体。

Knative 通过启用 HTTP/1 full duplex 支持,让数据路径上的代理可以同时进行请求读取与响应写入,从而解决上述卡死问题。该能力在底层对应 Go 标准库 net/http 中 ResponseController 的 EnableFullDuplex 机制,可在数据面上端到端生效。

3.2 配置方式

在 Service 的 Revision 模板元数据上添加注解即可启用:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: example-service
  namespace: default
spec:
  template:
    metadata:
      annotations:
        features.knative.dev/http-full-duplex: "Enabled"
...

要点说明:

  • 注解位于 spec.template.metadata.annotations,即作用于每个 Revision;
  • 取值为 "Enabled"(字符串形式),符合 Knative feature flag 注解的命名规范;
  • 该特性自 Knative v1.13 版本起随数据面支持引入(参见 Knative v1.13 发布说明 中关于 HTTP/1 full duplex 的说明,其中明确指出工作负载需要以 features.knative.dev/http-full-duplex 注解标注)。

3.3 启用前的注意事项

原文档给出了明确的警告:在启用前务必使用你的 HTTP 客户端先行测试,因为较旧的客户端可能不支持 HTTP/1 全双工。具体建议:

  • 先在测试环境对典型客户端(浏览器、SDK、curl 版本)做冒烟测试,确认双向流式交互(如请求体与响应体同时传输)正常;
  • 确认应用容器框架(如 Go 的 http.Server、Node.js、Java Servlet 等)对同一连接上并发读写无兼容性问题;
  • 仅对确有双向并发需求的负载(如流式上传 + 流式响应、代理透传类应用)开启,普通请求/响应型服务保持默认即可。

3.4 工作原理与适用场景

从 Knative 的数据面结构看,该注解最终影响的是请求路径上反向代理对 HTTP/1 连接的处理方式:代理不再强制"请求读完才写响应",而是允许请求读取与响应写入同时进行。这适用于以下典型场景:

  • 应用服务器需要边读取客户端请求体、边持续回写数据(例如流式处理管道);
  • 客户端长连接上需要频繁的双向小消息交互,且协议无法升级为 WebSocket 或 HTTP/2。

需要说明的是,HTTP/1 全双工与 WebSocket 是两个不同的机制:WebSocket 通过 HTTP Upgrade 切换到独立全双工协议;而此处启用的是在 HTTP/1 请求-响应模型内的双向并发能力。Knative 对 WebSocket 的支持可参考 Knative Serving WebSockets 文章 中的讨论。

四、常见问题与排障思路

4.1 配置了 redirected 但 Service URL 仍是 http://

可能原因与排查顺序:

  1. 证书未就绪:external-domain-tls 未开启,或 cert-manager 尚未签发证书。此时即便 http-protocol 为 redirected,也不会产生 HTTPS 重定向目标。检查 kubectl get certificate 与 kubectl rollout restart deploy/controller -n knative-serving 是否已执行。
  2. 注解拼写或位置错误:确认是 networking.knative.dev/http-protocol(不是 networking.knative.dev/https-redirect 等其他键),且位于 Service 的 metadata.annotations。
  3. 值未生效:ConfigMap 修改后需要重启 Serving controller 才能被读取。

4.2 启用了 full duplex 后出现连接异常

  • 确认客户端版本支持 HTTP/1 全双工;
  • 确认应用容器是否真正需要双向并发,而非单纯的长连接;
  • 若问题集中在特定客户端,可在该 Service 上移除注解回退到默认行为,其余负载不受影响。

4.3 注解与全局配置的优先级

按 Revision 注解(networking.knative.dev/http-protocol)优先于全局 config-network 中的 http-protocol 键。这允许管理员在集群级强制 HTTPS 的同时,为个别内网/测试 Service 保留明文 HTTP 访问能力;反之,也可以全局放开、个别收紧。

五、相关文档与源码入口

实践提示:上述配置均属集群级或工作负载级行为调整,建议先在非生产命名空间验证效果,再通过 config-network ConfigMap 或 Knative Operator 逐步推广到全集群,确保 HTTPS 重定向与全双工能力在不影响现有客户端的前提下平滑上线。

登录后查看全文
docs