Knative Serving 服务 HTTP 协议配置指南:HTTPS 重定向与 HTTP/1 全双工详解
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-networkConfigMap 中的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 访问,会带来两个问题:
- 敏感数据(凭据、业务数据)在传输过程中以明文暴露;
- 用户可能缓存
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://
可能原因与排查顺序:
- 证书未就绪:
external-domain-tls未开启,或 cert-manager 尚未签发证书。此时即便http-protocol为redirected,也不会产生 HTTPS 重定向目标。检查kubectl get certificate与kubectl rollout restart deploy/controller -n knative-serving是否已执行。 - 注解拼写或位置错误:确认是
networking.knative.dev/http-protocol(不是networking.knative.dev/https-redirect等其他键),且位于 Service 的metadata.annotations。 - 值未生效: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 访问能力;反之,也可以全局放开、个别收紧。
五、相关文档与源码入口
- 本文核心文档:服务 HTTP 协议配置
- 外部域名 TLS 与证书:配置外部域名加密
- 网络层与 Ingress 配置:配置 Knative 网络
- Service 对象模型:Knative Services 概述
- 自定义域名映射:自定义域名(DomainMapping)
- 特性引入记录:Knative v1.13 发布说明(HTTP/1 full duplex)、Knative v1.4 发布说明(
networking.knative.dev/http-protocol注解在 DomainMapping 上的支持)
实践提示:上述配置均属集群级或工作负载级行为调整,建议先在非生产命名空间验证效果,再通过
config-networkConfigMap 或 Knative Operator 逐步推广到全集群,确保 HTTPS 重定向与全双工能力在不影响现有客户端的前提下平滑上线。