github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.13.1/config/upstream-tls.md (about)

     1  # Upstream TLS
     2  
     3  A HTTPProxy can proxy to an upstream TLS backend by annotating the upstream Kubernetes Service or by specifying the upstream protocol in the HTTPProxy [services][2] field.
     4  Applying the `projectcontour.io/upstream-protocol.tls` annotation to a Service object tells Contour that TLS should be enabled and which port should be used for the TLS connection.
     5  The same configuration can be specified by setting the protocol name in the `spec.routes.services[].protocol` field on the HTTPProxy object.
     6  If both the annotation and the protocol field are specified, the protocol field takes precedence.
     7  By default, the upstream TLS server certificate will not be validated, but validation can be requested by setting the `spec.routes.services[].validation` field.
     8  This field has mandatory `caSecret` and `subjectName` fields, which specify the trusted root certificates with which to validate the server certificate and the expected server name.
     9  
    10  _**Note:**
    11  If `spec.routes.services[].validation` is present, `spec.routes.services[].{name,port}` must point to a Service with a matching `projectcontour.io/upstream-protocol.tls` Service annotation._
    12  
    13  In the example below, the upstream service is named `secure-backend` and uses port `8443`:
    14  
    15  ```yaml
    16  # httpproxy-example.yaml
    17  apiVersion: projectcontour.io/v1
    18  kind: HTTPProxy
    19  metadata:
    20    name: example
    21  spec:
    22    virtualhost:
    23      fqdn: www.example.com
    24    routes:
    25    - services:
    26      - name: secure-backend
    27        port: 8443
    28        validation:
    29          caSecret: my-certificate-authority
    30          subjectName: backend.example.com
    31  ```
    32  
    33  ```yaml
    34  # service-secure-backend.yaml
    35  apiVersion: v1
    36  kind: Service
    37  metadata:
    38    name: secure-backend
    39    annotations:
    40      projectcontour.io/upstream-protocol.tls: "8443"
    41  spec:
    42    ports:
    43    - name: https
    44      port: 8443
    45    selector:
    46      app: secure-backend
    47  
    48  ```
    49  
    50  If the `validation` spec is defined on a service, but the secret which it references does not exist, Contour will reject the update and set the status of the HTTPProxy object accordingly.
    51  This helps prevent the case of proxying to an upstream where validation is requested, but not yet available.
    52  
    53  ```yaml
    54  Status:
    55    Current Status:  invalid
    56    Description:     route "/": service "tls-nginx": upstreamValidation requested but secret not found or misconfigured
    57  ```
    58  
    59  ## Upstream Validation
    60  
    61  When defining upstream services on a route, it's possible to configure the connection from Envoy to the backend endpoint to communicate over TLS.
    62  Two configuration items are required, a CA certificate and a `SubjectName` which are both used to verify the backend endpoint's identity.
    63  
    64  The CA certificate bundle for the backend service should be supplied in a Kubernetes Secret.
    65  The referenced Secret must be of type "Opaque" and have a data key named `ca.crt`.
    66  This data value must be a PEM-encoded certificate bundle.
    67  
    68  In addition to the CA certificate and the subject name, the Kubernetes service must also be annotated with a Contour specific annotation: `projectcontour.io/upstream-protocol.tls: <port>` ([see annotations section][1]).
    69  
    70  _**Note:** This annotation is applied to the Service not the Ingress or HTTPProxy object._
    71  
    72  ```yaml
    73  apiVersion: projectcontour.io/v1
    74  kind: HTTPProxy
    75  metadata:
    76    name: blog
    77    namespace: marketing
    78  spec:
    79    routes:
    80      - services:
    81          - name: s2
    82            port: 80
    83            validation:
    84              caSecret: foo-ca-cert
    85              subjectName: foo.marketing
    86  ```
    87  
    88  ## Envoy Client Certificate
    89  
    90  Contour can be configured with a `namespace/name` in the [Contour configuration file][3] of a Kubernetes secret which Envoy uses as a client certificate when upstream TLS is configured for the backend.
    91  Envoy will send the certificate during TLS handshake when the backend applications request the client to present its certificate.
    92  Backend applications can validate the certificate to ensure that the connection is coming from Envoy.
    93  
    94  [1]: annotations.md
    95  [2]: api/#projectcontour.io/v1.Service
    96  [3]: ../configuration#fallback-certificate