diff options
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/oom_quickstart_guide.rst | 4 | ||||
| -rw-r--r-- | docs/oom_setup_ingress_controller.rst | 159 |
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 + |