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:

Allow ConfigurationsDeny ConfigurationsMiscellaneous

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.

[1]

The client requests do not need to include a baggage header. If clients send only non-baggage request headers for application-defined properties (as determined by ESS configuration), ESS creates a baggage for propagation within its system. However, if a baggage request header exists, ESS adds the non-baggage requests headers (if any, as determined by ESS configuration) to the baggage, and propagates the enhanced baggage.

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.