Request header rules

In this article, request header configuration is explained. For response header configuration, see Response header rules.

General tips for working with CRs

  • CLI:
  • Use kubectl explain <replace with CRD name> --recursive to list all available options and the YAML structure.
  • Check the CRD description texts with kubectl explain <replace with CRD name and path> of the available options for more details.
  • API Reference documentation:
  • Click on the link to open the CR-related documentation in a new browser tab or window: CRD Reference documentation. See also the API Reference documentation links at the end article.

Allow request headers

To allow a request header, the header must either be in the built-in standardHeaders allow list or configured as a custom rule in the custom section. All other request headers will be removed and not forwarded to the upstream container.

Example:

...
  request:   
    allow:  
      matchingHeaders:  
        custom:
          - name: Allow X-CSRF-Token header
            headers:
              - name:
                  matcher:
                    exact: X-CSRF-TOKEN
...

The matchingHeaders option is the default. When enabled, the built-in list standardHeaders allows the predefined typical headers only. Additional custom rules can be configured to forward other headers to the upstream container as in our example.

  • Instead of using the default matchingHeaders option in conjunction with custom rules to supplement the built-in rules, the option allHeaders: {} can be used to forward all headers (unfiltered).
  • When using this setting, add custom rules to the header remove section, to remove certain headers from the upstream to avoid possible attacks.

See also the API Reference documentation link at the end of this article.

Remove request headers

With alternativeForwardedHeaders: true, predefined alternative headers are removed from the request. These alternative headers may potentially be misused to attack the upstream container. Additional custom rules can be configured to remove other headers from the request.

Example:

...
  request:   
    remove:  
      builtIn:  
        alternativeForwardedHeaders: true  
      custom: 
      - name: Remove X-Forwarded-Host
        headers: 
        - name: 
            matcher: 
              exact: X-Forwarded-Host
...

In our example, the alternativeForwardedHeaders and a custom header rule that matches to X-Forwarded-Host are removed from incoming requests.

See also the API Reference documentation link at the end of this article.

Add request headers

To add a header to a request, the header must be configured as a custom rule in the custom section.

Example:

... 
  request:  
    add: 
      custom: 
        - name: Add headers with TLS information of the downstream connection 
          headers: 
            - name: X-TLS-DOWNSTREAM-PEER-CERT 
              value: "%DOWNSTREAM_PEER_CERT%"
          mode: AddIfAbsent 
...

Our example adds the header X-TLS-DOWNSTREAM-PEER-CERT to requests if this header is missing (mode: AddIfAbsent).

See also the API Reference documentation link at the end of this article.