From c6adeb8f8cb606f0d78e46f14efbf17367d8ffe4 Mon Sep 17 00:00:00 2001
From: Davide Icardi <davide.icardi@gmail.com>
Date: Sun, 24 Oct 2021 21:20:21 +0200
Subject: [PATCH] improve basic usage documentation (#7661)

---
 docs/user-guide/basic-usage.md | 100 ++++++++++++++++-----------------
 1 file changed, 49 insertions(+), 51 deletions(-)

diff --git a/docs/user-guide/basic-usage.md b/docs/user-guide/basic-usage.md
index ae913b6a4..64c81148b 100644
--- a/docs/user-guide/basic-usage.md
+++ b/docs/user-guide/basic-usage.md
@@ -2,7 +2,11 @@
 
 ingress-nginx can be used for many use cases, inside various cloud provider and supports a lot of configurations. In this section you can find a common usage scenario where a single load balancer powered by ingress-nginx will route traffic to 2 different HTTP backend services based on the host name.
 
-First of all follow the instructions to install ingress-nginx. Then imagine that you need to expose 2 HTTP services already installed: `myServiceA`, `myServiceB`. Let's say that you want to expose the first at `myServiceA.foo.org` and the second at `myServiceB.foo.org`. One possible solution is to create two **ingress** resources:
+First of all follow the instructions to install ingress-nginx. Then imagine that you need to expose 2 HTTP services already installed, `myServiceA`, `myServiceB`, and configured as `type: ClusterIP`. 
+
+Let's say that you want to expose the first at `myServiceA.foo.org` and the second at `myServiceB.foo.org`.
+
+If cluster version < 1.19 you can create two **ingress** resources like this:
 
 ```
 apiVersion: networking.k8s.io/v1
@@ -46,59 +50,53 @@ spec:
               number: 80
 ```
 
-When you apply this yaml, 2 ingress resources will be created managed by the **ingress-nginx** instance. Nginx is configured to automatically discover all ingress with the `kubernetes.io/ingress.class: "nginx"` annotation.
+If cluster version >= 1.19 the Ingress resource above will not work, instead of annotations you should use the new `ingressClassName: nginx` property.
+
+```
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ingress-myservicea
+spec:
+  rules:
+  - host: myservicea.foo.org
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: myservicea
+            port: 
+              number: 80
+  ingressClassName: nginx
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ingress-myserviceb
+spec:
+  rules:
+  - host: myserviceb.foo.org
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: myserviceb
+            port: 
+              number: 80
+  ingressClassName: nginx
+```
+
+When you apply this yaml, 2 ingress resources will be created managed by the **ingress-nginx** instance. Nginx is configured to automatically discover all ingress with the `kubernetes.io/ingress.class: "nginx"` annotation or where `ingressClassName: nginx` is present.
 Please note that the ingress resource should be placed inside the same namespace of the backend resource.
 
-If cluster version >= 1.19 the Ingress resource above will not work.
-You need to deploy the following so that it match the new api version.
-This will require changes to the Ingress objects as shown below, and a new object from type "kind: IngressClass"
-```
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: ingress-myservicea
-spec:
-  rules:
-  - host: myservicea.foo.org
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: myservicea
-            port: 
-              number: 80
-  ingressClassName: nginx
----
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: ingress-myserviceb
-spec:
-  rules:
-  - host: myserviceb.foo.org
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: myserviceb
-            port: 
-              number: 80
-  ingressClassName: nginx
----
-apiVersion: networking.k8s.io/v1
-kind: IngressClass
-metadata:
-  name: nginx
-spec:
-  controller: k8s.io/ingress-nginx
-```
-
-On many cloud providers ingress-nginx will also create the corresponding Load Balancer resource. All you have to do is get the external IP and add a DNS `A record` inside your DNS provider that point myServiceA.foo.org and myServiceB.foo.org to the nginx external IP. Get the external IP by running:
+On many cloud providers ingress-nginx will also create the corresponding Load Balancer resource. All you have to do is get the external IP and add a DNS `A record` inside your DNS provider that point myservicea.foo.org and myserviceb.foo.org to the nginx external IP. Get the external IP by running:
 
 ```
 kubectl get services -n ingress-nginx
 ```
+
+To test inside minikube refer to this documentation: [Set up Ingress on Minikube with the NGINX Ingress Controller](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/)
\ No newline at end of file