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