docs: PEM-5725 gRPC Transcoding (#4051)

* docs: 9-23-24 cve updates (#4046) * 9-23-24 cve updates * ci: auto-formatting prettier issues --------- Co-authored-by: frederickjoi <[email protected]> * docs: PEM-5725 * docs: review feedback * docs: vale feedback * docs: apply suggestions from code review Co-authored-by: caroldelwing <[email protected]> * ci: auto-formatting prettier issues * docs: feedback updates --------- Co-authored-by: frederickjoi <[email protected]> Co-authored-by: frederickjoi <[email protected]> Co-authored-by: caroldelwing <[email protected]> Co-authored-by: karl-cardenas-coding <[email protected]>
spectrocloud · Sep 24, 2024 · a74f3ac · a74f3ac
1 parent 2602a17
commit a74f3ac
Show file tree

Hide file tree

Showing 17 changed files with 121 additions and 49 deletions.
diff --git a/docs/docs-content/architecture/grps-proxy.md b/docs/docs-content/architecture/grps-proxy.md
@@ -11,19 +11,77 @@ sidebar_custom_props:
 
 Palette uses [gRPC](https://grpc.io) to communicate between the management platform and the workload cluster. gRPC is a
 high-performance, open-source universal Remote Procedure Call (RPC) framework. It is used to build distributed
-applications and services. gRPC is based on HTTP/2 and uses protocol buffers ([protobuf](https://protobuf.dev/)) as the
-underlying data serialization framework.
+applications and services. gRPC is based on HTTP/2 protocol and uses protocol buffers
+([protobuf](https://protobuf.dev/)) as the underlying data serialization framework.
 
-:::info
+:::tip
 
 Refer to the [Network Ports](networking-ports.md) documentation for a detailed network architecture diagram with gRPC
 and to learn more about the ports used for communication.
 
 :::
 
+## gRPC and WebSocket
+
+The Palette agent will automatically attempt to connect to the management plane using gRPC through HTTPS using the
+HTTP/2 protocol. In some environments, the network configuration may not allow gRPC traffic to pass through. A common
+scenario is when the network is behind a proxy server that does not support HTTP/2. In this scenario, the Palette agent
+will first attempt to connect to the management plane using HTTP/2. After several failed attempts, the agent will fall
+back to using WebSocket over HTTPS with HTTP/1.1.
+
+The fallback to WebSocket with transcoding occurs automatically and does not require any additional configuration.
+
+### gRPC Transcode
+
+Behind the scenes, when the Palette agent fails to connect with the management plane after a maximum of ten connection
+attempts, the agent initiates the failover to a WebSocket connection and transcodes the gRPC messages with the HTTP/1.1
+protocol.
+
+The Palette agent directs gRPC messages to a freshly started in-memory proxy service, which takes the original gRPC
+request, transcodes it to HTTP/1.1 protocol, and sends it over the WebSocket connection to the management plane. The
+management plane's WebSocket handler will then accept the WebSocket message and transcode it back to the HTTP/2 protocol
+before forwarding it to the gRPC handler. The server will then respond with a gRPC message, which will be transcoded to
+HTTP/1.1 and sent back to the agent over the WebSocket. The agent's in-memory proxy will read the message and transcode
+it back to HTTP/2 and pass it to the agent.
+
+![An architecture diagram of the gRPC over WebSocket flow from a network perspective. Agent to agent proxy, to WebSocket handler, who then forwards the message to the server gRPC handler.](/architecture_grps-proxy_grpc-websocket.webp)
+
+Below is a high-level overview of the order of operations when the Palette agent falls back to using WebSocket:
+
+1. The agent initiates a new gRPC request to the management plane servers that is picked up by the in-memory proxy
+   service.
+2. The agent's in-memory proxy creates a WebSocket connection with the management plane servers.
+3. The management plane server accepts the WebSocket connection
+4. The agent in-memory proxy transcodes the gRPC request on-demand and sends it via the WebSocket connection.
+5. The server's WebSocker handler reads the request off the WebSocket connection and forwards it to the server's gRPC
+   handler.
+6. The gRPC handler processes the request and responds via the same connection. The WebSocket handler sends the response
+   from the gRPC handler back to the agent.
+7. The agent's in-memory proxy reads the response off the WebSocket connection and transcodes it back to HTTP/2 and
+   passes it to the agent.
+
+A more straightforward way to think about the WebSocket transcoding architecture is that network traffic between the
+Palette agent and the management plane uses the WebSocket connection and the HTTP/1.1 protocol. The agent and server are
+still communicating using gRPC, but the messages are transcoded to the HTTP/1.1 protocol between the two entities. Using
+WebSocket and HTTP/1.1 removes issues due to application firewalls or network proxies not supporting the HTTP/2
+protocol. Once the gRPC message is internal to the agent or the server, the HTTP/2 protocol is used for communication.
+
+## gRPC and Proxies
+
+:::info
+
+The following sections provide information about using gRPC with network proxies. These issues are addressed by using
+WebSocket and the HTTP/1.1 protocol as a fallback mechanism. However, if you want to better understand the reasons for
+falling back to a WebSocket connection, the following sections provide more information about challenges with gRPC and
+network proxies. If you want to learn more about gRPC and transcoding, check out the Red Hat article
+[gRPC Anywhere](https://www.redhat.com/en/blog/grpc-anywhere).
+
+:::
+
 When gRPC is used with network proxies, the proxy servers may or may not support gRPC or require additional
 configuration to allow gRPC traffic to pass through. The following table summarizes the different scenarios and whether
-or not the proxy server supports gRPC.
+or not the proxy server supports gRPC. Keep in mind that should the gRPC connection fail, the agent will automatically
+fall back to using WebSocket.
 
 | **Scenario**                                                      | **Description**                                                                                                                              | **Proxy Supported** |
 | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
@@ -33,7 +91,7 @@ or not the proxy server supports gRPC.
 
 The following sections provide more information about gRPC and proxies.
 
-## Proxy Without SSL Bump
+### Proxy Without SSL Bump
 
 Because gRPC is based on HTTP/2, any proxy server that supports the
 [HTTP CONNECT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT) method can be used to forward gRPC
@@ -48,7 +106,7 @@ scenario, the proxy server must support gRPC and may require additional configur
 
 :::
 
-## Proxy With SSL Bump
+### Proxy With SSL Bump
 
 Several vendors provide proxy servers that support gRPC. Some of the vendors may require additional configurations or
 the use of a specific version of the proxy server. We encourage you to review your proxy server documentation for more
@@ -65,7 +123,7 @@ to some vendors' documentation that addresses HTTP/2 and gRPC support.
 
 - [Check Point](https://support.checkpoint.com/results/sk/sk116022)
 
-## Squid Proxy With SSL Bump
+### Squid Proxy With SSL Bump
 
 A common open-source proxy server is [Squid](https://wiki.squid-cache.org). Squid is a caching proxy for the Web
 supporting HTTP, HTTPS, FTP, and more. Squid supports gRPC but requires additional configuration. gRPC with SSL bump

diff --git a/docs/docs-content/security-bulletins/reports/cve-2005-2541.md b/docs/docs-content/security-bulletins/reports/cve-2005-2541.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-8/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -31,7 +31,7 @@ Waiting on a fix from third party mongodb vendor.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -41,3 +41,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added Palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2015-20107.md b/docs/docs-content/security-bulletins/reports/cve-2015-20107.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-08/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -33,7 +33,7 @@ Waiting on a fix from third party mongodb vendor
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -43,3 +43,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2015-8855.md b/docs/docs-content/security-bulletins/reports/cve-2015-8855.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-7/31/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -32,7 +32,7 @@ application.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -42,3 +42,4 @@ Ongoing
 
 - 1.0 07/31/2024 Initial Publication
 - 2.0 08/17/2024 Remediated in Palette VerteX 4.4.14
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2016-1585.md b/docs/docs-content/security-bulletins/reports/cve-2016-1585.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-8/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -30,7 +30,7 @@ Spectro Cloud Official Summary coming soon.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -40,3 +40,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added Palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2018-20225.md b/docs/docs-content/security-bulletins/reports/cve-2018-20225.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-08/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -34,7 +34,7 @@ Waiting on a fix from third party mongodb vendor
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -44,3 +44,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2019-19244.md b/docs/docs-content/security-bulletins/reports/cve-2019-19244.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-08/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -31,7 +31,7 @@ Waiting on a fix from third party mongodb vendor.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -41,3 +41,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2019-9674.md b/docs/docs-content/security-bulletins/reports/cve-2019-9674.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-08/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -31,7 +31,7 @@ Waiting on a fix from third party mongodb vendor
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -41,3 +41,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2019-9923.md b/docs/docs-content/security-bulletins/reports/cve-2019-9923.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-8/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -31,7 +31,7 @@ Waiting on a fix from third party mongodb vendor.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -41,3 +41,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added Palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2019-9936.md b/docs/docs-content/security-bulletins/reports/cve-2019-9936.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-8/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -31,7 +31,7 @@ Waiting on a fix from third party mongodb vendor.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -41,3 +41,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added Palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2019-9937.md b/docs/docs-content/security-bulletins/reports/cve-2019-9937.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-8/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -31,7 +31,7 @@ Waiting on a fix from third party mongodb vendor.
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -41,3 +41,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added Palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2020-35512.md b/docs/docs-content/security-bulletins/reports/cve-2020-35512.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-08/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -33,7 +33,7 @@ Waiting on a fix from third party mongodb vendor
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -43,3 +43,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added palette VerteX 4.4.14 to Affected Products
+- 3.0 9/23/2024 Changed CVE status to Resolved
diff --git a/docs/docs-content/security-bulletins/reports/cve-2021-3737.md b/docs/docs-content/security-bulletins/reports/cve-2021-3737.md
@@ -14,7 +14,7 @@ tags: ["security", "cve"]
 
 ## Last Update
 
-08/16/2024
+9/23/24
 
 ## NIST CVE Summary
 
@@ -32,7 +32,7 @@ Waiting on a fix from third party mongodb vendor
 
 ## Status
 
-Ongoing
+Resolved
 
 ## Affected Products & Versions
 
@@ -42,3 +42,4 @@ Ongoing
 
 - 1.0 08/16/2024 Initial Publication
 - 2.0 08/17/2024 Added palette VerteX 4.4.14 to Affected Products
+- 3.0 09/23/2024 Changed CVE status to Resolved