github.com/projectcontour/contour@v1.28.2/site/content/posts/2020-01-16-announcing-contour-1.1.md (about)

     1  ---
     2  title: Header and Host Rewrite with Contour 1.1
     3  excerpt: Our latest release, Contour 1.1, now includes request and response header manipulation as well as host rewriting to external domains.
     4  author_name: Steve Sloka
     5  author_avatar: /img/contributors/steve-sloka.png
     6  categories: [kubernetes]
     7  # Tag should match author to drive author pages
     8  tags: ['Contour Team', 'Steve Sloka', 'release']
     9  date: 2020-01-16
    10  slug: announcing-contour-1.1
    11  ---
    12  
    13  Contour continues to take shape with new features. Our latest release, [Contour 1.1](https://github.com/projectcontour/contour/releases/tag/v1.1.0), now includes request and response header manipulation as well as host rewriting to external domains. Contour 1.1 also lets you specify a service’s protocol in HTTPProxy and adds back prefix rewrite support, which was the last feature blocking many users from migrating from IngressRoute to HTTPProxy.
    14  
    15  ## Header Manipulation
    16  
    17  Manipulating request and response headers are supported per-Service or per-Route. A `HeaderRequestPolicy` can be defined for both request and response requests.
    18  
    19  The header request policy has the following configuration:
    20  
    21  * **Set**: Takes a name-value pair and will create a header if it does not exist or update the value of the header specified by the key
    22  * **Remove**: Takes the name of a header to remove
    23  
    24  The following example takes requests from `headers.projectcontour.io/` and applies the following logic:
    25  
    26  * Adds the header `X-Foo: bar` to any request before it is proxied to the Kubernetes service named `s1` and removes the header `X-Baz`
    27  * After the request is processed by service `s1`, the response back to the requester will have the header `X-Service-Name: s1` added and will remove the header `X-Internal-Secret`
    28  
    29  ```yaml
    30  apiVersion: projectcontour.io/v1
    31  kind: HTTPProxy
    32  metadata:
    33    name: header-manipulation
    34    namespace: default
    35  spec:
    36    virtualhost:
    37      fqdn: headers.projectcontour.io
    38    routes:
    39      - services:
    40          - name: s1
    41            port: 80
    42            requestHeadersPolicy:
    43              set:
    44                - name: X-Foo
    45                  value: bar
    46              remove:
    47                - X-Baz
    48            responseHeaderPolicy:
    49              set:
    50                - name: X-Service-Name
    51                  value: s1
    52              remove:
    53                - X-Internal-Secret
    54  ```
    55  
    56  ## Prefix Rewrite Support
    57  
    58  Path prefix rewrite was a feature in IngressRoute that got removed right before Contour 1.0 was released. Now in Contour 1.1, HTTPProxy supports rewriting the HTTP request URL path prior to delivering the request to the backend service. Rewriting, which is performed after a routing decision has been made, never changes the request destination.
    59  
    60  The pathRewritePolicy field specifies how the path prefix should be rewritten. The replacePrefix rewrite policy specifies a replacement string for a HTTP request path prefix match. When this field is present, the path prefix that the request matched is replaced by the text specified in the replacement field. If the HTTP request path is longer than the matched prefix, the remainder of the path is unchanged.
    61  
    62  The following example will replace the prefix `/v1/api` with `/app/api/v1` on the request:
    63  
    64  ```yaml
    65  apiVersion: projectcontour.io/v1
    66  kind: HTTPProxy
    67  metadata:
    68    name: rewrite-example
    69    namespace: default
    70  spec:
    71    virtualhost:
    72      fqdn: rewrite.bar.com
    73    routes:
    74    - services:
    75      - name: s1
    76        port: 80
    77      pathRewritePolicy:
    78        replacePrefix:
    79        - prefix: /v1/api
    80          replacement: /app/api/v1
    81  ```
    82  
    83  For more information, see the documentation on [`Path Rewriting`](https://projectcontour.io/docs/v1.1.0/httpproxy/#path-rewriting).
    84  
    85  ## Host Rewrite
    86  
    87  Contour supports routing traffic to `ExternalName` service types. This kind of traffic routing allows users to proxy traffic to resources that aren’t running in the same Kubernetes cluster. You could, for example, proxy traffic to an external object storage bucket.
    88  
    89  Some users encountered a problem with this feature, in that the host header that the externalName service received was the same host header as in the original request. This problem potentially leads to routing in the external name service to fail. 
    90  
    91  To solve this issue, you can set a `requestHeadersPolicy` and define the `Host` header to match the value of the externalName; here’s an example:  
    92  
    93  ```yaml
    94  apiVersion: projectcontour.io/v1
    95  kind: HTTPProxy
    96  metadata:
    97    name: header-rewrite-example
    98  spec:
    99    virtualhost:
   100      fqdn: header.projectcontour.io
   101    routes:
   102    - services:
   103      - name: s1
   104        port: 80
   105      requestHeadersPolicy:
   106        set:
   107        - name: Host
   108          value: external.dev
   109  ```
   110  
   111  Now requests to `header.projectcontour.io` will proxy to `external.dev` with the header `Host: external.dev`. 
   112  
   113  ## IngressRoute Deprecation
   114  
   115  Since the release of Contour 1.0, `HTTPProxy` became the successor of `IngressRoute` going forward. One struggle for users wanting to migrate is a way to convert IngressRoute resources to HTTPProxy resources.
   116  
   117  A new tool named [`ir2proxy`](https://github.com/projectcontour/ir2proxy) will take an `IngressRoute` object and migrate it to an HTTPProxy.
   118  
   119  ```yaml
   120  $ ir2proxy basic.ingressroute.yaml
   121  ---
   122  apiVersion: projectcontour.io/v1
   123  kind: HTTPProxy
   124  metadata:
   125    name: basic
   126    namespace: default
   127  spec:
   128    routes:
   129    - conditions:
   130      - prefix: /
   131      services:
   132      - name: s1
   133        port: 80
   134    virtualhost:
   135      fqdn: foo-basic.bar.com
   136  status: {}
   137  ```
   138  
   139  Ir2proxy can be installed from the [releases](https://github.com/projectcontour/ir2proxy/releases) page or via [homebrew](https://github.com/projectcontour/ir2proxy#homebrew).
   140  
   141  ## Future Plans
   142  
   143  The Contour team would love to hear your feedback! Many of the features in this release were driven by users who needed a better way to solve their problems. We’re working hard to add features to Contour, especially in expanding how we approach routing.
   144  
   145  We recommend reading the full release notes for [Contour 1.1](https://github.com/projectcontour/contour/releases/tag/v1.1.0) as well as digging into the [upgrade guide](https://projectcontour.io/resources/upgrading/), which outlines the changes to be aware of when moving to version 1.1.
   146  
   147  If you are interested in contributing, a great place to start is to comment on one of the issues labeled with [Help Wanted](https://github.com/projectcontour/contour/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) and work with the team on how to resolve them.
   148  
   149  ## Thank you!
   150  
   151  We’re immensely grateful for all the community contributions that help make Contour even better! For version 1.1, special thanks go out to the following people:
   152  
   153  [@alvaroaleman](https://github.com/alvaroaleman)  
   154  [@SDBrett](https://github.com/SDBrett)  
   155  [@dhxgit](https://github.com/dhxgit)  
   156  [@mattmoor](https://github.com/mattmoor)  
   157  [@stefanprodan](https://github.com/stefanprodan)  
   158  [@surajssd](https://github.com/surajssd)  
   159  [@tsaarni](https://github.com/tsaarni)  
   160  [@masa213f](https://github.com/masa213f)