Merge branch 'v1.17.x' into doc-fixes-1.17

solo-io · Nov 15, 2024 · 019841b · 019841b
2 parents 7c93fbc + 051b0ca
commit 019841b
Show file tree

Hide file tree

Showing 160 changed files with 4,869 additions and 1,333 deletions.
diff --git a/Makefile b/Makefile
@@ -54,7 +54,7 @@ SOURCES := $(shell find . -name "*.go" | grep -v test.go)
 # for more information, see https://github.com/solo-io/gloo/pull/9633
 # and
 # https://soloio.slab.com/posts/extended-http-methods-design-doc-40j7pjeu
-ENVOY_GLOO_IMAGE ?= quay.io/solo-io/envoy-gloo:1.30.6-patch2
+ENVOY_GLOO_IMAGE ?= quay.io/solo-io/envoy-gloo:1.30.6-patch5
 LDFLAGS := "-X github.com/solo-io/gloo/pkg/version.Version=$(VERSION)"
 GCFLAGS ?=
 

diff --git a/changelog/v1.17.16/doc-fixes.yaml b/changelog/v1.17.16/doc-fixes.yaml
@@ -1,5 +1,5 @@
 changelog:
   - type: NON_USER_FACING
-    description: >- 
-      Backports of doc fixes.
+    description: >-
+      Weekly doc fixes, including API proto doc format changes and an update to the copy-docs workflow.
       skipCI-kube-tests:true
