github.com/projectcontour/contour@v1.28.2/site/content/docs/main/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`, `subjectName`, and `subjectNames` fields, which specify the trusted root certificates with which to validate the server certificate and the expected server name(s).
     9  
    10  _**Note:**
    11  The `subjectName` field is deprecated in favor of `subjectNames`. When using `subjectNames`, the first entry must match the value for `subjectName`. The `subjectName` field also has a limit of 250 characters._
    12  
    13  The `caSecret` can be a namespaced name of the form `<namespace>/<secret-name>`. If the CA secret's namespace is not the same namespace as the `HTTPProxy` resource, [TLS Certificate Delegation][4] must be used to allow the owner of the CA certificate secret to delegate, for the purposes of referencing the CA certificate in a different namespace, permission to Contour to read the Secret object from another namespace.
    14  
    15  _**Note:**
    16  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._
    17  
    18  In the example below, the upstream service is named `secure-backend` and uses port `8443`:
    19  
    20  ```yaml
    21  # httpproxy-example.yaml
    22  apiVersion: projectcontour.io/v1
    23  kind: HTTPProxy
    24  metadata:
    25    name: example
    26  spec:
    27    virtualhost:
    28      fqdn: www.example.com
    29    routes:
    30    - services:
    31      - name: secure-backend
    32        port: 8443
    33        validation:
    34          caSecret: my-certificate-authority
    35          subjectName: backend.example.com
    36  ```
    37  
    38  ```yaml
    39  # service-secure-backend.yaml
    40  apiVersion: v1
    41  kind: Service
    42  metadata:
    43    name: secure-backend
    44    annotations:
    45      projectcontour.io/upstream-protocol.tls: "8443"
    46  spec:
    47    ports:
    48    - name: https
    49      port: 8443
    50    selector:
    51      app: secure-backend
    52  
    53  ```
    54  
    55  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.
    56  This helps prevent the case of proxying to an upstream where validation is requested, but not yet available.
    57  
    58  ```yaml
    59  Status:
    60    Current Status:  invalid
    61    Description:     route "/": service "tls-nginx": upstreamValidation requested but secret not found or misconfigured
    62  ```
    63  
    64  ## Upstream Validation
    65  
    66  When defining upstream services on a route, it's possible to configure the connection from Envoy to the backend endpoint to communicate over TLS.
    67  
    68  A CA certificate and a Subject Name must be provided, which are both used to verify the backend endpoint's identity.
    69  
    70  If specifying multiple Subject Names, `SubjectNames` and `SubjectName` must be configured such that `SubjectNames[0] == SubjectName`. 
    71  
    72  The CA certificate bundle for the backend service should be supplied in a Kubernetes Secret.
    73  The referenced Secret must be of type "Opaque" and have a data key named `ca.crt`.
    74  This data value must be a PEM-encoded certificate bundle.
    75  
    76  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]).
    77  
    78  _**Note:** This annotation is applied to the Service not the Ingress or HTTPProxy object._
    79  
    80  ```yaml
    81  apiVersion: projectcontour.io/v1
    82  kind: HTTPProxy
    83  metadata:
    84    name: blog
    85    namespace: marketing
    86  spec:
    87    routes:
    88      - services:
    89          - name: s2
    90            port: 80
    91            validation:
    92              caSecret: foo-ca-cert
    93              subjectName: foo.marketing
    94              subjectNames:
    95              - foo.marketing
    96              - bar.marketing
    97  ```
    98  
    99  ## Envoy Client Certificate
   100  
   101  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.
   102  Envoy will send the certificate during TLS handshake when the backend applications request the client to present its certificate.
   103  Backend applications can validate the certificate to ensure that the connection is coming from Envoy.
   104  
   105  [1]: annotations.md
   106  [2]: api/#projectcontour.io/v1.Service
   107  [3]: ../configuration#fallback-certificate
   108  [4]: tls-delegation.md