Skip to content

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Request IDs

Page as Markdown

Keep, generate, or stop generating the x-request-id header that the gateway proxy adds to requests.

Control how the gateway proxy generates and forwards the x-request-id header.

About request IDs

The gateway proxy adds an x-request-id header with a UUID to each request before it forwards the request to the backend. You can use the request ID to correlate the logs of a single request across your gateway proxy and backend services, such as with the %REQ(X-REQUEST-ID)% command in access logs. If you set up tracing, the gateway proxy also uses the request ID to make trace sampling decisions.

By default, the gateway proxy generates a new request ID for every request from a downstream client. If the client already sends an x-request-id header, the gateway proxy replaces it with a new value.

You can use the following settings in the spec.default.httpSettings section of a ListenerPolicy to change this behavior.

SettingDescription
preserveExternalRequestIdSet to true to keep the x-request-id header that a client sends. The gateway proxy still generates a request ID for requests without an x-request-id header. Defaults to false.
generateRequestIdSet to false to stop generating request IDs, such as to save the cost of generating a UUID for each request in high-throughput setups. Requests without an x-request-id header are forwarded without one, and an x-request-id header that a client sends is kept. If you set up tracing, the gateway proxy does not trace requests without an x-request-id header unless you also set uuidRequestIdConfig.useRequestIdForTraceSampling to false. Defaults to true.
uuidRequestIdConfig.packTraceReasonWhen tracing is set up, the gateway proxy can change one character of the request ID to record the trace sampling decision in the UUID. Set to false to forward request IDs unchanged, such as to keep the exact UUIDs that an external system sets. Without the sampling decision in the request ID, stable sampling of traces and access logs no longer works, and only random sampling is possible. Defaults to true.
uuidRequestIdConfig.useRequestIdForTraceSamplingWhether the gateway proxy uses the request ID to make trace sampling decisions. When true, the sampling decision is consistent for all requests with the same request ID. Defaults to true.

Note

If you set useRemoteAddress to false in your ListenerPolicy, the gateway proxy keeps the x-request-id header that a client sends, even if you do not set preserveExternalRequestId. The gateway proxy replaces request IDs only for requests that it treats as coming from external clients, which requires useRemoteAddress to be true, the default setting.

Before you begin

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. Get the external address of the gateway and save it in an environment variable.

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
    echo $INGRESS_GW_ADDRESS  

Default behavior

Send a request to the httpbin app with the x-request-id: my-request-123 header. Verify that the X-Request-Id header that the httpbin app receives has a new UUID instead of the value that you sent.

curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \
  -H "x-request-id: my-request-123"

Example output:

{
  "headers": {
    "Accept": [
      "*/*"
    ],
    "Host": [
      "www.example.com"
    ],
    "User-Agent": [
      "curl/8.7.1"
    ],
    "X-Envoy-Expected-Rq-Timeout-Ms": [
      "15000"
    ],
    "X-Envoy-External-Address": [
      "127.0.0.1"
    ],
    "X-Forwarded-For": [
      "10.244.0.7"
    ],
    "X-Forwarded-Proto": [
      "http"
    ],
    "X-Request-Id": [
      "6e2e78c8-17bd-4340-846b-525ae7dc6c9b"
    ]
  }
}

Keep request IDs from clients

If a client or a proxy in front of the gateway proxy already sets request IDs, keep them so that you can correlate the request across all systems.

  1. Create a ListenerPolicy that sets preserveExternalRequestId to true.

    kubectl apply -f- <<EOF
    apiVersion: gateway.kgateway.dev/v1alpha1
    kind: ListenerPolicy
    metadata:
      name: request-id
      namespace: kgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: http
      default:
        httpSettings:
          preserveExternalRequestId: true
    EOF

    Review the following table to understand this configuration. For more information about the available fields, see the API reference.

    SettingDescription
    spec.targetRefsThe Gateway that this policy applies to. The policy applies to all HTTP and HTTPS listeners on the Gateway.
    spec.default.httpSettings.preserveExternalRequestIdSet to true to keep the x-request-id header that a client sends instead of replacing it with a new value.
  2. Repeat the request with the x-request-id: my-request-123 header. Verify that the httpbin app receives the request ID that you sent.

    curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \
      -H "x-request-id: my-request-123"

    Example output:

    ...
        "X-Request-Id": [
          "my-request-123"
        ]
    ...
    
  3. Send a request without an x-request-id header. Verify that the gateway proxy still generates a request ID.

    curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com"

    Example output:

    ...
        "X-Request-Id": [
          "fc7f8d46-069c-4575-94ea-6ca69c01c7a1"
        ]
    ...
    

