Manage Application-Defined Metadata Propagation#

Starting in 2.2, ESS adds support for application-defined metadata/properties; specifically, ESS adds support for baggage HTTP header. These application-defined properties can be included in audit messages and log messages as well as returned as response headers. ESS further expands on this support by providing configuration to add non-baggage request headers to the baggage for propagation within its system. [1]

As part of its support for application-defined metadata propagation, ESS provides the following configurations to customize the propagation:

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW

Adds specified non-baggage request headers to the baggage for propagation (unless also specified in the corresponding *_DENY configuration); i.e., support propagation of non-baggage headers as application-defined properties.

This configuration is case-insensitive.

INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW

Determines which propagated properties can be returned as response headers (unless also specified in the corresponding *_DENY configuration). This configuration is case-sensitive to the entries in the propagated baggage.

Tip

  • To return a propagated property that was added to the baggage via INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW, ensure that the cases of these properties match.

  • When returning application-properties as response headers, you may need to update QUARKUS_HTTP_CORS_EXPOSED_HEADERS to extend the list of CORS-safelisted response headers.

INRUPT_LOGGING_REQUEST_METADATA_ALLOW

Determines which propagated properties can be included in associated log messages (unless also specified in the corresponding *_DENY configuration). This configuration is case-sensitive to the propagated baggage entries.

Tip

To include a propagated property that was added to the baggage via INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW, ensure that the cases of these properties match.

INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW

Determines which propagated properties can be included in associated audit events (unless also specified in the corresponding *_DENY configuration). This configuration is case-sensitive to the propagated baggage entries.

Tip

To include a propagated property that was added to the baggage via INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW, ensure that the cases of these properties match.

Example Customization#

The following example configuration updates:

  • INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW to include the client request x-correlation-id, x-request-id, and my-client-version headers as baggage entries.

  • INRUPT_LOGGING_REQUEST_METADATA_ALLOW to include the propagated x-correlation-id, x-request-id, and my-client-version in the associated log messages.

  • INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW to include the propagated x-correlation-id, x-request-id, and my-client-version in the associated audit events.

  • INRUPT_LOGGING_REQUEST_METADATA_ALLOW to return the propagated x-correlation-id and x-request-id as response headers (and not``my-client-version``).

Tip

INRUPT_LOGGING_REQUEST_METADATA_ALLOW, INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW, and INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW are case-sensitive to the entries in the propagated baggage. If the propagated baggage includes properties from INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW configuration, ensure that the cases of those properties match.

  1. Go to your ESS installation directory:

    cd ${HOME}/ess
    
  2. Modify the kustomization.yaml (i.e., step 3 of the Applying Your Customizations procedure).

    Specifically, add the highlighted content to the kustomization.yaml file under the patches key:

    Tip

    If patches list does not exist in kustomization.yaml, add the key patches as well.

    # kustomization.yaml in your ESS installation directory
    
    # ...  Preceding content omitted for brevity 
    # ...
    
    patches:
      - target:
          kind: Deployment
          labelSelector: quarkus=true
        patch: |-
          - op: add
            path: /spec/template/spec/containers/0/env/-
            value:
              #Adds the following request headers to the `baggage` for propagation
              name: INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW
              value: "x-correlation-id,x-request-id,my-client-version"
          - op: add
            path: /spec/template/spec/containers/0/env/-
            value:
              #Return the following propagated properties as response headers
              name: INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_ALLOW
              value: "x-correlation-id,x-request-id"
          - op: add
            path: /spec/template/spec/containers/0/env/-
            value:
              #Include the following propagated properties in log messages
              name: INRUPT_LOGGING_REQUEST_METADATA_ALLOW
              value: "x-correlation-id,x-request-id,my-client-version,"
          - op: add
            path: /spec/template/spec/containers/0/env/-
            value:
              #Include the following propagated properties in audit events
              name: INRUPT_AUDIT_PRODUCER_REQUEST_METADATA_ALLOW
              value: "x-correlation-id,x-request-id,my-client-version"
    

    Tip

    When returning application-defined properties as response headers, you may need to update QUARKUS_HTTP_CORS_EXPOSED_HEADERS to extend the list of CORS-safelisted response headers.

  3. Continue with the rest of the Applying Your Customizations procedure.