docs: add fallback certificate docs

Signed-off-by: Steve Sloka <[email protected]>

site/docs/master/configuration.md

@@ -24,6 +24,7 @@ Where Contour settings can also be specified with command-line flags, the comman
 | request-timeout | [duration][4] | `0s` | This field specifies the default request timeout as a Go duration string. Zero means there is no timeout. |
 | tls | TLS | | The default [TLS configuration](#tls-configuration). |
 {: class="table thead-dark table-bordered"}
+<br>
 
 ### TLS Configuration
 
@@ -33,7 +34,18 @@ Contour should provision TLS hosts.
 | Field Name | Type| Default  | Description |
 |------------|-----|----------|-------------|
 | minimum-protocol-version| string | `""` | This field specifies the minimum TLS protocol version that is allowed. Valid options are `1.2` and `1.3`. Any other value defaults to TLS 1.1. |
+| fallback-certificate | | | [Fallback certificate configuration](#fallback-certificate). |
 {: class="table thead-dark table-bordered"}
+<br>
+
+### Fallback Certificate
+
+| Field Name | Type| Default  | Description |
+|------------|-----|----------|-------------|
+| name       | string | `""` | This field specifies the name of the Kubernetes secret to use as the fallback certificate.      |
+| namespace  | string | `""` | This field specifies the namespace of the Kubernetes secret to use as the fallback certificate. |
+{: class="table thead-dark table-bordered"}
+<br>
 
 ### Leader Election Configuration
 
@@ -49,6 +61,7 @@ In the vast majority of deployments, only the `configmap-name` and `configmap-na
 | renew-deadline | [duration][4] | `10s` | The length of time that the leader will retry refreshing leadership before giving up. |
 | retry-period | [duration][4] | `2s` | The interval at which Contour will attempt to the acquire leadership lease. |
 {: class="table thead-dark table-bordered"}
+<br>
 
 ### Configuration Example
 
@@ -73,6 +86,9 @@ data:
     tls:
       # minimum TLS version that Contour will negotiate
       # minimumProtocolVersion: "1.1"
+      fallback-certificate:
+      # name: fallback-secret-name
+      # namespace: projectcontour
     # The following config shows the defaults for the leader election.
     # leaderelection:
       # configmap-name: leader-elect

site/docs/master/httpproxy.md

@@ -5,7 +5,7 @@
 The [Ingress][1] object was added to Kubernetes in version 1.1 to describe properties of a cluster-wide reverse HTTP proxy.
 Since that time, the Ingress object has not progressed beyond the beta stage, and its stagnation inspired an [explosion of annotations][2] to express missing properties of HTTP routing.
 
-The goal of the `HTTPProxy` (previously `IngressRoute`) Custom Resource Definition (CRD) is to expand upon the functionality of the Ingress API to allow for a richer user experience as well addressing the limitations of the latter's use in multi tenent environments.
+The goal of the HTTPProxy (previously `IngressRoute`) Custom Resource Definition (CRD) is to expand upon the functionality of the Ingress API to allow for a richer user experience as well addressing the limitations of the latter's use in multi tenent environments.
 
 ## Key HTTPProxy Benefits
 
@@ -252,6 +252,55 @@ The TLS **Minimum Protocol Version** a vhost should negotiate can be specified b
 - 1.2
 - 1.1 (Default)
 
+##### Fallback Certificate
+
+Contour provides virtual host based routing, so that any TLS request is routed to the appropriate service based on both the server name requested by the TLS client and the HOST header in the HTTP request. 
+
+As the HOST Header is encrypted during TLS handshake, it can’t be used for virtual host based routing unless the client sends HTTPS requests specifying hostname using the TLS server name, or the request is first decrypted using a default TLS certificate.
+
+Some TLS clients do not send the server name, so Envoy does not know how to select the right certificate. A fallback certificate is needed for these clients.
+
+_Note: The minimum TLS protocol version for any fallback request is defined by the `minimum TLS protocol version` set in the Contour configuration file. Enabling the fallback certificate is not compatible with TLS client authentication._
+
+###### Configuration
+
+First define the `namespace/name` in the [Contour configuration file][11] of a Kubernetes secret which will be used as the fallback certificate.
+Any HTTPProxy which enables fallback certificate delegation must have the fallback certificate delegated to the namespace in which the HTTPProxy object resides.
+
+To do that, configure `TLSCertificateDelegation` to delegate the fallback certificate to specific or all namespaces (e.g. `*`) which should be allowed to enable the fallback certificate.
+Finally, for each root HTTPProxy, set the `Spec.TLS.enableFallbackCertificate` parameter to allow that HTTPProxy to opt-in to the fallback certificate routing.
+
+```yaml
+apiVersion: projectcontour.io/v1
+kind: HTTPProxy
+metadata:
+  name: fallback-tls-example
+  namespace: defaultub
+spec:
+  virtualhost:
+    fqdn: fallback.bar.com
+    tls:
+      secretName: testsecret
+      enableFallbackCertificate: true
+  routes:
+    - services:
+        - name: s1
+          port: 80
+---
+apiVersion: projectcontour.io/v1
+kind: TLSCertificateDelegation
+metadata:
+  name: fallback-delegation
+  namespace: www-admin
+spec:
+  delegations:
+    - secretName: fallback-secret-name
+      targetNamespaces:
+      - "*"
+```
+
+
+
 #### Upstream TLS
 
 A HTTPProxy can proxy to an upstream TLS connection by annotating the upstream Kubernetes Service or by specifying the upstream protocol in the HTTPProxy [`services`][10] field.
@@ -1367,3 +1416,4 @@ Some examples of invalid configurations that Contour provides statuses for:
  [8]: #conditions
  [9]: {% link docs/master/annotations.md %}
  [10]: /docs/{{site.latest}}/api/#projectcontour.io/v1.Service
+ [11]: configuration.md#fallback-certificate