Stop generating request IDs

Use generateRequestId: false to stop the gateway proxy from generating request IDs, such as when you handle high-throughput traffic and do not use request IDs for log correlation. If you set up tracing, the gateway proxy does not trace requests without an x-request-id header unless you also set uuidRequestIdConfig.useRequestIdForTraceSampling to false.

  1. Update the ListenerPolicy to set generateRequestId to false. This replaces the policy from the previous section, so preserveExternalRequestId is no longer set.

    kubectl apply -f- <<EOF
    apiVersion: gateway.kgateway.dev/v1alpha1
    kind: ListenerPolicy
    metadata:
      name: request-id
      namespace: kgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: http
      default:
        httpSettings:
          generateRequestId: false
    EOF

    Review the following table to understand this configuration. For more information about the available fields, see the API reference.

    SettingDescription
    spec.targetRefsThe Gateway that this policy applies to. The policy applies to all HTTP and HTTPS listeners on the Gateway.
    spec.default.httpSettings.generateRequestIdSet to false to stop generating request IDs. An x-request-id header that a client sends is still kept.
  2. Send a request without an x-request-id header. Verify that the httpbin app does not receive an X-Request-Id header.

    curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com"

    Example output:

    {
      "headers": {
        "Accept": [
          "*/*"
        ],
        "Host": [
          "www.example.com"
        ],
        "User-Agent": [
          "curl/8.7.1"
        ],
        "X-Envoy-Expected-Rq-Timeout-Ms": [
          "15000"
        ],
        "X-Envoy-External-Address": [
          "127.0.0.1"
        ],
        "X-Forwarded-For": [
          "10.244.0.7"
        ],
        "X-Forwarded-Proto": [
          "http"
        ]
      }
    }
    

Keep request IDs unchanged with tracing

When you set up tracing, the gateway proxy records its trace sampling decision in the request ID by changing the version character of the UUID. For example, if you keep request IDs from clients, a sampled request with the 1b4e28ba-2fa1-41d2-883f-0016d3cca427 request ID is forwarded with the 1b4e28ba-2fa1-91d2-883f-0016d3cca427 request ID. If your systems require the exact UUID that a client sends, set packTraceReason to false.

  1. Update the ListenerPolicy to keep request IDs from clients and to not change them.

    kubectl apply -f- <<EOF
    apiVersion: gateway.kgateway.dev/v1alpha1
    kind: ListenerPolicy
    metadata:
      name: request-id
      namespace: kgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: http
      default:
        httpSettings:
          preserveExternalRequestId: true
          uuidRequestIdConfig:
            packTraceReason: false
    EOF
    Review the following table to understand this configuration.
    SettingDescription
    spec.default.httpSettings.preserveExternalRequestIdKeep the x-request-id header that a client sends.
    spec.default.httpSettings.uuidRequestIdConfig.packTraceReasonSet to false to forward request IDs without recording the trace sampling decision in them.
    spec.default.httpSettings.uuidRequestIdConfig.useRequestIdForTraceSamplingNot set in this example, so it defaults to true.
  2. Port-forward the gateway proxy on port 19000 to open the Envoy admin interface.

    kubectl port-forward deploy/http -n kgateway-system 19000
  3. In the Envoy configuration, verify that the request ID extension is configured. Alternatively, you can open the Envoy admin interface and look for the request_id_extension setting in the config dump.

    curl -s localhost:19000/config_dump | jq '[.. | objects | select(has("request_id_extension")) | {preserve_external_request_id, request_id_extension}]'

    Example output:

    [
      {
        "preserve_external_request_id": true,
        "request_id_extension": {
          "typed_config": {
            "@type": "type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig",
            "pack_trace_reason": false,
            "use_request_id_for_trace_sampling": true
          }
        }
      }
    ]
    

Cleanup

You can remove the resources that you created in this guide.
kubectl delete listenerpolicy request-id -n kgateway-system --ignore-not-found
Was this page helpful?