sigs.k8s.io/gateway-api@v1.0.0/site-src/guides/http-redirect-rewrite.md (about)

     1  # HTTP path redirects and rewrites
     2  
     3  [HTTPRoute resources](/api-types/httproute) can issue redirects to
     4  clients or rewrite paths sent upstream using
     5  [filters](/api-types/httproute#filters-optional). This guide shows how
     6  to use these features.
     7  
     8  Note that redirect and rewrite filters are mutually incompatible. Rules cannot
     9  use both filter types at once.
    10  
    11  ## Redirects
    12  
    13  Redirects return HTTP 3XX responses to a client, instructing it to retrieve a
    14  different resource. [`RequestRedirect` rule
    15  filters](/reference/spec/#gateway.networking.k8s.io/v1beta1.HTTPRequestRedirectFilter)
    16  instruct Gateways to emit a redirect response to requests matching a filtered
    17  HTTPRoute rule.
    18  
    19  Redirect filters can substitute various URL components independently. For
    20  example, to issue a permanent redirect (301) from HTTP to HTTPS, configure
    21  `requestRedirect.statusCode=301` and `requestRedirect.scheme="https"`:
    22  
    23  ```yaml
    24  {% include 'standard/http-redirect-rewrite/httproute-redirect-https.yaml' %}
    25  ```
    26  
    27  Redirects change configured URL components to match the redirect configuration
    28  while preserving other components from the original request URL. In this
    29  example, the request `GET http://redirect.example/cinnamon` will result in a
    30  301 response with a `location: https://redirect.example/cinnamon` header. The
    31  hostname (`redirect.example`), path (`/cinnamon`), and port (implicit) remain
    32  unchanged.
    33  
    34  ### Path redirects
    35  
    36  Path redirects use an HTTP Path Modifier to replace either entire paths or path
    37  prefixes. For example, the HTTPRoute below will issue a 302 redirect to all
    38  `redirect.example` requests whose path begins with `/cayenne` to `/paprika`:
    39  
    40  ```yaml
    41  {% include 'standard/http-redirect-rewrite/httproute-redirect-full.yaml' %}
    42  ```
    43  
    44  Both requests to
    45  `https://redirect.example/cayenne/pinch` and
    46  `https://redirect.example/cayenne/teaspoon` will receive a redirect with a
    47  `location: https://redirect.example/paprika`.
    48  
    49  The other path redirect type, `ReplacePrefixMatch`, replaces only the path
    50  portion matching `matches.path.value`. Changing the filter in the above to:
    51  
    52  ```yaml
    53  {% include 'standard/http-redirect-rewrite/httproute-redirect-prefix.yaml' %}
    54  ```
    55  
    56  will result in redirects with `location:
    57  https://redirect.example/paprika/pinch` and `location:
    58  https://redirect.example/paprika/teaspoon` response headers.
    59  
    60  ## Rewrites
    61  
    62  Rewrites modify components of a client request before proxying it upstream. A
    63  [`URLRewrite`
    64  filter](/reference/spec/#gateway.networking.k8s.io/v1beta1.HTTPURLRewriteFilter)
    65  can change the upstream request hostname and/or path. For example, the
    66  following HTTPRoute will accept a request for
    67  `https://rewrite.example/cardamom` and send it upstream to `example-svc` with
    68  `host: elsewhere.example` in request headers instead of `host:
    69  rewrite.example`.
    70  
    71  ```yaml
    72  {% include 'standard/http-redirect-rewrite/httproute-rewrite.yaml' %}
    73  ```
    74  
    75  Path rewrites also make use of HTTP Path Modifiers. The HTTPRoute below
    76  will take request for `https://rewrite.example/cardamom/smidgen` and proxy a
    77  request to `https://elsewhere.example/fennel` upstream to `example-svc`.
    78  Instead using `type: ReplacePrefixMatch` and `replacePrefixMatch: /fennel` will
    79  request `https://elsewhere.example/fennel/smidgen` upstream.
    80  
    81  ```yaml
    82  {% include 'standard/http-redirect-rewrite/httproute-rewritepath.yaml' %}
    83  ```