DOC howto setup ingress on the Kubernetes cluster

User manual howto setup ingress controller on the kubernetes
cluster using Nginx and MetalLB

Issue-ID: OOM-1878
Change-Id: I0947c0060851fd7a43bfa92b0472b9ec898857b6
Signed-off-by: Lucjan Bryndza <l.bryndza@samsung.com>

2 files changed, 160 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index c8048d142e..c933a726fb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,3 +16,4 @@ OOM Documentation Repository
   oom_cloud_setup_guide.rst
   release-notes.rst
   oom_setup_kubernetes_rancher.rst
+  oom_setup_ingress_controller.rst
diff --git a/docs/oom_setup_ingress_controller.rst b/docs/oom_setup_ingress_controller.rst
new file mode 100644
index 0000000000..a4abc2b390
--- /dev/null
+++ b/docs/oom_setup_ingress_controller.rst
@@ -0,0 +1,159 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2020, Samsung Electronics
+
+.. Links
+.. _HELM Best Practices Guide: https://docs.helm.sh/chart_best_practices/#requirements
+.. _kubectl Cheat Sheet: https://kubernetes.io/docs/reference/kubectl/cheatsheet/
+.. _Kubernetes documentation for emptyDir: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir
+.. _metallb Metal Load Balancer installation: https://metallb.universe.tf/installation/
+.. _http://cd.onap.info:30223/mso/logging/debug: http://cd.onap.info:30223/mso/logging/debug
+.. _Onboarding and Distributing a Vendor Software Product: https://wiki.onap.org/pages/viewpage.action?pageId=1018474
+.. _README.md: https://gerrit.onap.org/r/gitweb?p=oom.git;a=blob;f=kubernetes/README.md
+
+.. figure:: oomLogoV2-medium.png
+   :align: right
+
+.. _onap-on-kubernetes-with-rancher:
+
+
+Ingress controller setup on HA Kubernetes Cluster
+#################################################
+
+This guide provides instruction how to setup experimental ingress controller feature.
+For this, we are hosting our cluster on OpenStack VMs and using the Rancher Kubernetes Engine (RKE)
+to deploy and manage our Kubernetes Cluster and ingress controller
+
+.. contents::
+   :depth: 1
+   :local:
+..
+
+The result at the end of this tutorial will be:
+
+#. Customization of the cluster.yaml file for ingress controller support
+
+#. Installation and configuration test DNS server for ingress host resolution on testing machines
+
+#. Instalation and configuration MLB (Metal Load Balancer) required for exposing ingress service
+
+#. Instalation and configuration NGINX ingress controller
+
+#. Additional info howto deploy onap with services exposed via Ingress controller
+
+Customize cluster.yml file
+===========================
+Before setup cluster for ingress purposes DNS cluster IP and ingress provider should be configured and follwing:
+
+.. code-block:: yaml
+	<...>
+	restore:
+  		restore: false
+  		snapshot_name: ""
+	ingress:
+		provider: none
+	dns:
+		provider: coredns
+		upstreamnameservers:
+			- <custer_dns_ip>:31555
+
+Where the <cluster_dns_ip> should be set to the same IP as the CONTROLPANE node.
+
+For external load balacer purposes minimum one of the worker node should be configured with external IP
+address accessible outside the cluster. It can be done using the following example node configuration:
+
+.. code-block:: yaml
+	<...>
+	- address: <external_ip>
+	  internal_address: <internal_ip>
+	  port: "22"
+	  role:
+	  - worker
+	  hostname_override: "onap-worker-0"
+	  user: ubuntu
+	  ssh_key_path: "~/.ssh/id_rsa"
+    <...>
+
+Where the <external_ip> is external worker node IP address, and <internal_ip> is internal node IP address if it is required
+
+
+
+DNS server configuration and instalation
+========================
+DNS server deployed on the Kubernetes cluster makes it easy to use services exposed through ingress controller because it
+resolves all subdomain related to the onap cluster to the load balancer IP.
+Testing ONAP cluster requires a lot of entries on the target machines in the /etc/hosts.
+Adding many entries into the configuration files on testing machines is quite problematic and error prone.
+The better wait is to create central DNS server with entries for all virtual host pointed to simpledemo.onap.org and add custom DNS server as a target DNS server for testing machines and/or as external DNS for kubernetes cluster.
+
+DNS server has automatic instalation and configuration script, so instalation is quite easy::
+
+	> cd kubernetes/contrib/dns-server-for-vhost-ingress-testing
+
+	> ./deploy\_dns.sh
+
+After DNS deploy you need to setup DNS entry on the target testing machine.
+Because DNS listen on non standard port configuration require iptables rules
+on the target machine. Please follow the configuation proposed by the deploy scripts
+Example output depends on the IP address and example output looks like bellow::
+
+
+	DNS server already deployed:
+	1. You can add the DNS server to the target machine using following commands:
+			sudo iptables -t nat -A OUTPUT -p tcp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555
+			sudo iptables -t nat -A OUTPUT -p udp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555
+			sudo sysctl -w net.ipv4.conf.all.route_localnet=1
+			sudo sysctl -w net.ipv4.ip_forward=1
+	2. Update /etc/resolv.conf file with nameserver 192.168.211.211 entry on your target machine
+
+
+MetalLB Load Balancer instalation and configuration
+====================================================
+
+By default pure Kubernetes cluster requires external load balancer if we want to expose
+external port using LoadBalancer settings. For this purpose MetalLB can be used.
+Before installing the MetalLB you need to ensure that at least one worker has assigned IP acessible outside the cluster.
+
+MetalLB Load balanancer can be easily installed using automatic install script::
+
+	> cd kubernetes/contrib/metallb-loadbalancer-inst
+
+	> ./install-metallb-on-cluster.sh
+
+
+Configuration NGINX ingress controller
+=======================================
+
+After installation DNS server and ingress controller we can install and configure ingress controller.
+It can be done using the following commands::
+
+	> cd kubernetes/contrib/ingress-nginx-post-inst
+
+	> kubectl apply -f nginx_ingress_cluster_config.yaml
+
+	> kubectl apply -f nginx_ingress_enable_optional_load_balacer_service.yaml
+
+After deploy NGINX ingress controller you can ensure that the ingress port is exposed as load balancer service
+with external IP address::
+
+	> kubectl get svc -n ingress-nginx
+	NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                      AGE
+	default-http-backend   ClusterIP      10.10.10.10   <none>           80/TCP                       25h
+	ingress-nginx          LoadBalancer   10.10.10.11    10.12.13.14   80:31308/TCP,443:30314/TCP   24h
+
+
+ONAP with ingress exposed services
+=====================================
+If you want to deploy onap with services exposed through ingress controller you can use full onap deploy script::
+	> onap/resources/overrides/onap-all-ingress-nginx-vhost.yaml
+
+Ingress also can be enabled on any onap setup override using following code:
+
+.. code-block:: yaml
+	<...>
+	#ingress virtualhost based configuration
+	global:
+    <...>
+	  ingress:
+		enabled: true
+