Manage Application-Defined Metadata Propagation

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.

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.

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

Allow Configurations

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. 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.

Deny Configurations

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_DENY Excludes specified non-baggage request headers from being added to the baggage. This configuration is case-insensitive.
INRUPT_REQUEST_METADATA_REFLECTOR_HEADER_DENY Excludes propagated properties from returning as response headers. This configuration is case-sensitive to the entries in the propagated baggage. Tip To exclude 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_LOGGING_REQUEST_METADATA_DENY Excludes propagated properties from being included in associated log messages. This configuration is case-sensitive to the propagated baggage entries. Tip To exclude 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_DENY Determines which propagated properties are included in associated audit events. This configuration is case-sensitive to the propagated baggage entries. Tip To exclude a propagated property that was added to the baggage via INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_ALLOW , ensure that the cases of these properties match.

Miscellaneous

INRUPT_REQUEST_METADATA_PROPAGATOR_HEADER_OVERRIDES Determines, in cases of a property being defined both as a header and as a baggage entry, whether to keep the entry or update/override it with the header value. The default is to keep the baggage entry as is. See Duplicate Property Definition for more information.

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 .

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