Skip to content

Redirect examples ​

Normally omit backend.type: Ingress infers redirect when only backend.redirect is set. examples/ssl-tls/route-redirect.yaml pairs type: redirect with omission on two hosts so you can compare. Add backend.type: redirect only if ingress validate reports ambiguity. examples/redirect/capture-and-mixed.yaml also mixes explicit backend.type on some backends with omission elsewhere. Do not combine backend.service or backend.handler with backend.redirect on the same backend—use separate paths entries when one host needs both proxy and redirect (see below).

For global HTTP→HTTPS (before routing), use https.redirect_from_http — see SSL/TLS.

Sources: examples/redirect/ and examples/ssl-tls/route-redirect.yaml for a minimal host redirect.

Redirect status (duration + preserve_request) ​

Use duration (temporary | permanent) and preserve_request (true | false) to pick 302 / 301 / 307 / 308 without memorizing status codes. Legacy permanent / with_origin_method_and_body still work; prefer the new fields.

durationpreserve_requestStatus
temporaryfalse302
permanentfalse301
temporarytrue307
permanenttrue308
yaml
version: v1
port: 8080

# Redirect status codes (scheme A: duration + preserve_request).
# Each host returns a different status when probed with GET.

rules:
  - host: r302.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: temporary
  - host: r301.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: permanent
  - host: r307.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: temporary
        preserve_request: true
  - host: r308.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: permanent
        preserve_request: true

Each host in the sample returns a different status on GET. preserve_request: true is for POST/API redirects where method and body must survive the redirect.

Path regex redirect ​

paths[].path is a Go regexp (compiled with an implicit leading ^). Path-level backend.redirect uses the same matcher as service/handler paths. Use ${path.N} for capture groups in redirect.url; add $ when you need an exact path match. A path-level url is used as configured, so trailing request path/query are dropped unless the path backend sets preserve_path: true (host-level redirects always keep them).

yaml
version: v1
port: 8080

rules:
  - host: redirect.example.com
    backend:
      redirect:
        url: https://new.example.com
        permanent: true
    paths:
      # Path-level redirects use redirect.url as configured: the request path/query are not appended.
      # Prefix match: /legacy/* → fixed archive URL (explicit path in url).
      - path: /legacy/
        backend:
          redirect:
            url: https://archive.example.com/docs
            permanent: true
      # Path-level default: url has no path → Location is exactly https://landing.example.com
      # (the /root-only/... request path and query are dropped).
      - path: /root-only/
        backend:
          redirect:
            url: https://landing.example.com
      # preserve_path: true restores the host-level whole-site semantics for this path:
      # /mirror/docs?lang=en → https://mirror.example.com/mirror/docs?lang=en
      - path: /mirror/
        backend:
          redirect:
            url: https://mirror.example.com
            preserve_path: true
      # Regex capture: /go/{segment} → templated host from ${path.1}.
      - path: /go/([^/]+)$
        backend:
          redirect:
            url: https://seg.${path.1}.example.com/app
      # Exact match: only /promo → fixed campaign landing (explicit path in url).
      - path: /promo$
        backend:
          redirect:
            url: https://campaign.example.com/special

Prefix /legacy/ sends matching traffic to a fixed URL; /root-only/ shows the default path-level behaviour (the Location is the bare url); /mirror/ opts back in with preserve_path: true; /go/([^/]+)$ expands ${path.1}; /promo$ matches only /promo and redirects to an explicit landing path. Unmatched paths fall back to the host-level redirect (preserving path and query).

Regex host with captures in redirect.url ​

Same templating as service.name: $1, ${host.1}, etc.

The sample below also shows host-level redirect with path backends, and path-only redirect using ${path.N}:

yaml
version: v1
port: 8080

rules:
  - host: '^bigscreen-([^.]+)\.example\.com$'
    host_type: regex
    backend:
      type: redirect
      redirect:
        url: https://bigscreen-$1.other.example.com
  - host: app.example.com
    backend:
      redirect:
        url: https://www.example.com/landing
    paths:
      - path: ^/api/
        backend:
          type: service
          service:
            name: api-svc
            port: 8080
            protocol: http
  - host: api.example.com
    backend:
      service:
        name: default-upstream
        port: 8080
        protocol: http
    paths:
      - path: ^/go/([^/]+)$
        backend:
          redirect:
            url: https://seg.${path.1}.example.com/resource

What each rule demonstrates ​

  1. Regex host: ^bigscreen-([^.]+)\.example\.com$ → redirect.url uses $1.
  2. Host fallback + path services: default traffic redirects; paths matching ^/api/ proxy to a service.
  3. ${path.N}: path regex capture feeds redirect.url.

Released under the MIT License.