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 Amdocs, Bell Canada
   5
   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 4.0.0-ONAP http://gerrit.onap.org/r/oom --recurse-submodules
  21   > cd oom/kubernetes
  22
  23 **Step 2.** Install Helm Plugins required to deploy ONAP::
  24
  25   > sudo cp -R ~/oom/kubernetes/helm/plugins/ ~/.helm
  26
  27
  28 **Step 3.** Customize the helm charts like oom/kubernetes/onap/values.yaml or an override
  29 file like onap-all.yaml, onap-vfw.yaml or openstack.yaml file to suit your deployment with items like the
  30 OpenStack tenant information.
  31
  32 .. note::
  33   Standard and example override files (e.g. onap-all.yaml, openstack.yaml) can be found in
  34   the oom/kubernetes/onap/resources/overrides/ directory.
  35
  36
  37  a. You may want to selectively enable or disable ONAP components by changing
  38     the `enabled: true/false` flags.
  39
  40
  41  b. Encyrpt the OpenStack password using the shell tool for robot and put it in
  42     the robot helm charts or robot section of openstack.yaml
  43
  44
  45  c. Encrypt the OpenStack password using the java based script for SO helm charts
  46     or SO section of openstack.yaml.
  47
  48
  49  d. Update the OpenStack parameters that will be used by robot, SO and APPC helm
  50     charts or use an override file to replace them.
  51
  52
  53
  54
  55 a. Enabling/Disabling Components:
  56 Here is an example of the nominal entries that need to be provided.
  57 We have different values file available for different contexts.
  58
  59 .. literalinclude:: onap-values.yaml
  60    :language: yaml
  61
  62
  63 b. Generating ROBOT Encrypted Password:
  64 The ROBOT encrypted Password uses the same encryption.key as SO but an
  65 openssl algorithm that works with the python based Robot Framework.
  66
  67 .. note::
  68   To generate ROBOT openStackEncryptedPasswordHere :
  69
  70   ``cd so/resources/config/mso/``
  71
  72   ``/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``
  73
  74 c. Generating SO Encrypted Password:
  75 The SO Encrypted Password uses a java based encryption utility since the
  76 Java encryption library is not easy to integrate with openssl/python that
  77 ROBOT uses in Dublin.
  78
  79 .. note::
  80   To generate SO openStackEncryptedPasswordHere and openStackSoEncryptedPassword:
  81
  82   SO_ENCRYPTION_KEY=`cat ~/oom/kubernetes/so/resources/config/mso/encryption.key`
  83
  84   OS_PASSWORD=XXXX_OS_CLEARTESTPASSWORD_XXXX
  85
  86   git clone http://gerrit.onap.org/r/integration
  87
  88   cd integration/deployment/heat/onap-rke/scripts
  89
  90
  91   javac Crypto.java
  92
  93   [ if javac is not installed 'apt-get update ; apt-get install default-jdk' ]
  94
  95   java Crypto "$OS_PASSWORD" "$SO_ENCRYPTION_KEY"
  96
  97
  98 d. Update the OpenStack parameters:
  99
 100 There are assumptions in the demonstration VNF heat templates about the networking
 101 available in the environment. To get the most value out of these templates and the
 102 automation that can help confirm the setup is correct, please observe the following
 103 constraints.
 104
 105 openStackPublicNetId:
 106
 107 This network should allow heat templates to add interfaces.
 108 This need not be an external network, floating IPs can be assigned to the ports on
 109 the VMs that are created by the heat template but its important that neutron allow
 110 ports to be created on them.
 111
 112 openStackPrivateNetCidr: "10.0.0.0/16"
 113
 114 This ip address block is used to assign OA&M addresses on VNFs to allow ONAP connectivity.
 115 The demonstration heat templates assume that 10.0 prefix can be used by the VNFs and the
 116 demonstration ip addressing plan embodied in the preload template prevent conflicts when
 117 instantiating the various VNFs. If you need to change this, you will need to modify the preload
 118 data in the robot helm chart like integration_preload_parametes.py and the demo/heat/preload_data
 119 in the robot container. The size of the CIDR should be sufficient for ONAP and the VMs you expect
 120 to create.
 121
 122 openStackOamNetworkCidrPrefix: "10.0"
 123
 124 This ip prefix mush match the openStackPrivateNetCidr and is a helper variable to some of the
 125 robot scripts for demonstration. A production deployment need not worry about this
 126 setting but for the demonstration VNFs the ip asssignment strategy assumes 10.0 ip prefix.
 127
 128
 129 Example Keystone v2.0
 130 .. literalinclude:: example-integration-override.yaml
 131    :language: yaml
 132
 133 Example Keystone v3  (required for Rocky and later releases)
 134 .. literalinclude:: example-integration-override-v3.yaml
 135    :language: yaml
 136
 137
 138
 139 **Step 4.** To setup a local Helm server to server up the ONAP charts::
 140
 141   > helm serve &
 142
 143 Note the port number that is listed and use it in the Helm repo add as
 144 follows::
 145
 146   > helm repo add local http://127.0.0.1:8879
 147
 148 **Step 5.** Verify your Helm repository setup with::
 149
 150   > helm repo list
 151   NAME   URL
 152   local  http://127.0.0.1:8879
 153
 154 **Step 6.** Build a local Helm repository (from the kubernetes directory)::
 155
 156   > make all; make onap
 157
 158 **Step 7.** Display the onap charts that available to be deployed::
 159
 160   > helm search onap -l
 161
 162 .. literalinclude:: helm-search.txt
 163
 164 .. note::
 165   The setup of the Helm repository is a one time activity. If you make changes to your deployment charts or values be sure to use `make` to update your local Helm repository.
 166
 167 **Step 8.** Once the repo is setup, installation of ONAP can be done with a
 168 single command
 169
 170 .. note::
 171   The --timeout 900 is currently required in Dublin to address long running initialization tasks
 172   for DMaaP and SO. Without this timeout value both applications may fail to deploy.
 173
 174  a. To deploy all ONAP applications use this command::
 175
 176     > cd oom/kubernetes
 177     > helm deploy dev local/onap --namespace onap -f onap/resources/overrides/onap-all.yaml -f onap/resources/overrides/openstack.yaml --timeout 900
 178
 179  b. If you are using a custom override (e.g. integration-override.yaml) use this command::
 180
 181     > helm deploy dev local/onap -f /root/integration-override.yaml --namespace onap --timeout 900
 182
 183
 184  c. If you have a slower cloud environment you may want to use the public-cloud.yaml
 185     which has longer delay intervals on database updates.::
 186
 187     > helm deploy dev local/onap -f /root/oom/kubernetes/onap/resources/environments/public-cloud.yaml -f /root/integration-override.yaml --namespace onap --timeout 900
 188
 189
 190 **Step 9.** Commands to interact with the OOM installation
 191
 192 Use the following to monitor your deployment and determine when ONAP is
 193 ready for use::
 194
 195   > kubectl get pods -n onap -o=wide
 196
 197 Undeploying onap can be done using the following command::
 198
 199   > helm undeploy dev --purge
 200
 201
 202 More examples of using the deploy and undeploy plugins can be found here: https://wiki.onap.org/display/DW/OOM+Helm+%28un%29Deploy+plugins