Query Parameter

The Query Parameter middleware allows manipulation of query parameters in HTTP requests before forwarding them to services.

The middleware supports four types of operations: set, append, remove, and rename. Only one operation type can be used per middleware instance.

---

Configuration Examples

Set Operation

Setting api_key to static value and version from X-API-Version header

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: query-set
  namespace: apps
spec:
  plugin:
    queryParam:
      set:
        - name: api_key
          value: "12345"
        - name: version
          fromHeader: X-API-Version

Append Operation

Appending gateway-processed tag and features from X-Feature-Flags header

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: query-append
  namespace: apps
spec:
  plugin:
    queryParam:
      append:
        - name: tags
          value: "gateway-processed"
        - name: features
          fromHeader: X-Feature-Flags

Remove Operation

Removing debug and internal_flag parameters before forwarding

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: query-remove
  namespace: apps
spec:
  plugin:
    queryParam:
      remove:
        - name: debug
        - name: internal_flag

Rename Operation

Renaming old_param to new_param and legacy_filter to filter

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: query-rename
  namespace: apps
spec:
  plugin:
    queryParam:
      rename:
        - from: old_param
          to: new_param
        - from: legacy_filter
          to: filter

Configuration Options

Field	Description	Default	Required
set	List of set operations to perform. Each operation sets the query parameter to the specified value (adds if not present, replaces if exists). More information here.	[]	No
append	List of append operations to perform. Each operation adds the query parameter to the existing ones. More information here.	[]	No
remove	List of remove operations to perform. Each operation removes the specified query parameter. More information here.	[]	No
rename	List of rename operations to perform. Each operation renames a query parameter. More information here.	[]	No

Operation Types

Set Operations

Set operations set query parameters to specified values. If the parameter doesn't exist, it's added. If the parameter already exists, all existing values are replaced with the new value.

Field	Description	Default	Required
name	Name of the query parameter to set.	""	Yes
value	Static value to set for the parameter.	""	No
fromHeader	HTTP header name to extract the value from.	""	No

Value Source Constraint - Each operation must use either value OR fromHeader

Each individual set operation must specify either value OR fromHeader, but not both. However, you can have multiple operations where some use value and others use fromHeader.

# ✅ Valid - different operations use different sources
queryParam:
  set:
    - name: api_key
      value: "12345"           # Uses static value
    - name: version
      fromHeader: X-API-Version # Uses header value

# ❌ Invalid - same operation has both sources
queryParam:
  set:
    - name: api_key
      value: "12345"           # Cannot have both
      fromHeader: X-API-Key    # Cannot have both

Append Operations

Append operations add query parameters to the existing ones. If the parameter already exists, the new value is added alongside the existing values.

Field	Description	Default	Required
name	Name of the query parameter to append.	""	Yes
value	Static value to append for the parameter.	""	No
fromHeader	HTTP header name to extract the value from.	""	No

Value Source Constraint - Each operation must use either value OR fromHeader

Each individual append operation must specify either value OR fromHeader, but not both. However, you can have multiple operations where some use value and others use fromHeader.

# ✅ Valid - different operations use different sources
queryParam:
  append:
    - name: tags
      value: "gateway-processed"  # Uses static value
    - name: features
      fromHeader: X-Feature-Flags # Uses header value

# ❌ Invalid - same operation has both sources
queryParam:
  append:
    - name: tags
      value: "gateway-processed"  # Cannot have both
      fromHeader: X-Tags          # Cannot have both

Remove Operations

Remove operations delete query parameters from the request.

Field	Description	Default	Required
name	Name of the query parameter to remove.	""	Yes

Rename Operations

Rename operations change the name of query parameters while preserving their values. If the source parameter has multiple values, all values are transferred to the new parameter name.

Examples:

• Renaming old_param to new_param in a request with old_param=value&keep=other results in keep=other&new_param=value
• Renaming old_param to new_param in a request with old_param=value-1&old_param=value-2 results in new_param=value-1&new_param=value-2

Field	Description	Default	Required
from	Original name of the query parameter to rename.	""	Yes
to	New name for the query parameter.	""	Yes

Parameter Format Support

The Query Parameter middleware supports various parameter formats for all operations:

• Standard repeated parameters: foo=bar&foo=baz - handled according to each operation type
• Bracket notation: foo[]=bar&foo[]=baz - treated as literal parameter names (not parsed as arrays)
• Complex nested parameters: users[0][tags]=value - treated as literal parameter names

CSV-style values

CSV-style values (foo=bar,qux) are not supported as they're not part of the URL standard.

Important Notes

• Only one operation type (set, append, remove, or rename) can be specified per middleware instance
• At least one operation must be specified
• For set and append operations, either value or fromHeader must be specified, but not both
• Missing headers referenced in fromHeader result in empty string values
• The Host header cannot be extracted using fromHeader. Use alternative headers like X-Forwarded-Host when you need hostname information.
• The middleware handles URL encoding and decoding of parameter names and values
• Complex parameter names (including dots, brackets, and non-alphanumeric characters) are supported
• Multiple values for the same parameter are handled according to the operation type