X-Git-Url: https://gerrit.onap.org/r/gitweb?p=oom.git;a=blobdiff_plain;f=docs%2Foom_user_guide.rst;h=019d84363f9e8a17436786b07544541b47e4147f;hp=df9c8413cc09fa964b4af294e68b56ad72363a84;hb=370c6dc33e55bfee7b3b79bcc21481b02a3f1e24;hpb=08b973568127ca4cffbfdb86c3525a3a4addb188 diff --git a/docs/oom_user_guide.rst b/docs/oom_user_guide.rst index df9c8413cc..019d84363f 100644 --- a/docs/oom_user_guide.rst +++ b/docs/oom_user_guide.rst @@ -1,7 +1,7 @@ .. 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 @@ -15,8 +15,8 @@ .. _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 @@ -55,8 +55,8 @@ ONAP with a few simple commands. 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 Cert-Manager +and Helm setup as a one time activity. Install Kubectl ~~~~~~~~~~~~~~~ @@ -64,7 +64,7 @@ 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.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 @@ -76,15 +76,20 @@ Verify that the Kubernetes config is correct:: > 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 Cert-Manager +~~~~~~~~~~~~~~~~~~~~ +Details on how to install Cert-Manager can be found +:doc:`here `. 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:: @@ -113,7 +118,7 @@ stable which should be removed to avoid confusion:: 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 @@ -151,43 +156,46 @@ system, and looks for matches:: > 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. @@ -196,7 +204,11 @@ deployment:: 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:: @@ -232,9 +244,9 @@ precedence of all. 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"] } { @@ -302,35 +314,31 @@ value for the vnfDeployment/openstack/oam_network_cidr key as shown below. 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 :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` @@ -432,23 +440,24 @@ the portal and then simply access now the new ssl-encrypted URL: | 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 :align: right @@ -485,6 +494,9 @@ have been created - a sample from the ONAP Integration labs follows: To see the real-time health of a deployment go to: ``http://: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 `_ method to access an application .. figure:: oomLogoV2-Heal.png :align: right @@ -536,7 +548,49 @@ component. Here is an excerpt that shows this parameter: 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_, @@ -586,7 +640,7 @@ Prior to doing an upgrade, determine of the status of the deployed charts:: > 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 @@ -609,21 +663,21 @@ sequence of events described in the previous paragraph would be initiated. 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 @@ -645,9 +699,9 @@ For example, to roll-back back to previous system revision 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 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:: @@ -706,8 +760,8 @@ 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 @@ -717,6 +771,17 @@ To completely delete a release and remove it from the internal store enter:: > helm undeploy onap +Once complete undeploy is done then delete the namespace as well +using following command:: + + > kubectl delete 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::