.. 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 both the Kubernetes `kubectl` and Helm setup as a
-one time activity.
+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.8.10/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
> kubectl get pods --all-namespaces
-At this point you should see six Kubernetes pods running.
+At this point you should see Kubernetes pods running.
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 jakarta --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 10.0.0 Application Controller
+ local/clamp 10.0.0 ONAP Clamp
+ local/common 10.0.0 Common templates for inclusion in other charts
+ local/onap 10.0.0 Open Network Automation Platform (ONAP)
+ local/robot 10.0.0 A helm Chart for kubernetes-ONAP Robot
+ local/so 10.0.0 ONAP Service Orchestrator
In any case, setup of the Helm repository is a one time activity.
-Next, install Helm Plugins required to deploy the ONAP Casablanca release::
+Next, install Helm Plugins required to deploy the ONAP release::
> cp -R ~/oom/kubernetes/helm/plugins/ ~/.local/share/helm/plugins
Once the repo is setup, installation of ONAP can be done with a single
command::
- > helm deploy development local/onap --namespace onap
+ > helm deploy development local/onap --namespace onap --set global.masterPassword=password
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 deploy development local/onap --namespace onap -f overrides.yaml
+
+
+ > helm deploy development local/onap --namespace onap -f overrides.yaml --set global.masterPassword=password
+
+.. note::
+ Refer the Configure_ section on how to update overrides.yaml and values.yaml
To get a summary of the status of all of the pods (containers) running in your
deployment::
- > kubectl get pods --all-namespaces -o=wide
+ > kubectl get pods --namespace onap -o=wide
.. note::
The Kubernetes namespace concept allows for multiple instances of a component
(such as all of ONAP) to co-exist with other components in the same
Kubernetes cluster by isolating them entirely. Namespaces share only the
hosts that form the cluster thus providing isolation between production and
- development systems as an example. The OOM deployment of ONAP in Beijing is
- now done within a single Kubernetes namespace where in Amsterdam a namespace
- was created for each of the ONAP components.
+ development systems as an example.
.. note::
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)
with the given release name enter::
- > helm deploy so onap/so --version 3.0.1
+ > helm deploy so onap/so --version 10.0.0 --set global.masterPassword=password --set global.flavor=unlimited --namespace onap
+
+.. note::
+ The dependent components should be installed for component being installed
+
To display details of a specific resource or group of resources type::
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"]
}
{
To deploy ONAP with this environment file, enter::
- > helm deploy local/onap -n onap -f environments/onap-production.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: ~2.0.0
+ version: ~10.0.0
repository: '@local'
condition: so.enabled
<...>
-The ~ operator in the `so` version value indicates that the latest "2.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 2.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/onap-dev.yaml (see the excerpt below) enables
+The onap/resources/environment/dev.yaml (see the excerpt below) enables
for fine grained control on what components are included as part of this
deployment. By changing this `so` line to `enabled: false` the `so` component
will not be deployed. If this change is part of an upgrade the existing `so`
| 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/``
where a GUI much like the following will be found:
+.. note::
+ 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
In order to change the size of a cluster, an operator could use a helm upgrade
(described in detail in the next section) as follows::
- > helm upgrade --set replicaCount=3 onap/so/mariadb
+ > helm upgrade [RELEASE] [CHART] [flags]
+
+The RELEASE argument can be obtained from the following command::
+
+ > helm list
+
+Below is the example for the same::
+
+ > helm list
+ NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
+ dev 1 Wed Oct 14 13:49:52 2020 DEPLOYED onap-10.0.0 Jakarta onap
+ dev-cassandra 5 Thu Oct 15 14:45:34 2020 DEPLOYED cassandra-10.0.0 onap
+ dev-contrib 1 Wed Oct 14 13:52:53 2020 DEPLOYED contrib-10.0.0 onap
+ dev-mariadb-galera 1 Wed Oct 14 13:55:56 2020 DEPLOYED mariadb-galera-10.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 cassandra. Use the below
+command to get the chart name::
+
+ > helm search cassandra
+
+Below is the example for the same::
+
+ > helm search cassandra
+ NAME CHART VERSION APP VERSION DESCRIPTION
+ local/cassandra 10.0.0 ONAP cassandra
+ local/portal-cassandra 10.0.0 Portal cassandra
+ local/aaf-cass 10.0.0 ONAP AAF cassandra
+ local/sdc-cs 10.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 corresponding chart name is local/cassandra
+
+
+Now we have both the command's arguments, thus we can perform the
+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 cassandra db instances.
+
The ONAP components use Kubernetes provided facilities to build clustered,
highly available systems including: Services_ with load-balancers, ReplicaSet_,
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 2018 DEPLOYED so-2.0.1 default
+ so 1 Mon Feb 5 10:05:22 2020 DEPLOYED so-10.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 deploy onap onap/so --version 2.0.1 --set enableDebug=true
+ > helm upgrade so onap/so --version 8.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 deploy onap onap/so --version 2.0.2 -f environments/demo.yaml
+ > helm upgrade so onap/so --version 8.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 2018 SUPERSEDED so-2.0.1 Install complete
- 2 Mon Feb 5 10:10:55 2018 DEPLOYED so-2.0.2 Upgrade complete
+ 1 Mon Feb 5 10:05:22 2020 SUPERSEDED so-9.0.0 Install complete
+ 2 Mon Feb 5 10:10:55 2020 DEPLOYED so-10.0.0 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 2018 SUPERSEDED so-2.0.1 Install complete
- 2 Mon Feb 5 10:10:55 2018 SUPERSEDED so-2.0.2 Upgrade complete
- 3 Mon Feb 5 10:14:32 2018 DEPLOYED so-2.0.1 Rollback to 1
+ 1 Mon Feb 5 10:05:22 2020 SUPERSEDED so-9.0.0 Install complete
+ 2 Mon Feb 5 10:10:55 2020 SUPERSEDED so-10.0.0 Upgrade complete
+ 3 Mon Feb 5 10:14:32 2020 DEPLOYED so-9.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
Existing deployments can be partially or fully removed once they are no longer
needed. To minimize errors it is recommended that before deleting components
from a running deployment the operator perform a 'dry-run' to display exactly
-what will happen with a given command prior to actually deleting anything. For
-example::
+what will happen with a given command prior to actually deleting anything.
+For example::
> helm undeploy onap --dry-run
> helm undeploy onap
+Once complete undeploy is done then delete the namespace as well
+using following command::
+
+ > kubectl delete namespace <name of namespace>
+
+.. note::
+ You need to provide the namespace name which you used during deployment,
+ below is the example::
+
+ > kubectl delete namespace onap
+
One can also remove individual components from a deployment by changing the
ONAP configuration values. For example, to remove `so` from a running
deployment enter::