Header Propagation
Overview
Signadot can dynamically route http and gRPC requests to specific versions of the destination Service based on sidecars or a Service Mesh. A specific request header value is used to determine where to route a request. By default requests are routed to the baseline version of Services. If the header contains context for a specific Sandbox, then the request is routed to the forked version of the Service in that Sandbox.
Consider an example where you have Services A, B and C and we have a fork, Service B" in a Sandbox. In the request flow diagram shown below, the dotted orange lines show a request that includes a header with a reference to the Sandbox. This request is routed to the forked version Service B" that's part of the Sandbox. All requests without this header, will flow through Service B.
For this to work, a pre-requisite is for Service A to propagate specific request headers from the incoming requests to all outgoing requests. This is called header propagation. The sections below detail how to implement header propagation in your Services.
Implementing Header Propagation
Header propagation is commonly implemented using distributed tracing libraries. Signadot supports the following header formats in HTTP 1/2 and gRPC and the corresponding tracing libraries.
OpenTelemetry Tracing
There are two mechanisms of propagation that are supported from the OpenTelemetry specification:
In both of these cases, a key named sd-sandbox
is used to persist information pertaining to Sandboxes. If you're making use of OpenTelemetry instrumentation in your services, baggage
and tracestate
headers are propagated automatically.
Jaeger Tracing
A header named uberctx-sd-sandbox
is expected to be propagated by your services. If you're making use of Jaeger instrumentation in your services, headers in this format are propagated automatically.
Datadog Tracing
A header named ot-baggage-sd-sandbox
is expected to be propagated by your services. If you're using Datadog's Go language instrumentation libraries, headers in this format are propagated automatically. Support in other languages depends on the library being used and the mode in which it's used.
Custom Instrumentation
If you are not using the above libraries, we recommend that you make use of the baggage
header as described in the W3C Baggage Specification. Services would need to propagate this header from each incoming request to any outgoing requests the original handler makes.
The headers that will be set on the entry-point service when using a Signadot preview URL will be in the following format and the application must propagate this header as-is (or with modifications according to the W3C spec) to other services in the system.
baggage: sd-sandbox=<sandbox-id>
Header Propagation Examples
Sample code for implementing header propagation in various languages using OpenTelemetry can be found in this GitHub Repository.