This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new 9690f34eed Document vertx-websocket limitations for knative usage
9690f34eed is described below
commit 9690f34eed8f1d3597836ebe138b782acd041011
Author: James Netherton <[email protected]>
AuthorDate: Fri Jun 12 13:07:47 2026 +0100
Document vertx-websocket limitations for knative usage
Fixes #8754
---
.../ROOT/pages/reference/extensions/knative.adoc | 37 ++++++++++++++++++++++
.../knative/runtime/src/main/doc/limitations.adoc | 31 ++++++++++++++++++
2 files changed, 68 insertions(+)
diff --git a/docs/modules/ROOT/pages/reference/extensions/knative.adoc
b/docs/modules/ROOT/pages/reference/extensions/knative.adoc
index 5924b630cb..587de3a374 100644
--- a/docs/modules/ROOT/pages/reference/extensions/knative.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/knative.adoc
@@ -43,3 +43,40 @@ Or add the coordinates to your existing project:
ifeval::[{doc-show-user-guide-link} == true]
Check the xref:user-guide/index.adoc[User guide] for more information about
writing Camel Quarkus applications.
endif::[]
+
+[id="extensions-knative-camel-quarkus-limitations"]
+== Camel Quarkus limitations
+
+[id="extensions-knative-limitations-vertx-websocket-with-knative-does-not-work-with-http-2"]
+=== vertx-websocket with Knative does not work with HTTP/2
+
+The xref:reference/extensions/vertx-websocket.adoc[vertx-websocket] extension
is supported with Knative, but has important protocol compatibility constraints.
+
+WebSocket connections require the HTTP/1.1 upgrade mechanism and are
incompatible with HTTP/2. If your Knative application is intended to accept
WebSocket connections, it **must not** allow negotiating the HTTP/2 protocol,
or else clients will fail to upgrade to the WebSocket protocol.
+
+This creates an incompatibility with the
xref:reference/extensions/grpc.adoc[grpc] extension, which requires HTTP/2.
+
+NOTE: If you need to use gRPC with Knative, you must configure HTTP/2 support.
+ifeval::[{doc-show-advanced-features} == true]
+See
https://docs.redhat.com/en/documentation/red_hat_openshift_serverless/1.31/html/serving/external-and-ingress-routing#using-http2-gRPC_kourier-gateway-service-type[Using
HTTP2 and gRPC] for configuration instructions.
+endif::[]
+ifeval::[{doc-show-advanced-features} == false]
+Refer to your platform's Knative documentation for configuration instructions.
+endif::[]
+
+To use WebSockets with Knative:
+
+* Ensure your Knative service does not negotiate HTTP/2
+* Configure ingress gateways and load balancers to use HTTP/1.1 for WebSocket
routes
+* Do not enable HTTP/2 support if your application accepts WebSocket
connections
+
+For platform-specific configuration, refer to:
+
+ifeval::[{doc-show-advanced-features} == true]
+*
https://docs.openshift.com/container-platform/4.15/networking/ingress-operator.html[OpenShift
Ingress Operator documentation]
+endif::[]
+ifeval::[{doc-show-advanced-features} == false]
+* https://kubernetes.io/docs/concepts/services-networking/ingress/[Kubernetes
Ingress documentation]
+*
https://knative.dev/docs/serving/services/configure-requests/#protocol-selection[Knative
protocol selection documentation]
+endif::[]
+
diff --git a/extensions/knative/runtime/src/main/doc/limitations.adoc
b/extensions/knative/runtime/src/main/doc/limitations.adoc
new file mode 100644
index 0000000000..1141807cc9
--- /dev/null
+++ b/extensions/knative/runtime/src/main/doc/limitations.adoc
@@ -0,0 +1,31 @@
+=== vertx-websocket with Knative does not work with HTTP/2
+
+The xref:reference/extensions/vertx-websocket.adoc[vertx-websocket] extension
is supported with Knative, but has important protocol compatibility constraints.
+
+WebSocket connections require the HTTP/1.1 upgrade mechanism and are
incompatible with HTTP/2. If your Knative application is intended to accept
WebSocket connections, it **must not** allow negotiating the HTTP/2 protocol,
or else clients will fail to upgrade to the WebSocket protocol.
+
+This creates an incompatibility with the
xref:reference/extensions/grpc.adoc[grpc] extension, which requires HTTP/2.
+
+NOTE: If you need to use gRPC with Knative, you must configure HTTP/2 support.
+ifeval::[{doc-show-advanced-features} == true]
+See
https://docs.redhat.com/en/documentation/red_hat_openshift_serverless/1.31/html/serving/external-and-ingress-routing#using-http2-gRPC_kourier-gateway-service-type[Using
HTTP2 and gRPC] for configuration instructions.
+endif::[]
+ifeval::[{doc-show-advanced-features} == false]
+Refer to your platform's Knative documentation for configuration instructions.
+endif::[]
+
+To use WebSockets with Knative:
+
+* Ensure your Knative service does not negotiate HTTP/2
+* Configure ingress gateways and load balancers to use HTTP/1.1 for WebSocket
routes
+* Do not enable HTTP/2 support if your application accepts WebSocket
connections
+
+For platform-specific configuration, refer to:
+
+ifeval::[{doc-show-advanced-features} == true]
+*
https://docs.openshift.com/container-platform/4.15/networking/ingress-operator.html[OpenShift
Ingress Operator documentation]
+endif::[]
+ifeval::[{doc-show-advanced-features} == false]
+* https://kubernetes.io/docs/concepts/services-networking/ingress/[Kubernetes
Ingress documentation]
+*
https://knative.dev/docs/serving/services/configure-requests/#protocol-selection[Knative
protocol selection documentation]
+endif::[]
