aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.rst1
-rw-r--r--docs/oom_quickstart_guide.rst4
-rw-r--r--docs/oom_setup_ingress_controller.rst159
3 files changed, 164 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_quickstart_guide.rst b/docs/oom_quickstart_guide.rst
index 565c43f467..364f14e923 100644
--- a/docs/oom_quickstart_guide.rst
+++ b/docs/oom_quickstart_guide.rst
@@ -193,6 +193,10 @@ All override files may be customized (or replaced by other overrides) as per nee
`onap-all.yaml`
Enables the modules in the ONAP deployment. As ONAP is very modular, it is possible to customize ONAP and disable some components through this configuration file.
+`onap-all-ingress-nginx-vhost.yaml`
+ Alternative version of the `onap-all.yaml` but with global ingress controller enabled. It requires the cluster configured with the nginx ingress controller and load balancer.
+ Please use this file instad `onap-all.yaml` if you want to use experimental ingress controller feature.
+
`environment.yaml`
Includes configuration values specific to the deployment environment.
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
+