Improve the ingress controller guide

In addition to the extraPortMapping example, document how to run the
Ingress with a LoadBalancer provisioning by cloud-provider kind, that
provides a more realistic experience.

It also removes the specific implimentation details of the guide so it
is more agnostic of the Ingress implementation.

Change-Id: I865e72ca4571f0c513a1e9e412bc5e9c06a67a51

site/content/docs/user/ingress.md

@@ -10,16 +10,12 @@ description: |-
 ---
 ## Setting Up An Ingress Controller
 
-We can leverage KIND's `extraPortMapping` config option when
-creating a cluster to forward ports from the host
-to an ingress controller running on a node.
+Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster.
 
-We can also setup a custom node label by using `node-labels`
-in the kubeadm `InitConfiguration`, to be used
-by the ingress controller `nodeSelector`.
+1. [Create a cluster](#create-cluster): There are two primary methods to direct external traffic to Services inside the cluster"
+    1. using a [LoadBalancer](./loadbalancer.md).
+    2. leverage KIND's `extraPortMapping` config option when creating a cluster to forward ports from the host.
 
-
-1. [Create a cluster](#create-cluster)
 2. Deploy an Ingress controller, we document [Ingress NGINX](#ingress-nginx) here but other ingresses may work including [Contour](https://projectcontour.io/docs/main/guides/kind/) and Kong, you should follow their docs if you choose to use them.
 
 > **NOTE**: You may also want to consider using [Gateway API](https://gateway-api.sigs.k8s.io/) instead of Ingress.
@@ -29,10 +25,18 @@ by the ingress controller `nodeSelector`.
 
 ### Create Cluster
 
-Create a kind cluster with `extraPortMappings` and `node-labels`.
+#### Option 1: LoadBalancer
 
-- **extraPortMappings** allow the local host to make requests to the Ingress controller over ports 80/443
-- **node-labels** only allow the ingress controller to run on a specific node(s) matching the label selector
+Create a kind cluster and run [Cloud Provider KIND](./loadbalancer.md)
+to enable the loadbalancer controller which ingress-nginx will use through the loadbalancer API.
+
+{{< codeFromInline lang="bash" >}}
+kind create cluster
+{{< /codeFromInline >}}
+
+#### Option 2: extraPortMapping
+
+Create a single node kind cluster with `extraPortMappings` to allow the local host to make requests to the Ingress controller over ports 80/443.
 
 {{< codeFromInline lang="bash" >}}
 cat <<EOF | kind create cluster --config=-
@@ -40,12 +44,6 @@ kind: Cluster
 apiVersion: kind.x-k8s.io/v1alpha4
 nodes:
 - role: control-plane
-  kubeadmConfigPatches:
-  - |
-    kind: InitConfiguration
-    nodeRegistration:
-      kubeletExtraArgs:
-        node-labels: "ingress-ready=true"
   extraPortMappings:
   - containerPort: 80
     hostPort: 80
@@ -56,15 +54,19 @@ nodes:
 EOF
 {{< /codeFromInline >}}
 
+If you want to run with multiple nodes you must ensure that your ingress-controller is deployed on the same node where you have configured the PortMapping, in this example you can use a [nodeSelector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/) to specify the control-plane node name.
+
+{{< codeFromInline lang="yaml" >}}
+nodeSelector:
+  kubernetes.io/hostname: "kind-control-plane"
+{{< /codeFromInline >}}
+
 ### Ingress NGINX
 
 {{< codeFromInline lang="bash" >}}
 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
 {{< /codeFromInline >}}
 
-The manifests contains kind specific patches to forward the hostPorts to the
-ingress controller, set taint tolerations and schedule it to the custom labelled node.
-
 Now the Ingress is all setup. Wait until is ready to process requests running:
 
 {{< codeFromInline lang="bash" >}}
@@ -95,9 +97,46 @@ kubectl apply -f {{< absURL "examples/ingress/usage.yaml" >}}
 
 Now verify that the ingress works
 
+#### Option 1: LoadBalancer
+
+Check the External IP assigned to the Ingress controller by the LoadBalancer
+
 {{< codeFromInline lang="bash" >}}
-# should output "foo-app"
-curl localhost/foo/hostname
-# should output "bar-app"
-curl localhost/bar/hostname
+kubectl -n ingress-nginx get services
+NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                      AGE
+ingress-nginx-controller             LoadBalancer   10.96.33.233   192.168.8.5   80:31753/TCP,443:30288/TCP   27d
+ingress-nginx-controller-admission   ClusterIP      10.96.80.178   <none>        443/TCP                      27d
+{{< /codeFromInline >}}
+
+{{< codeFromInline lang="bash" >}}
+
+# get the loadalancer IP
+
+LOADBALANCER_IP=$(kubectl get services \
+   --namespace ingress-nginx \
+   ingress-nginx-controller \
+   --output jsonpath='{.status.loadBalancer.ingress[0].ip}')
+
+# should output "foo-app"
+
+curl ${LOADBALANCER_IP}/foo
+
+# should output "bar-app"
+
+curl ${LOADBALANCER_IP}/bar
+{{< /codeFromInline >}}
+
+#### Option 2: extraPortMapping
+
+The Ingress controller ports will be exposed in your `localhost` address
+
+{{< codeFromInline lang="bash" >}}
+
+# should output "foo-app"
+
+curl localhost/foo
+
+# should output "bar-app"
+
+curl localhost/bar
 {{< /codeFromInline >}}

site/static/examples/ingress/usage.yaml

@@ -8,9 +8,9 @@ spec:
   containers:
   - command:
     - /agnhost
-    - netexec
-    - --http-port
-    - "8080"
+    - serve-hostname
+    - --http=true
+    - --port=8080
     image: registry.k8s.io/e2e-test-images/agnhost:2.39
     name: foo-app
 ---
@@ -35,9 +35,9 @@ spec:
   containers:
   - command:
     - /agnhost
-    - netexec
-    - --http-port
-    - "8080"
+    - serve-hostname
+    - --http=true
+    - --port=8080
     image: registry.k8s.io/e2e-test-images/agnhost:2.39
     name: bar-app
 ---
@@ -56,21 +56,19 @@ apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: example-ingress
-  annotations:
-    nginx.ingress.kubernetes.io/rewrite-target: /$2
 spec:
   rules:
   - http:
       paths:
-      - pathType: ImplementationSpecific
-        path: /foo(/|$)(.*)
+      - pathType: Prefix
+        path: /foo
         backend:
           service:
             name: foo-service
             port:
               number: 8080
-      - pathType: ImplementationSpecific
-        path: /bar(/|$)(.*)
+      - pathType: Prefix
+        path: /bar
         backend:
           service:
             name: bar-service