From 248ecd10bf3e662881d61af44688e1cdac31964a Mon Sep 17 00:00:00 2001
From: "Christopher M. Luciano" <cmluciano@us.ibm.com>
Date: Thu, 25 Jun 2020 12:42:45 -0400
Subject: [PATCH] ingress: Add documentation on resource backends

Signed-off-by: Christopher M. Luciano <cmluciano@us.ibm.com>
---
 .../concepts/services-networking/ingress.md   | 32 ++++++++++++++++++-
 .../networking/ingress-resource-backend.yaml  | 20 ++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 content/en/examples/service/networking/ingress-resource-backend.yaml

diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md
index ca0c0333d1..1951325e24 100644
--- a/content/en/docs/concepts/services-networking/ingress.md
+++ b/content/en/docs/concepts/services-networking/ingress.md
@@ -88,7 +88,7 @@ Each HTTP rule contains the following information:
   and a `service.Port.Name` or `service.Port.Number`. Both the host and path must match the content of an incoming request before the
   load balancer directs traffic to the referenced Service.
 * A backend is a combination of Service and port names as described in the
-  [Service doc](/docs/concepts/services-networking/service/) or a [custom resource backend]() by way of a CRD. HTTP (and HTTPS) requests to the
+  [Service doc](/docs/concepts/services-networking/service/) or a [custom resource backend](#resource-backends) by way of a CRD. HTTP (and HTTPS) requests to the
   Ingress that matches the host and path of the rule are sent to the listed backend.
 
 A `defaultBackend` is often configured in an Ingress controller to service any requests that do not
@@ -102,6 +102,36 @@ of the [Ingress controller](/docs/concepts/services-networking/ingress-controlle
 If none of the hosts or paths match the HTTP request in the Ingress objects, the traffic is
 routed to your default backend.
 
+### Resource Backends {#resource-backend}
+
+A _`Resource`_ backend is an ObjectRef to another Kubernetes resource within the
+same namespace of the Ingress object. A _`Resource`_ is a mutually exclusive
+setting with Service, and will fail validation if both are specified. A common
+usage for a _`Resource`_ backend is to ingress data to a object storage backend
+with static assets.
+
+{{< codenew file="service/networking/ingress-resource-backend.yaml" >}}
+
+After creating the Ingress above, you can view it with the following command:
+
+```
+kubectl describe ingress ingress-resource-backend
+```
+
+```
+Name:             ingress-resource-backend
+Namespace:        default
+Address:
+Default backend:  APIGroup: k8s.example.com, Kind: StorageBucket, Name: static-assets
+Rules:
+  Host        Path  Backends
+  ----        ----  --------
+  *
+              /icons   APIGroup: k8s.example.com, Kind: StorageBucket, Name: icon-assets
+Annotations:  <none>
+Events:       <none>
+```
+
 ### Path Types
 
 Each path in an Ingress is required to have a corresponding path type. Paths
diff --git a/content/en/examples/service/networking/ingress-resource-backend.yaml b/content/en/examples/service/networking/ingress-resource-backend.yaml
new file mode 100644
index 0000000000..87b6bbd0f3
--- /dev/null
+++ b/content/en/examples/service/networking/ingress-resource-backend.yaml
@@ -0,0 +1,20 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ingress-resource-backend
+spec:
+  defaultBackend:
+    resource:
+      apiGroup: k8s.example.com
+      kind: StorageBucket
+      name: static-assets
+  rules:
+    - http:
+        paths:
+          - path: /icons
+            pathType: ImplementationSpecific
+            backend:
+              resource:
+                apiGroup: k8s.example.com
+                kind: StorageBucket
+                name: icon-assets