Skip to content

How to set custom headers using CRDs

How to set custom headers using CRDs (Custom Resource Definitions).

Before you begin

Before getting started, make sure to read our header overview docs to learn about API headers.

Custom Resource Definitions

Headers need to be configured in the API CRD or in the APIVersion CRD.

Info

If you version your APIs, you need to add the headers configuration to the APIVersion CRD.
If you don't version your APIs, please add your header settings to the API CRD.

Examples

---
# Example of an API CRD with custom request and response headers.
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: customer-api
  namespace: apps
  labels:
    area: customers
    module: crm
spec:
  pathPrefix: /customers
  service:
    openApiSpec:
      url: /openapi.yam
      port:
        number: 300
    name: customer-app
    port:
      number: 3000
  headers:
    request:
      set:
        "X-Request-Header": "Custom request header"
        "X-Username": "Somebody"
      delete:
      - "Unnecessary-Request-Header"
    response:
      set:
        "X-Response-Header": "Custom response header"
        "X-API-Server": "Traefik Hub"
      delete:
      - "Secret-Response-Header"
---
# Example of versioning an API using `pathPrefix` for URI path
# and using custom request and response headers.
apiVersion: hub.traefik.io/v1alpha1
kind: APIVersion
metadata:
  name: my-flights-api-v2
  namespace: apps
spec:
  # The API this version is referencing (assumed to be in the same namespace).
  apiName: my-versioned-flights-api
  # SemVer of the release
  release: v2.0.0
  title: "An awesome title for this release, like a cheese name"
  routes:
    # The API will be available on one route using URI path for versioning.
    # Example: curl https://api.example.com/flights/v2.0.0
    - pathPrefix: "/v2.0.0"
  # The path prefix of the route will be removed and not forwarded with the request.
  stripPathPrefix: true
  service:
    name:  flights-svc-v2
    port:
      number: 8080
    openApiSpec:
      path: /api/v2/openapi.json
      port:
        number: 8080
  headers:
    request:
      set:
        "X-Request-Header": "Custom request header"
        "X-Username": "Somebody"
      delete:
      - "Unnecessary-Request-Header"
    response:
      set:
        "X-Response-Header": "Custom response header"
        "X-API-Server": "Traefik Hub"
      delete:
      - "Secret-Response-Header"

What's next