.. This work is licensed under a Creative Commons Attribution 4.0
.. International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright 2018-2020 Amdocs, Bell Canada, Orange, Samsung
+.. Copyright 2018-2021 Amdocs, Bell Canada, Orange, Samsung, Nordix Foundation
.. _oom_user_guide:
.. Links
.. _Kubernetes LoadBalancer: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer
.. _user-guide-label:
-OOM User Guide helm3 (experimental)
-###################################
+OOM User Guide
+##############
The ONAP Operations Manager (OOM) provide the ability to manage the entire
life-cycle of an ONAP installation, from the initial deployment to final
complete description of these commands please refer to the `Helm
Documentation`_.
-.. figure:: oomLogoV2-medium.png
+.. figure:: images/oom_logo/oomLogoV2-medium.png
:align: right
The following sections describe the life-cycle operations:
impact
- Delete_ - cleanup individual containers or entire deployments
-.. figure:: oomLogoV2-Deploy.png
+.. figure:: images/oom_logo/oomLogoV2-Deploy.png
:align: right
Deploy
Pre-requisites
--------------
-Your environment must have the Kubernetes `kubectl` with Cert-Manager
+Your environment must have the Kubernetes `kubectl` with Strimzi Apache Kafka, Cert-Manager
and Helm setup as a one time activity.
Install Kubectl
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.15.11/bin/linux/amd64/kubectl
+ > curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.19.11/bin/linux/amd64/kubectl
> chmod +x ./kubectl
> sudo mv ./kubectl /usr/local/bin/kubectl
> mkdir ~/.kube
At this point you should see Kubernetes pods running.
-Install Cert-Manager
-~~~~~~~~~~~~~~~~~~~~
-Details on how to install Cert-Manager can be found
-:doc:`here <oom_setup_paas>`.
-
Install Helm
~~~~~~~~~~~~
Helm is used by OOM for package and configuration management. To install Helm,
enter the following::
- > wget https://get.helm.sh/helm-v3.5.2-linux-amd64.tar.gz
- > tar -zxvf helm-v3.5.2-linux-amd64.tar.gz
+ > wget https://get.helm.sh/helm-v3.6.3-linux-amd64.tar.gz
+ > tar -zxvf helm-v3.6.3-linux-amd64.tar.gz
> sudo mv linux-amd64/helm /usr/local/bin/helm
Verify the Helm version with::
> helm version
+Install Strimzi Apache Kafka Operator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Details on how to install Strimzi Apache Kafka can be found
+:doc:`here <oom_setup_paas>`.
+
+Install Cert-Manager
+~~~~~~~~~~~~~~~~~~~~
+Details on how to install Cert-Manager can be found
+:doc:`here <oom_setup_paas>`.
+
Install the Helm Repo
---------------------
Once kubectl and Helm are setup, one needs to setup a local Helm server to
To prepare your system for an installation of ONAP, you'll need to::
- > git clone -b guilin --recurse-submodules -j2 http://gerrit.onap.org/r/oom
+ > git clone -b kohn --recurse-submodules -j2 http://gerrit.onap.org/r/oom
> cd oom/kubernetes
> helm search repo local
NAME VERSION DESCRIPTION
- local/appc 2.0.0 Application Controller
- local/clamp 2.0.0 ONAP Clamp
- local/common 2.0.0 Common templates for inclusion in other charts
- local/onap 2.0.0 Open Network Automation Platform (ONAP)
- local/robot 2.0.0 A helm Chart for kubernetes-ONAP Robot
- local/so 2.0.0 ONAP Service Orchestrator
+ local/appc 11.0.0 Application Controller
+ local/clamp 11.0.0 ONAP Clamp
+ local/common 11.0.0 Common templates for inclusion in other charts
+ local/onap 11.0.0 Open Network Automation Platform (ONAP)
+ local/robot 11.0.0 A helm Chart for kubernetes-ONAP Robot
+ local/so 11.0.0 ONAP Service Orchestrator
In any case, setup of the Helm repository is a one time activity.
To install a specific version of a single ONAP component (`so` in this example)
with the given release name enter::
- > helm deploy so onap/so --version 8.0.0 --set global.masterPassword=password --set global.flavor=unlimited --namespace onap
+ > helm deploy so onap/so --version 11.0.0 --set global.masterPassword=password --set global.flavor=unlimited --namespace onap
.. note::
The dependent components should be installed for component being installed
where the pod identifier refers to the auto-generated pod identifier.
-.. figure:: oomLogoV2-Configure.png
+.. figure:: images/oom_logo/oomLogoV2-Configure.png
:align: right
Configure
oValues [label="values.yaml"]
demo [label="onap-demo.yaml"]
prod [label="onap-production.yaml"]
- oReq [label="requirements.yaml"]
+ oReq [label="Chart.yaml"]
soValues [label="values.yaml"]
- soReq [label="requirements.yaml"]
+ soReq [label="Chart.yaml"]
mdValues [label="values.yaml"]
}
{
> helm deploy local/onap -n onap -f onap/resources/environments/onap-production.yaml --set global.masterPassword=password
-.. include:: environments_onap_demo.yaml
+.. include:: yaml/environments_onap_demo.yaml
:code: yaml
-When deploying all of ONAP a requirements.yaml file control which and what
-version of the ONAP components are included. Here is an excerpt of this
-file:
+When deploying all of ONAP, the dependencies section of the Chart.yaml file
+controls which and what version of the ONAP components are included.
+Here is an excerpt of this file:
.. code-block:: yaml
- # Referencing a named repo called 'local'.
- # Can add this repo by running commands like:
- # > helm serve
- # > helm repo add local http://127.0.0.1:8879
dependencies:
<...>
- name: so
- version: ~8.0.0
+ version: ~11.0.0
repository: '@local'
condition: so.enabled
<...>
-The ~ operator in the `so` version value indicates that the latest "8.X.X"
+The ~ operator in the `so` version value indicates that the latest "10.X.X"
version of `so` shall be used thus allowing the chart to allow for minor
-upgrades that don't impact the so API; hence, version 8.0.1 will be installed
+upgrades that don't impact the so API; hence, version 10.0.1 will be installed
in this case.
The onap/resources/environment/dev.yaml (see the excerpt below) enables
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
+In this example, use the 11.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
| 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.
+ - 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.
+ 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"'
+ - 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.
+ 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
+.. figure:: images/oom_logo/oomLogoV2-Monitor.png
:align: right
Monitor
view the current health status of all of the ONAP components for which agents
have been created - a sample from the ONAP Integration labs follows:
-.. figure:: consulHealth.png
+.. figure:: images/consul/consulHealth.png
:align: center
To see the real-time health of a deployment go to: ``http://<kubernetes IP>:30270/ui/``
If Consul GUI is not accessible, you can refer this
`kubectl port-forward <https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/>`_ method to access an application
-.. figure:: oomLogoV2-Heal.png
+.. figure:: images/oom_logo/oomLogoV2-Heal.png
:align: right
Heal
> kubectl get pods --all-namespaces -o=wide
-.. figure:: oomLogoV2-Scale.png
+.. figure:: images/oom_logo/oomLogoV2-Scale.png
:align: right
Scale
> helm list
NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
- dev 1 Wed Oct 14 13:49:52 2020 DEPLOYED onap-8.0.0 Honolulu onap
- dev-cassandra 5 Thu Oct 15 14:45:34 2020 DEPLOYED cassandra-8.0.0 onap
- dev-contrib 1 Wed Oct 14 13:52:53 2020 DEPLOYED contrib-8.0.0 onap
- dev-mariadb-galera 1 Wed Oct 14 13:55:56 2020 DEPLOYED mariadb-galera-8.0.0 onap
+ dev 1 Wed Oct 14 13:49:52 2020 DEPLOYED onap-11.0.0 Kohn onap
+ dev-cassandra 5 Thu Oct 15 14:45:34 2020 DEPLOYED cassandra-11.0.0 onap
+ dev-contrib 1 Wed Oct 14 13:52:53 2020 DEPLOYED contrib-11.0.0 onap
+ dev-mariadb-galera 1 Wed Oct 14 13:55:56 2020 DEPLOYED mariadb-galera-11.0.0 onap
Here the Name column shows the RELEASE NAME, In our case we want to try the
scale operation on cassandra, thus the RELEASE NAME would be dev-cassandra.
-Now we need to obtain the chart name for casssandra. Use the below
+Now we need to obtain the chart name for cassandra. Use the below
command to get the chart name::
> helm search cassandra
> helm search cassandra
NAME CHART VERSION APP VERSION DESCRIPTION
- local/cassandra 8.0.0 ONAP cassandra
- local/portal-cassandra 8.0.0 Portal cassandra
- local/aaf-cass 8.0.0 ONAP AAF cassandra
- local/sdc-cs 8.0.0 ONAP Service Design and Creation Cassandra
+ local/cassandra 11.0.0 ONAP cassandra
+ local/portal-cassandra 11.0.0 Portal cassandra
+ local/aaf-cass 11.0.0 ONAP AAF cassandra
+ local/sdc-cs 11.0.0 ONAP Service Design and Creation Cassandra
Here the Name column shows the chart name. As we want to try the scale
-operation for cassandra, thus the correponding chart name is local/cassandra
+operation for cassandra, thus the corresponding chart name is local/cassandra
Now we have both the command's arguments, thus we can perform the
-scale opeartion for cassandra as follows::
+scale operation for cassandra as follows::
> helm upgrade dev-cassandra local/cassandra --set replicaCount=3
-Using this command we can scale up or scale down the cassadra db instances.
+Using this command we can scale up or scale down the cassandra db instances.
The ONAP components use Kubernetes provided facilities to build clustered,
of how these capabilities can be used is described in the Running Consul on
Kubernetes tutorial.
-.. figure:: oomLogoV2-Upgrade.png
+.. figure:: images/oom_logo/oomLogoV2-Upgrade.png
:align: right
Upgrade
> helm list
NAME REVISION UPDATED STATUS CHART NAMESPACE
- so 1 Mon Feb 5 10:05:22 2020 DEPLOYED so-8.0.0 onap
+ so 1 Mon Feb 5 10:05:22 2020 DEPLOYED so-11.0.0 onap
When upgrading a cluster a parameter controls the minimum size of the cluster
during the upgrade while another parameter controls the maximum number of nodes
For example, to upgrade a container by changing configuration, specifically an
environment value::
- > helm upgrade so onap/so --version 8.0.1 --set enableDebug=true
+ > helm upgrade so onap/so --version 11.0.1 --set enableDebug=true
Issuing this command will result in the appropriate container being stopped by
Kubernetes and replaced with a new container with the new environment value.
To upgrade a component to a new version with a new configuration file enter::
- > helm upgrade so onap/so --version 8.0.1 -f environments/demo.yaml
+ > helm upgrade so onap/so --version 11.0.1 -f environments/demo.yaml
To fetch release history enter::
> helm history so
REVISION UPDATED STATUS CHART DESCRIPTION
- 1 Mon Feb 5 10:05:22 2020 SUPERSEDED so-8.0.0 Install complete
- 2 Mon Feb 5 10:10:55 2020 DEPLOYED so-8.0.1 Upgrade complete
+ 1 Mon Jul 5 10:05:22 2022 SUPERSEDED so-11.0.0 Install complete
+ 2 Mon Jul 5 10:10:55 2022 DEPLOYED so-11.0.1 Upgrade complete
Unfortunately, not all upgrades are successful. In recognition of this the
lineup of pods within an ONAP deployment is tagged such that an administrator
> helm history so
REVISION UPDATED STATUS CHART DESCRIPTION
- 1 Mon Feb 5 10:05:22 2020 SUPERSEDED so-8.0.0 Install complete
- 2 Mon Feb 5 10:10:55 2020 SUPERSEDED so-8.0.1 Upgrade complete
- 3 Mon Feb 5 10:14:32 2020 DEPLOYED so-8.0.0 Rollback to 1
+ 1 Mon Jul 5 10:05:22 2022 SUPERSEDED so-11.0.0 Install complete
+ 2 Mon Jul 5 10:10:55 2022 SUPERSEDED so-11.0.1 Upgrade complete
+ 3 Mon Jul 5 10:14:32 2022 DEPLOYED so-11.0.0 Rollback to 1
.. note::
The previous so pod will be terminated and a new so pod with an updated so
container will be created.
-.. figure:: oomLogoV2-Delete.png
+.. figure:: images/oom_logo/oomLogoV2-Delete.png
:align: right
Delete