From: Krzysztof Opasiak Date: Thu, 1 Apr 2021 06:37:50 +0000 (+0000) Subject: Merge "[DOC] Update user guide doc" X-Git-Tag: 8.0.0~18 X-Git-Url: https://gerrit.onap.org/r/gitweb?p=oom.git;a=commitdiff_plain;h=94b5be41218a2d6be673dffd5fef938bfd995970;hp=fc84d43852eedf6ce97a9d51c596058910035e41 Merge "[DOC] Update user guide doc" --- diff --git a/docs/oom_user_guide.rst b/docs/oom_user_guide.rst index df9c8413cc..02f5c483b5 100644 --- a/docs/oom_user_guide.rst +++ b/docs/oom_user_guide.rst @@ -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.15.11/bin/linux/amd64/kubectl > chmod +x ./kubectl > sudo mv ./kubectl /usr/local/bin/kubectl > mkdir ~/.kube @@ -76,7 +76,7 @@ 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 Helm ~~~~~~~~~~~~ @@ -160,34 +160,37 @@ system, and looks for matches:: 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 +199,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 8.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:: @@ -302,7 +309,7 @@ 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 @@ -320,17 +327,17 @@ file: dependencies: <...> - name: so - version: ~2.0.0 + version: ~8.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 "8.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 8.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` @@ -485,6 +492,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 +546,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-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 + +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 +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 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 + +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 + + +Now we have both the command's arguments, thus we can perform the +scale opeartion 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. + The ONAP components use Kubernetes provided facilities to build clustered, highly available systems including: Services_ with load-balancers, ReplicaSet_, @@ -586,7 +638,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-8.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 +661,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-8.0.0 Install complete + 2 Mon Feb 5 10:10:55 2020 DEPLOYED so-8.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 @@ -645,9 +697,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-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 .. note:: @@ -706,8 +758,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 +769,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::