Document unique gateway HTTPS port name requirement (#2650)

content/help/ops/traffic-management/deploy-guidelines/index.md

@@ -6,6 +6,92 @@ weight: 5
 
 This section provides specific deployment or configuration guidelines to avoid networking or traffic management issues.
 
+## Configuring multiple TLS hosts in a gateway
+
+If you apply a `Gateway` configuration that has the same `selector` labels as another
+existing `Gateway`, then if they both expose the same HTTPS port you must ensure that they have
+unique port names. Otherwise, the configuration will be applied without an immediate error indication
+but it will be ignored in the runtime gateway configuration. For example:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: mygateway
+spec:
+  selector:
+    istio: ingressgateway # use istio default ingress gateway
+  servers:
+  - port:
+      number: 443
+      name: https
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+    hosts:
+    - "myhost.com"
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: mygateway2
+spec:
+  selector:
+    istio: ingressgateway # use istio default ingress gateway
+  servers:
+  - port:
+      number: 443
+      name: https
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+    hosts:
+    - "myhost2.com"
+{{< /text >}}
+
+With this configuration, requests to the second host, `myhost2.com`, will fail because
+both gateway ports have `name: https`.
+A _curl_ request, for example, will produce an error message something like this:
+
+{{< text plain >}}
+curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to myhost2.com:443
+{{< /text >}}
+
+You can confirm that this has happened by checking Pilot's logs for a message similar to the following:
+
+{{< text bash >}}
+$ kubectl logs -n istio-system -l istio=pilot -c discovery | grep "non unique port"
+2018-09-14T19:02:31.916960Z info    model   skipping server on gateway mygateway2 port https.443.HTTPS: non unique port name for HTTPS port
+{{< /text >}}
+
+To avoid this problem, ensure that multiple uses of the same `protocol: HTTPS` port are uniquely named.
+For example, change the second one to `https2`:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: mygateway2
+spec:
+  selector:
+    istio: ingressgateway # use istio default ingress gateway
+  servers:
+  - port:
+      number: 443
+      name: https2
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+    hosts:
+    - "myhost2.com"
+{{< /text >}}
+
 ## Multiple virtual services and destination rules for the same host
 
 In situations where it is inconvenient to define the complete set of route rules or policies for a particular