docs/oom_setup_ingress_controller.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2020, Samsung Electronics
   4
   5 .. Links
   6 .. _HELM Best Practices Guide: https://docs.helm.sh/chart_best_practices/#requirements
   7 .. _kubectl Cheat Sheet: https://kubernetes.io/docs/reference/kubectl/cheatsheet/
   8 .. _Kubernetes documentation for emptyDir: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir
   9 .. _metallb Metal Load Balancer installation: https://metallb.universe.tf/installation/
  10 .. _http://cd.onap.info:30223/mso/logging/debug: http://cd.onap.info:30223/mso/logging/debug
  11 .. _Onboarding and Distributing a Vendor Software Product: https://wiki.onap.org/pages/viewpage.action?pageId=1018474
  12 .. _README.md: https://gerrit.onap.org/r/gitweb?p=oom.git;a=blob;f=kubernetes/README.md
  13
  14 .. figure:: oomLogoV2-medium.png
  15    :align: right
  16
  17 .. _onap-on-kubernetes-with-rancher:
  18
  19
  20 Ingress controller setup on HA Kubernetes Cluster
  21 #################################################
  22
  23 This guide provides instruction how to setup experimental ingress controller feature.
  24 For this, we are hosting our cluster on OpenStack VMs and using the Rancher Kubernetes Engine (RKE)
  25 to deploy and manage our Kubernetes Cluster and ingress controller
  26
  27 .. contents::
  28    :depth: 1
  29    :local:
  30 ..
  31
  32 The result at the end of this tutorial will be:
  33
  34 #. Customization of the cluster.yaml file for ingress controller support
  35
  36 #. Installation and configuration test DNS server for ingress host resolution on testing machines
  37
  38 #. Instalation and configuration MLB (Metal Load Balancer) required for exposing ingress service
  39
  40 #. Instalation and configuration NGINX ingress controller
  41
  42 #. Additional info howto deploy onap with services exposed via Ingress controller
  43
  44 Customize cluster.yml file
  45 ===========================
  46 Before setup cluster for ingress purposes DNS cluster IP and ingress provider should be configured and follwing:
  47
  48 .. code-block:: yaml
  49         <...>
  50         restore:
  51                 restore: false
  52                 snapshot_name: ""
  53         ingress:
  54                 provider: none
  55         dns:
  56                 provider: coredns
  57                 upstreamnameservers:
  58                         - <custer_dns_ip>:31555
  59
  60 Where the <cluster_dns_ip> should be set to the same IP as the CONTROLPANE node.
  61
  62 For external load balacer purposes minimum one of the worker node should be configured with external IP
  63 address accessible outside the cluster. It can be done using the following example node configuration:
  64
  65 .. code-block:: yaml
  66         <...>
  67         - address: <external_ip>
  68           internal_address: <internal_ip>
  69           port: "22"
  70           role:
  71           - worker
  72           hostname_override: "onap-worker-0"
  73           user: ubuntu
  74           ssh_key_path: "~/.ssh/id_rsa"
  75     <...>
  76
  77 Where the <external_ip> is external worker node IP address, and <internal_ip> is internal node IP address if it is required
  78
  79
  80
  81 DNS server configuration and instalation
  82 ========================
  83 DNS server deployed on the Kubernetes cluster makes it easy to use services exposed through ingress controller because it
  84 resolves all subdomain related to the onap cluster to the load balancer IP.
  85 Testing ONAP cluster requires a lot of entries on the target machines in the /etc/hosts.
  86 Adding many entries into the configuration files on testing machines is quite problematic and error prone.
  87 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.
  88
  89 DNS server has automatic instalation and configuration script, so instalation is quite easy::
  90
  91         > cd kubernetes/contrib/dns-server-for-vhost-ingress-testing
  92
  93         > ./deploy\_dns.sh
  94
  95 After DNS deploy you need to setup DNS entry on the target testing machine.
  96 Because DNS listen on non standard port configuration require iptables rules
  97 on the target machine. Please follow the configuation proposed by the deploy scripts
  98 Example output depends on the IP address and example output looks like bellow::
  99
 100
 101         DNS server already deployed:
 102         1. You can add the DNS server to the target machine using following commands:
 103                         sudo iptables -t nat -A OUTPUT -p tcp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555
 104                         sudo iptables -t nat -A OUTPUT -p udp -d 192.168.211.211 --dport 53 -j DNAT --to-destination 10.10.13.14:31555
 105                         sudo sysctl -w net.ipv4.conf.all.route_localnet=1
 106                         sudo sysctl -w net.ipv4.ip_forward=1
 107         2. Update /etc/resolv.conf file with nameserver 192.168.211.211 entry on your target machine
 108
 109
 110 MetalLB Load Balancer instalation and configuration
 111 ====================================================
 112
 113 By default pure Kubernetes cluster requires external load balancer if we want to expose
 114 external port using LoadBalancer settings. For this purpose MetalLB can be used.
 115 Before installing the MetalLB you need to ensure that at least one worker has assigned IP acessible outside the cluster.
 116
 117 MetalLB Load balanancer can be easily installed using automatic install script::
 118
 119         > cd kubernetes/contrib/metallb-loadbalancer-inst
 120
 121         > ./install-metallb-on-cluster.sh
 122
 123
 124 Configuration NGINX ingress controller
 125 =======================================
 126
 127 After installation DNS server and ingress controller we can install and configure ingress controller.
 128 It can be done using the following commands::
 129
 130         > cd kubernetes/contrib/ingress-nginx-post-inst
 131
 132         > kubectl apply -f nginx_ingress_cluster_config.yaml
 133
 134         > kubectl apply -f nginx_ingress_enable_optional_load_balacer_service.yaml
 135
 136 After deploy NGINX ingress controller you can ensure that the ingress port is exposed as load balancer service
 137 with external IP address::
 138
 139         > kubectl get svc -n ingress-nginx
 140         NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                      AGE
 141         default-http-backend   ClusterIP      10.10.10.10   <none>           80/TCP                       25h
 142         ingress-nginx          LoadBalancer   10.10.10.11    10.12.13.14   80:31308/TCP,443:30314/TCP   24h
 143
 144
 145 ONAP with ingress exposed services
 146 =====================================
 147 If you want to deploy onap with services exposed through ingress controller you can use full onap deploy script::
 148         > onap/resources/overrides/onap-all-ingress-nginx-vhost.yaml
 149
 150 Ingress also can be enabled on any onap setup override using following code:
 151
 152 .. code-block:: yaml
 153         <...>
 154         #ingress virtualhost based configuration
 155         global:
 156     <...>
 157           ingress:
 158                 enabled: true
 159