HTTP tunneling documentation improvements (#10706)

Co-authored-by: Andy Fong <[email protected]>

Author: ryanrolds

changelog/v1.19.0-beta14/improve-http-tunneling-docs.yaml

@@ -0,0 +1,7 @@
+changelog:
+- type: FIX
+  description: >-
+    Improved HTTP tunneling documentation and added note about remote JWKS configuration
+    using an upstream with `httpProxyHostname` requiring additional configuration.
+  issueLink: https://github.com/solo-io/solo-projects/issues/7497
+  resolvesIssue: false

docs/content/reference/api/github.com/solo-io/gloo/projects/gloo/api/v1/enterprise/options/jwt/jwt.proto.sk.md

@@ -124,6 +124,9 @@ message RemoteJwks {
     // This is used to set the host and path in the request
     string url = 1;
     // The Upstream representing the Json Web Key Set server
+    //
+    // Note: Setting this to an upstream using an HTTP tunnel (`httpProxyHostname`)
+    // requires also using that upstream in a route.
     core.solo.io.ResourceRef upstream_ref = 2;
     // Duration after which the cached JWKS should be expired. 
     // If not specified, default cache duration is 5 minutes.

docs/content/reference/api/github.com/solo-io/gloo/projects/gloo/api/v1/upstream.proto.sk.md

@@ -139,8 +139,10 @@ message Upstream {
     // See [RFC7540, sec. 8.1](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1) for details.
     google.protobuf.BoolValue override_stream_error_on_invalid_http_message = 26;
 
-    // Tells envoy that the upstream is an HTTP proxy (e.g., another proxy in a DMZ) that supports HTTP Connect.
-    // This configuration sets the hostname used as part of the HTTP Connect request.
+    // Tells Envoy that the upstream is an HTTP proxy that supports [HTTP CONNECT method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT).
+    // The hostname is the destination of the tunnel established by the proxy.
+    // Some Envoy Command Operators (.e.g `%REQUESTED_SERVER_NAME%`) are supported allowing for dynamic destinations.
+    //
     // For example, setting to: host.com:443 and making a request routed to the upstream such as `curl <envoy>:<port>/v1`
     // would result in the following request:
     //
@@ -152,7 +154,7 @@ message Upstream {
     //    user-agent: curl/7.64.1
     //    accept: */*
     //
-    // Note: if setting this field to a hostname rather than IP:PORT, you may want to also set `host_rewrite` on the route
+    // Note: If setting this field to a hostname rather than IP:PORT, you may want to also set `host_rewrite` on the route
     google.protobuf.StringValue http_proxy_hostname = 21;
 
     // HttpConnectSslConfig contains the options necessary to configure envoy to originate TLS to an HTTP Connect proxy.