docs/oom_quickstart_guide.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2019-2020 Amdocs, Bell Canada, Orange, Samsung
   5 .. _oom_quickstart_guide:
   6 .. _quick-start-label:
   7
   8 OOM Quick Start Guide
   9 #####################
  10
  11 .. figure:: oomLogoV2-medium.png
  12    :align: right
  13
  14 Once a Kubernetes environment is available (follow the instructions in
  15 :ref:`cloud-setup-guide-label` if you don't have a cloud environment
  16 available), follow the following instructions to deploy ONAP.
  17
  18 **Step 1.** Clone the OOM repository from ONAP gerrit::
  19
  20   > git clone -b <BRANCH> http://gerrit.onap.org/r/oom --recurse-submodules
  21   > cd oom/kubernetes
  22
  23 where <BRANCH> can be an official release tag, such as
  24
  25 * 4.0.0-ONAP for Dublin
  26 * 5.0.1-ONAP for El Alto
  27 * 6.0.0 for Frankfurt
  28 * 7.0.0 for Guilin
  29
  30 **Step 2.** Install Helm Plugins required to deploy ONAP::
  31
  32   > sudo cp -R ~/oom/kubernetes/helm/plugins/ ~/.helm
  33
  34
  35 **Step 3.** Customize the Helm charts like `oom/kubernetes/onap/values.yaml` or
  36 an override file like `onap-all.yaml`, `onap-vfw.yaml` or `openstack.yaml` file
  37 to suit your deployment with items like the OpenStack tenant information.
  38
  39 .. note::
  40   Standard and example override files (e.g. `onap-all.yaml`, `openstack.yaml`) can be found in
  41   the `oom/kubernetes/onap/resources/overrides/` directory.
  42
  43
  44  a. You may want to selectively enable or disable ONAP components by changing
  45     the ``enabled: true/false`` flags.
  46
  47
  48  b. Encrypt the OpenStack password using the shell tool for Robot and put it in
  49     the Robot Helm charts or Robot section of `openstack.yaml`
  50
  51
  52  c. Encrypt the OpenStack password using the java based script for SO Helm charts
  53     or SO section of `openstack.yaml`.
  54
  55
  56  d. Update the OpenStack parameters that will be used by Robot, SO and APPC Helm
  57     charts or use an override file to replace them.
  58
  59  e. Add in the command line a value for the global master password (global.masterPassword).
  60
  61
  62
  63 a. Enabling/Disabling Components:
  64 Here is an example of the nominal entries that need to be provided.
  65 We have different values file available for different contexts.
  66
  67 .. literalinclude:: ../kubernetes/onap/values.yaml
  68    :language: yaml
  69
  70
  71 b. Generating ROBOT Encrypted Password:
  72 The Robot encrypted Password uses the same encryption.key as SO but an
  73 openssl algorithm that works with the python based Robot Framework.
  74
  75 .. note::
  76   To generate Robot ``openStackEncryptedPasswordHere``::
  77
  78     cd so/resources/config/mso/
  79     /oom/kubernetes/so/resources/config/mso# echo -n "<openstack tenant password>" | openssl aes-128-ecb -e -K `cat encryption.key` -nosalt | xxd -c 256 -p``
  80
  81   Use OS_PASSWORD value from openstack .RC file for "openstack tenant password"
  82
  83 c. Generating SO Encrypted Password:
  84 The SO Encrypted Password uses a java based encryption utility since the
  85 Java encryption library is not easy to integrate with openssl/python that
  86 Robot uses in Dublin and upper versions.
  87
  88 .. note::
  89   To generate SO ``openStackEncryptedPasswordHere`` and ``openStackSoEncryptedPassword``
  90   ensure `default-jdk` is installed::
  91
  92     sudo apt-get update; sudo apt-get install default-jdk
  93
  94   Then execute::
  95
  96     SO_ENCRYPTION_KEY=`cat ~/oom/kubernetes/so/resources/config/mso/encryption.key`
  97     OS_PASSWORD=XXXX_OS_CLEARTESTPASSWORD_XXXX
  98
  99     git clone http://gerrit.onap.org/r/integration
 100     cd integration/deployment/heat/onap-rke/scripts
 101
 102     javac Crypto.java
 103     java Crypto "$OS_PASSWORD" "$SO_ENCRYPTION_KEY"
 104
 105 d. Update the OpenStack parameters:
 106
 107 There are assumptions in the demonstration VNF Heat templates about the
 108 networking available in the environment. To get the most value out of these
 109 templates and the automation that can help confirm the setup is correct, please
 110 observe the following constraints.
 111
 112
 113 ``openStackPublicNetId:``
 114   This network should allow Heat templates to add interfaces.
 115   This need not be an external network, floating IPs can be assigned to the
 116   ports on the VMs that are created by the heat template but its important that
 117   neutron allow ports to be created on them.
 118
 119 ``openStackPrivateNetCidr: "10.0.0.0/16"``
 120   This ip address block is used to assign OA&M addresses on VNFs to allow ONAP
 121   connectivity. The demonstration Heat templates assume that 10.0 prefix can be
 122   used by the VNFs and the demonstration ip addressing plan embodied in the
 123   preload template prevent conflicts when instantiating the various VNFs. If
 124   you need to change this, you will need to modify the preload data in the
 125   Robot Helm chart like integration_preload_parameters.py and the
 126   demo/heat/preload_data in the Robot container. The size of the CIDR should
 127   be sufficient for ONAP and the VMs you expect to create.
 128
 129 ``openStackOamNetworkCidrPrefix: "10.0"``
 130   This ip prefix mush match the openStackPrivateNetCidr and is a helper
 131   variable to some of the Robot scripts for demonstration. A production
 132   deployment need not worry about this setting but for the demonstration VNFs
 133   the ip asssignment strategy assumes 10.0 ip prefix.
 134
 135 .. note::
 136   Copy below required openstack.yaml file and update the parameters for the variables
 137   accordingly from openstack environment (openrc file) and replace
 138
 139 Example Keystone v2.0
 140
 141 .. literalinclude:: example-integration-override.yaml
 142    :language: yaml
 143
 144 Example Keystone v3  (required for Rocky and later releases)
 145
 146 .. literalinclude:: example-integration-override-v3.yaml
 147    :language: yaml
 148
 149
 150 **Step 4.** To setup a local Helm server to server up the ONAP charts::
 151
 152   > helm serve &
 153
 154 Note the port number that is listed and use it in the Helm repo add as
 155 follows::
 156
 157   > helm repo add local http://127.0.0.1:8879
 158
 159 **Step 5.** Verify your Helm repository setup with::
 160
 161   > helm repo list
 162   NAME   URL
 163   local  http://127.0.0.1:8879
 164
 165 **Step 6.** Build a local Helm repository (from the kubernetes directory)::
 166
 167   > make SKIP_LINT=TRUE [HELM_BIN=<HELM_PATH>] all
 168
 169 `HELM_BIN`
 170   Sets the helm binary to be used. The default value use helm from PATH. Allow
 171   the user to have multiple version of helm in operating system and choose
 172   which one to use.
 173
 174 **Step 7.** Display the onap charts that available to be deployed::
 175
 176   > helm search onap -l
 177
 178 .. literalinclude:: helm-search.txt
 179
 180 .. note::
 181   The setup of the Helm repository is a one time activity. If you make changes
 182   to your deployment charts or values be sure to use ``make`` to update your
 183   local Helm repository.
 184
 185 **Step 8.** Once the repo is setup, installation of ONAP can be done with a
 186 single command
 187
 188 .. note::
 189   The ``--timeout 900`` is currently required in Guilin and up to address long
 190   running initialization tasks for DMaaP and SO. Without this timeout value both
 191   applications may fail to deploy.
 192
 193 .. danger::
 194   We've added the master password on the command line.
 195   You shouldn't put it in a file for safety reason
 196   please don't forget to change the value to something random
 197
 198   A space is also added in front of the command so "history" doesn't catch it.
 199   This masterPassword is very sensitive, please be careful!
 200
 201
 202 To deploy all ONAP applications use this command::
 203
 204     > cd oom/kubernetes
 205     >  helm deploy dev local/onap --namespace onap --set global.masterPassword=myAwesomePasswordThatINeedToChange -f onap/resources/overrides/onap-all.yaml -f onap/resources/overrides/environment.yaml -f onap/resources/overrides/openstack.yaml --timeout 900
 206
 207 All override files may be customized (or replaced by other overrides) as per
 208 needs.
 209
 210 `onap-all.yaml`
 211   Enables the modules in the ONAP deployment. As ONAP is very modular, it is
 212   possible to customize ONAP and disable some components through this
 213   configuration file.
 214
 215 `onap-all-ingress-nginx-vhost.yaml`
 216   Alternative version of the `onap-all.yaml` but with global ingress controller
 217   enabled. It requires the cluster configured with the nginx ingress controller
 218   and load balancer. Please use this file instead `onap-all.yaml` if you want
 219   to use experimental ingress controller feature.
 220
 221 `environment.yaml`
 222   Includes configuration values specific to the deployment environment.
 223
 224   Example: adapt readiness and liveness timers to the level of performance of
 225   your infrastructure
 226
 227 `openstack.yaml`
 228   Includes all the OpenStack related information for the default target tenant
 229   you want to use to deploy VNFs from ONAP and/or additional parameters for the
 230   embedded tests.
 231
 232 **Step 9.** Verify ONAP installation
 233
 234 Use the following to monitor your deployment and determine when ONAP is ready
 235 for use::
 236
 237   > kubectl get pods -n onap -o=wide
 238
 239 .. note::
 240   While all pods may be in a Running state, it is not a guarantee that all components are running fine.
 241
 242   Launch the healthcheck tests using Robot to verify that the components are healthy::
 243
 244     > ~/oom/kubernetes/robot/ete-k8s.sh onap health
 245
 246   Launch Robot distribute health checks to verify whether ONAP runtime components are healthy::
 247
 248     > ~/oom/kubernetes/robot/ete-k8s.sh onap healthdist
 249
 250 **Step 10.** Undeploy ONAP
 251 ::
 252
 253   > helm undeploy dev --purge
 254
 255 .. note::
 256   After undeploy follow the below steps to cleanup everything before redeplying ONAP
 257
 258 ::
 259
 260   > kubectl delete namespace onap
 261
 262   > kubectl delete pv -n onap --all
 263
 264   > kubectl delete pvc -n onap --all
 265
 266   > sudo rm -rf /dockerdata-nfs/*
 267
 268 More examples of using the deploy and undeploy plugins can be found here: https://wiki.onap.org/display/DW/OOM+Helm+%28un%29Deploy+plugins