From 95a77e30dbf713916b5f58486bf0139f720984be Mon Sep 17 00:00:00 2001
From: "Christopher M. Luciano" <cmluciano@us.ibm.com>
Date: Thu, 25 Jun 2020 13:04:39 -0400
Subject: [PATCH] ingress: Update documentation for wildcard hostnames

Signed-off-by: Christopher M. Luciano <cmluciano@us.ibm.com>
---
 .../concepts/services-networking/ingress.md   | 14 ++++++++++
 .../networking/ingress-wildcard-host.yaml     | 26 +++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 content/en/examples/service/networking/ingress-wildcard-host.yaml

diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md
index 1951325e24..c388f981d0 100644
--- a/content/en/docs/concepts/services-networking/ingress.md
+++ b/content/en/docs/concepts/services-networking/ingress.md
@@ -183,6 +183,20 @@ cases precedence will be given first to the longest matching path. If two paths
 are still equally matched, precedence will be given to paths with an exact path
 type over prefix path type.
 
+## Hostname Wildcards
+Hosts can be precise matches (for example “`foo.bar.com`”) or a wildcard (for
+example “`*.foo.com`”). Precise matches require that the http host header
+matches the Host setting. Wildcard matches require the http host header is equal
+to the suffix of the wildcard rule.
+
+| Host        | Host header       | Match?                                            |
+| ----------- |-------------------| --------------------------------------------------|
+| `*.foo.com` | `bar.foo.com`     | Matches based on shared suffix                    |
+| `*.foo.com` | `baz.bar.foo.com` | No match, wildcard only covers a single DNS label |
+| `*.foo.com` | `foo.com`         | No match, wildcard only covers a single DNS label |
+
+{{< codenew file="service/networking/ingress-wildcard-host.yaml" >}}
+
 ## Ingress Class
 
 Ingresses can be implemented by different controllers, often with different
diff --git a/content/en/examples/service/networking/ingress-wildcard-host.yaml b/content/en/examples/service/networking/ingress-wildcard-host.yaml
new file mode 100644
index 0000000000..2be7016706
--- /dev/null
+++ b/content/en/examples/service/networking/ingress-wildcard-host.yaml
@@ -0,0 +1,26 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ingress-wildcard-host
+spec:
+  rules:
+  - host: "foo.bar.com"
+    http:
+      paths:
+      - pathType: Prefix
+        path: "/bar"
+        backend:
+          service:
+            name: service1
+            port:
+              number: 80
+  - host: "*.foo.com"
+    http:
+      paths:
+      - pathType: Prefix
+        path: "/foo"
+        backend:
+          service:
+            name: service2
+            port:
+              number: 80