diff --git a/changelog/v1.17.16/early-header-manipulation.yaml b/changelog/v1.17.16/early-header-manipulation.yaml
@@ -0,0 +1,22 @@
+changelog:
+  - type: FIX
+    issueLink: https://github.com/solo-io/gloo/issues/9604
+    description: >-
+      Added support for early header manipulation on Gateways.
+      This feature allows headers to be manipulated before significant processing 
+      and routing decisions.
+      It affords the ability to add or remove headers that affect request processing
+      and can be used to implement override headers.
+      This can be configured by setting the
+      `gateway.spec.httpGateway.options.httpConnectionManagerSettings.earlyHeaderMutation` field.
+      The headersToAdd field will add key-value pair headers to the request if not already 
+      present or overwrite them unless append is set to true.
+      The headersToRemove field removes the specified headers and is processed after 
+      the headers have been added.
+  - type: DEPENDENCY_BUMP
+    dependencyOwner: solo-io
+    dependencyRepo: envoy-gloo
+    dependencyTag: 1.30.6-patch5
+    description: >
+      Bumped the Envoy version to 1.30.6-patch5
+      Needed the Early Header Manipulation extensions enabled.
diff --git a/changelog/v1.17.16/opentelemetry-span-name.yaml b/changelog/v1.17.16/opentelemetry-span-name.yaml
@@ -0,0 +1,28 @@
+changelog:
+  - type: DEPENDENCY_BUMP
+    dependencyOwner: solo-io
+    dependencyRepo: envoy-gloo
+    dependencyTag: v1.30.6-patch3
+    description: >
+      Update envoy-gloo to enable support for setting span names via the transformation filter.
+  - type: NON_USER_FACING
+    description: >-
+      Change the image used in our kubernetes/e2e tests from kennship/http-echo
+      to jmalloc/echo-server. This image supports http/2. It is also smaller and
+      faster, which may speed up our e2e tests and reduce CI costs.
+      kennship/http-echo is also an archived project that appears to not have
+      been updated in 6 years.
+
+      This change was also made necessary by the fact that the test was timing
+      out and failing because it was taking too long to download the
+      `kennship/http-echo` image. See
+      [here](https://github.com/solo-io/gloo/actions/runs/11693450838/job/32565060282?pr=10123)
+      for a sample run.
+  - type: FIX
+    issueLink: https://github.com/solo-io/gloo/issues/9848
+    resolvesIssue: false
+    description: >-
+      Enable modifying the span name for tracing purposes using InjaTemplates
+      in the transformation filter. More information on OpenTelemetry span
+      names can be found here:
+      https://opentelemetry.io/docs/specs/semconv/http/http-spans/
diff --git a/changelog/v1.17.16/translator-stopwatches-1.17.x.yaml b/changelog/v1.17.16/translator-stopwatches-1.17.x.yaml
@@ -0,0 +1,9 @@
+changelog:
+  - type: FIX
+    issueLink: https://github.com/solo-io/gloo/issues/10278
+    resolvesIssue: true
+    description: >-
+      Add metrics for translatation timing and time for taken to sync served xDS entries.
+
+      skipCI-kube-tests
+      skipCI-docs-build
diff --git a/docs/content/guides/observability/tracing/otel.md b/docs/content/guides/observability/tracing/otel.md
@@ -8,6 +8,8 @@ Enable [OpenTelemetry](https://opentelemetry.io/) (OTel) tracing capabilities to
 
 OTel provides a standardized protocol for reporting traces, and a standardized collector through which to recieve metrics. Additionally, OTel supports exporting metrics to several types of distributed tracing platforms. For the full list of supported platforms, see the [OTel GitHub respository](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter).
 
+## Set up OpenTelemetry tracing
+
 To get started, deploy an OTel collector and agents to your Gloo Gateway cluster to trace requests, and modify your gateway proxy with the OTel tracing configuration. Then, use a tracing provider to collect and visualize the sampled spans.
 
 {{% notice note %}}
@@ -165,4 +167,99 @@ This guide uses the Zipkin tracing platform as an example to show how to set up
 
 9. [Open the Zipkin web interface.](http://localhost:9411/zipkin/)
 
-10. In the Zipkin web interface, click **Run query** to view traces for your requests, and click **Show** to review the details of the trace.
+10. In the Zipkin web interface, click **Run query** to view traces for your requests, and click **Show** to review the details of the trace.
+
+## Customize the span name
+
+Gloo supports changing the default span name by using the transformation filter. The following steps show an example name change.
+
+1. Change the span name by modifying your Virtual Service. The following sample configuration in a Virtual Service changes the name to the host header in the `text: '{{header("Host")}}'` field. Note because the `spanTransformer.name` field is an Inja template, you can use header values and any other macro logic that is supported in transformations. For more information, see the [transformation documentation]({{< versioned_link_path fromRoot="/guides/traffic_management/request_processing/transformations/" >}}).
+   {{< highlight yaml "hl_lines=16-24" >}}
+   apiVersion: gateway.solo.io/v1
+   kind: VirtualService
+   metadata:
+     name: default
+     namespace: gloo-system
+   spec:
+     virtualHost:
+       domains:
+         - '*'
+       routes:
+         - matchers:
+            - prefix: /
+           directResponseAction:
+             status: 200
+             body: 'hello world'
+       options:
+         stagedTransformations:
+           regular:
+             requestTransforms:
+               - requestTransformation:
+                   transformationTemplate:
+                     spanTransformer:
+                       name:
+                         text: '{{header("Host")}}'
+   {{< /highlight >}}
+
+2. After you apply the updated Virtual Service, you can verify that the span name in the OpenTelemetry collector now is set to the value of the `Host` header by sending a curl request.
+   ```sh
+   curl -H "Host: my-hostname" http://localhost:8080
+   ```
+   In the output, verify that the following span appears:
+   ```
+   2024-11-04T20:18:08.656Z	info	TracesExporter	{"kind": "exporter", "data_type": "traces", "name": "logging", "#spans": 1}
+   2024-11-04T20:18:08.656Z	info	ResourceSpans #0
+   Resource SchemaURL: 
+   Resource attributes:
+        -> service.name: Str(gateway-proxy)
+   ScopeSpans #0
+   ScopeSpans SchemaURL: 
+   InstrumentationScope  
+   Span #0
+       Trace ID       : e42f4fa3ba873eefeb26b3b16112dc18
+       Parent ID      : 
+       ID             : 21547202617791ee
+       Name           : my-hostname
+       Kind           : Server
+       Start time     : 2024-11-04 20:18:06.697813 +0000 UTC
+       End time       : 2024-11-04 20:18:06.699024 +0000 UTC
+       Status code    : Unset
+       Status message : 
+   Attributes:
+        -> node_id: Str(gateway-proxy-577544cdcd-c6rvm.gloo-system)
+        -> zone: Str()
+        -> guid:x-request-id: Str(d1c5b217-e87b-95ae-b449-56c40eaa879c)
+        -> http.url: Str(http://echo-server/)
+        -> http.method: Str(GET)
+        -> downstream_cluster: Str(-)
+        -> user_agent: Str(curl/7.88.1)
+        -> http.protocol: Str(HTTP/1.1)
+        -> peer.address: Str(127.0.0.1)
+        -> request_size: Str(0)
+        -> response_size: Str(313)
+        -> component: Str(proxy)
+        -> upstream_cluster: Str(echo-server_gloo-system)
+        -> upstream_cluster.name: Str(echo-server_gloo-system)
+        -> http.status_code: Str(200)
+        -> response_flags: Str(-)
+   	{"kind": "exporter", "data_type": "traces", "name": "logging"}
+   ```
+
+Note that in this example, the span name was modified at the level of the virtual host, so all routes under the virtual host will exhibit the same span naming pattern. However, it is also possible to override this logic on a _per-route_ basis using the `routeDescriptor` field:
+
+```
+routes:
+- matchers:
+   - prefix: /route2
+  options:
+    autoHostRewrite: true
+    tracing:
+      routeDescriptor: CUSTOM_ROUTE_DESCRIPTOR
+  routeAction:
+    single:
+      upstream:
+        name: echo-server
+        namespace: gloo-system
+```
+
+When this configuration is applied, requests for the `/route2` endpoint will result in spans being reported to the OpenTelemetry collector with the span name set to `"CUSTOM_ROUTE_DESCRIPTOR"`. However, it is also important to note that `routeDescriptor` can only set a static override value and does not support Inja transformation templates.