X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Foom_user_guide.rst;h=f20097d927a6121fbca8ae4925c766785757991c;hb=446b12380b0adef85b3dd5f0b5f52b9188c37349;hp=1b9a3eaef36c2fbf1f172ea1afb73030a97782cc;hpb=e091209b92f0d5369018ae677525e0bc9ff78ad3;p=oom.git diff --git a/docs/oom_user_guide.rst b/docs/oom_user_guide.rst index 1b9a3eaef3..f20097d927 100644 --- a/docs/oom_user_guide.rst +++ b/docs/oom_user_guide.rst @@ -10,7 +10,7 @@ .. _Helm Documentation: https://docs.helm.sh/helm/ .. _Helm: https://docs.helm.sh/ .. _Kubernetes: https://Kubernetes.io/ - +.. _Kubernetes LoadBalancer: https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer .. _user-guide-label: OOM User Guide @@ -58,7 +58,7 @@ Install Kubectl ~~~~~~~~~~~~~~~ Enter the following to install kubectl (on Ubuntu, there are slight differences on other O/Ss), the Kubernetes command line interface used to manage a Kubernetes cluster:: - > curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.8.6/bin/linux/amd64/kubectl + > curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.8.10/bin/linux/amd64/kubectl > chmod +x ./kubectl > sudo mv ./kubectl /usr/local/bin/kubectl > mkdir ~/.kube @@ -75,8 +75,8 @@ Install Helm ~~~~~~~~~~~~ Helm is used by OOM for package and configuration management. To install Helm, enter the following:: - > wget http://storage.googleapis.com/kubernetes-helm/helm-v2.6.1-linux-amd64.tar.gz - > tar -zxvf helm-v2.6.1-linux-amd64.tar.gz + > wget http://storage.googleapis.com/kubernetes-helm/helm-v2.9.1-linux-amd64.tar.gz + > tar -zxvf helm-v2.9.1-linux-amd64.tar.gz > sudo mv linux-amd64/helm /usr/local/bin/helm Verify the Helm version with:: @@ -108,7 +108,7 @@ stable which should be removed to avoid confusion:: To prepare your system for an installation of ONAP, you'll need to:: - > git clone http://gerrit.onap.org/r/oom + > git clone -b beijing http://gerrit.onap.org/r/oom > cd oom/kubernetes @@ -147,13 +147,13 @@ In any case, setup of the Helm repository is a one time activity. Once the repo is setup, installation of ONAP can be done with a single command:: - > helm install local/onap -name development + > helm install local/onap --name development This will install ONAP from a local repository in a 'development' Helm release. As described below, to override the default configuration values provided by OOM, an environment file can be provided on the command line as follows:: - > helm install local/onap -name development -f onap-development.yaml + > helm install local/onap --name development -f onap-development.yaml To get a summary of the status of all of the pods (containers) running in your deployment:: @@ -170,7 +170,7 @@ deployment:: was created for each of the ONAP components. .. note:: - The Helm `-name` option refers to a release name and not a Kubernetes namespace. + The Helm `--name` option refers to a release name and not a Kubernetes namespace. To install a specific version of a single ONAP component (`so` in this example) @@ -196,7 +196,7 @@ Many technologies are used across the projects resulting in significant operational complexity and an inability to apply global parameters across the entire ONAP deployment. OOM solves this problem by introducing a common configuration technology, Helm charts, that provide a hierarchical -configuration configuration with the ability to override values with higher +configuration with the ability to override values with higher level charts or command line options. The structure of the configuration of ONAP is shown in the following diagram. @@ -348,6 +348,72 @@ can be modified, for example the `so`'s `liveness` probe could be disabled <...> +Accessing the ONAP Portal using OOM and a Kubernetes Cluster +------------------------------------------------------------ + +The ONAP deployment created by OOM operates in a private IP network that isn't +publicly accessible (i.e. Openstack VMs with private internal network) which +blocks access to the ONAP Portal. To enable direct access to this Portal from a +user's own environment (a laptop etc.) the portal application's port 8989 is +exposed through a `Kubernetes LoadBalancer`_ object. + +Typically, to be able to access the Kubernetes nodes publicly a public address is +assigned. In Openstack this is a floating IP address. + +When the `portal-app` chart is deployed a Kubernetes service is created that +instantiates a load balancer. The LB chooses the private interface of one of +the nodes as in the example below (10.0.0.4 is private to the K8s cluster only). +Then to be able to access the portal on port 8989 from outside the K8s & +Openstack environment, the user needs to assign/get the floating IP address that +corresponds to the private IP as follows:: + + > kubectl -n onap get services|grep "portal-app" + portal-app LoadBalancer 10.43.142.201 10.0.0.4 8989:30215/TCP,8006:30213/TCP,8010:30214/TCP 1d app=portal-app,release=dev + + +In this example, use the 10.0.0.4 private address as a key find the +corresponding public address which in this example is 10.12.6.155. If you're +using OpenStack you'll do the lookup with the horizon GUI or the Openstack CLI +for your tenant (openstack server list). That IP is then used in your +`/etc/hosts` to map the fixed DNS aliases required by the ONAP Portal as shown +below:: + + 10.12.6.155 portal.api.simpledemo.onap.org + 10.12.6.155 vid.api.simpledemo.onap.org + 10.12.6.155 sdc.api.fe.simpledemo.onap.org + 10.12.6.155 portal-sdk.simpledemo.onap.org + 10.12.6.155 policy.api.simpledemo.onap.org + 10.12.6.155 aai.api.sparky.simpledemo.onap.org + 10.12.6.155 cli.api.simpledemo.onap.org + 10.12.6.155 msb.api.discovery.simpledemo.onap.org + +Ensure you've disabled any proxy settings the browser you are using to access +the portal and then simply access the familiar URL: +http://portal.api.simpledemo.onap.org:8989/ONAPPORTAL/login.htm + + +.. note:: + + | Alternatives Considered: + + - Kubernetes port forwarding was considered but discarded as it would require + the end user to run a script that opens up port forwarding tunnels to each of + the pods that provides a portal application widget. + + - Reverting to a VNC server similar to what was deployed in the Amsterdam + release was also considered but there were many issues with resolution, lack + of volume mount, /etc/hosts dynamic update, file upload that were a tall order + to solve in time for the Beijing release. + + Observations: + + - If you are not using floating IPs in your Kubernetes deployment and directly attaching + a public IP address (i.e. by using your public provider network) to your K8S Node + VMs' network interface, then the output of 'kubectl -n onap get services | grep "portal-app"' + will show your public IP instead of the private network's IP. Therefore, + you can grab this public IP directly (as compared to trying to find the floating + IP first) and map this IP in /etc/hosts. + .. figure:: oomLogoV2-Monitor.png :align: right @@ -366,10 +432,10 @@ to monitor the real-time health of an ONAP deployment: - a set of liveness probes which feed into the Kubernetes manager which are described in the Heal section. -Within ONAP Consul is the monitoring system of choice and deployed by OOM in two parts: +Within ONAP, Consul is the monitoring system of choice and deployed by OOM in two parts: - a three-way, centralized Consul server cluster is deployed as a highly - available monitor of all of the ONAP components,and + available monitor of all of the ONAP components, and - a number of Consul agents. The Consul server provides a user interface that allows a user to graphically @@ -621,4 +687,4 @@ deployment enter:: will remove `so` as the configuration indicates it's no longer part of the deployment. This might be useful if a one wanted to replace just `so` by -installing a custom version. +installing a custom version.