docs/guides/onap-developer/settingup/onap_heat.rst

   1 .. This work is licensed undera Creative Commons Attribution 4.0
   2 .. International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2017-2018 ONAP
   5
   6
   7 .. contents::
   8    :depth: 2
   9 ..
  10
  11 .. index:: Setting Up Full ONAP using Virtual Machines
  12
  13
  14 ===============================================
  15 **Setting Up Full ONAP using Virtual Machines**
  16 ===============================================
  17
  18 .. _demo-installing-running-onap:
  19
  20 **Context**
  21 ===========
  22 ONAP may be deployed in different contexts depending on your requirements.
  23 The recommended installation for Beijng Release over virtual machines is based
  24 on OpenStack HEAT Template.
  25
  26 The VNFs managed by ONAP may be deployed in different OpenStack tenants or
  27 based on top of VMware based infrastructure. For details, refer
  28 :ref:`to MultiCloud project<index-multicloud>`.
  29
  30 The current installation is based on the single tenant deployment (all the ONAP
  31 components will be hosted in a unique tenant).
  32
  33 .. _demo-installing-running-onap-requirements:
  34
  35 **Requirements**
  36 ================
  37
  38 OpenStack
  39 ---------
  40 ONAP installation is validated on
  41 `OpenStack Ocata <https://releases.openstack.org/ocata/>`_ or latter release.
  42
  43 You can use various Cloud providers offering OpenStack based solutions.
  44 A list of available Cloud providers on the
  45 `OpenStack marketplace <https://www.openstack.org/marketplace/public-clouds/>`_.
  46
  47 You can use your private Cloud infrastructure.
  48
  49 The following OpenStack components must be deployed in the infrastructure:
  50  - *Cinder*
  51  - *Glance*
  52  - *Heat*
  53  - *Horizon*
  54  - *Keystone*
  55  - *Neutron*
  56  - *Nova*
  57
  58 To deploy OpenStack, you can use various solutions:
  59  - `OpenStack installation guide <https://docs.openstack.org/install-guide/>`_
  60  - `OPNFV Cross Community Continuous Integration - XCI installer <http://docs.opnfv.org/en/latest/infrastructure/xci.html>`_
  61  - `OpenStack Ocata installation guide <https://docs.openstack.org/ocata/install/>`_
  62
  63 .. tip::
  64  - Notice the documentation version mentioned in the URL, e.g. ocata/, pike/,
  65    latest/ ...
  66  - The installation is pretty huge, some automated scripts have been created by
  67    the community:
  68
  69   - `OpenStack installation with Ansible (All openstack services) <https://docs.openstack.org/openstack-ansible/latest/>`_
  70   - `OpenStack Ocata installation scripts for testing environment(DO NOT install Heat, Designate and Cinder Volume services) <https://github.com/reachsrirams/openstack-scripts>`_
  71
  72 The OpenStack infrastructure must enable internet access and you need to have
  73 an "External network" already configured properly.
  74 The External network ID will have to be provided in the Heat environment file.
  75
  76 ONAP components
  77 ---------------
  78 The following table presents the mapping between the created VM and the ONAP
  79 components, and provides VM information (flavor and image):
  80
  81     ===================  =================   =======  ============
  82     VM name              ONAP project(s)     Flavor   Image
  83     ===================  =================   =======  ============
  84     onap-aai-inst1       AAI                 xlarge   Ubuntu 14.04
  85     onap-aai-inst2       AAI/UI              xlarge   Ubuntu 14.04
  86     onap-appc            APPC, CCSDK         large    Ubuntu 14.04
  87     onap-clamp           CLAMP               medium   Ubuntu 16.04
  88     onap-dns-server      *Internal DNS*      small    Ubuntu 14.04
  89     onap-message-router  DMAAP               large    Ubuntu 14.04
  90     onap-multi-service   MSB, VF-C, VNFSDK   xlarge   Ubuntu 16.04
  91     onap-policy          Policy              xlarge   Ubuntu 14.04
  92     onap-portal          Portal, CLI         large    Ubuntu 14.04
  93     onap-robot           Integration         medium   Ubuntu 16.04
  94     onap-sdc             SDC                 xlarge   Ubuntu 16.04
  95     onap-sdnc            SDNC, CCSDK         large    Ubuntu 14.04
  96     onap-so              SO                  large    Ubuntu 16.04
  97     onap-vid             VID                 medium   Ubuntu 14.04
  98     onap-dcae            DCAE, Holmes        xlarge   Ubuntu 16.04
  99     onap-music           Music               large    Ubuntu 14.04
 100     onap-oof             OOF                 large    Ubuntu 16.04
 101     onap-aaf             AAF                 medium   Ubuntu 16.04
 102     onap-sms             AAF                 medium   Ubuntu 16.04
 103     onap-nbi             External API        small    Ubuntu 16.04
 104     ===================  =================   =======  ============
 105
 106 Footprint
 107 ---------
 108 The ONAP installation requires the following footprint:
 109  - 20 VM
 110  - 88 vCPU
 111  - 176 GB RAM
 112  - 1.76 TB Storage
 113  - 20 floating IP addresses
 114
 115 .. Note: You should also reserve some resources for the VNFs to be deployed.
 116
 117 Artifacts
 118 ---------
 119 The following artifacts must be deployed on the OpenStack infrastructure:
 120  - a public SSH key to access the various VM
 121  - Ubuntu 14.04 image (https://cloud-images.ubuntu.com/releases/14.04/14.04/)
 122  - Ubuntu 16.04 image (https://cloud-images.ubuntu.com/releases/16.04/release/)
 123  - Set of flavors: small, medium, large, xlarge
 124
 125 .. Note: The floating IP may be private IP.
 126
 127 .. Note: Basic flavors can reuse the default flavors as defined by
 128    OpenStack
 129    <https://docs.openstack.org/horizon/latest/admin/manage-flavors.html>`_
 130
 131 Security
 132 --------
 133 The default installation assumes that the Default security group is configured
 134 to enable full access between the ONAP components.
 135 Depending on your environment, we may need to open some security groups
 136 (eg when using the portal from your desktop).
 137
 138 The list of various services and ports used can be found on the
 139 `ONAP wiki - ports <https://wiki.onap.org/display/DW/ONAP+Services+List#ONAPServicesList-ONAPServices>`_.
 140
 141 **Deployment**
 142 ==============
 143
 144 Source files
 145 ------------
 146
 147 Both following files must be downloaded and configured to match your
 148 configuration:
 149
 150 - Template file:
 151   https://git.onap.org/demo/plain/heat/ONAP/onap_openstack.yaml
 152 - Environment file:
 153   https://git.onap.org/demo/plain/heat/ONAP/onap_openstack.env
 154
 155 The environment file must be customized as described in the following sections.
 156
 157 .. Note Beijing release files
 158
 159 Description
 160 -----------
 161
 162 The ONAP Heat template spins up all the components including the DCAE.
 163 The template, onap_openstack.yaml, comes with an environment file,
 164 onap_openstack.env, in which all the default values are defined.
 165
 166 The Heat template is composed of two sections: (i) parameters, and (ii)
 167 resources.
 168 The parameter section contains the declaration and
 169 description of the parameters that will be used to spin up ONAP, such as
 170 public network identifier, URLs of code and artifacts repositories, etc.
 171 The default values of these parameters can be found in the environment
 172 file.
 173
 174 The resource section contains the definition of:
 175
 176 - ONAP Private Management Network, which ONAP components use to communicate
 177   with each other and with VNFs
 178 - ONAP Virtual Machines (VMs)
 179 - Public key pair used to access ONAP VMs
 180 - Virtual interfaces towards the ONAP Private Management Network
 181 - Disk volumes
 182
 183 Each VM specification includes Operating System image name, VM size
 184 (i.e. flavor), VM name, etc. Each VM has two virtual network interfaces:
 185 one towards the public network and one towards the ONAP Private
 186 Management network, as described above. Furthermore, each VM runs a
 187 post-instantiation script that downloads and installs software
 188 dependencies (e.g. Java JDK, gcc, make, Python, ...) and ONAP software
 189 packages and Docker containers from remote repositories.
 190
 191 When the Heat template is executed, the OpenStack Heat engine creates
 192 the resources defined in the Heat template, based on the parameters
 193 values defined in the environment file.
 194
 195 Environment file
 196 ----------------
 197
 198 Before running Heat, it is necessary to customize the environment file.
 199 Indeed, some parameters, namely public_net_id, pub_key,
 200 openstack_tenant_id, openstack_username, and openstack_api_key,
 201 need to be set depending on the user's environment:
 202
 203 **Global parameters**
 204
 205 ::
 206
 207  public_net_id:       PUT YOUR NETWORK ID/NAME HERE
 208  pub_key:             PUT YOUR PUBLIC KEY HERE
 209  openstack_tenant_id: PUT YOUR OPENSTACK PROJECT ID HERE
 210  openstack_username:  PUT YOUR OPENSTACK USERNAME HERE
 211  openstack_api_key:   PUT YOUR OPENSTACK PASSWORD HERE
 212  keystone_url:        PUT THE KEYSTONE URL HERE (do not include version number)
 213
 214 openstack_region parameter is set to RegionOne (OpenStack default). If
 215 your OpenStack is using another Region, please modify this parameter.
 216
 217 public_net_id is the unique identifier (UUID) or name of the public
 218 network of the cloud provider. To get the public_net_id, use the
 219 following OpenStack CLI command (ext is the name of the external
 220 network, change it with the name of the external network of your
 221 installation)
 222
 223 ::
 224
 225  openstack network list  | grep ext |  awk '{print $2}'
 226
 227 pub_key is string value of the public key that will be installed in
 228 each ONAP VM. To create a public/private key pair in Linux, please
 229 execute the following instruction:
 230
 231 ::
 232
 233  user@ubuntu:~$ ssh-keygen -t rsa
 234
 235 The following operations create the public/private key pair:
 236
 237 ::
 238
 239  Generating public/private rsa key pair.
 240  Enter file in which to save the key (/home/user/.ssh/id_rsa):
 241  Created directory '/home/user/.ssh'.
 242  Enter passphrase (empty for no passphrase):
 243  Enter same passphrase again:
 244  Your identification has been saved in /home/user/.ssh/id_rsa.
 245  Your public key has been saved in /home/user/.ssh/id_rsa.pub.
 246
 247 openstack_username, openstack_tenant_id (password), and
 248 openstack_api_key are user's credentials to access the
 249 OpenStack-based cloud.
 250
 251 **Images and flavors parameters**
 252
 253 ::
 254
 255  ubuntu_1404_image:  PUT THE UBUNTU 14.04 IMAGE NAME HERE
 256  ubuntu_1604_image:  PUT THE UBUNTU 16.04 IMAGE NAME HERE
 257  flavor_small:       PUT THE SMALL FLAVOR NAME HERE
 258  flavor_medium:      PUT THE MEDIUM FLAVOR NAME HERE
 259  flavor_large:       PUT THE LARGE FLAVOR NAME HERE
 260  flavor_xlarge:      PUT THE XLARGE FLAVOR NAME HERE
 261
 262 To get the images in your OpenStack environment, use the following
 263 OpenStack CLI command:
 264
 265 ::
 266
 267         openstack image list | grep 'ubuntu'
 268
 269 To get the flavor names used in your OpenStack environment, use the
 270 following OpenStack CLI command:
 271
 272 ::
 273
 274         openstack flavor list
 275
 276 **Network parameters**
 277
 278 ::
 279
 280  dns_list: PUT THE ADDRESS OF THE EXTERNAL DNS HERE (e.g. a comma-separated list
 281  of IP addresses in your /etc/resolv.conf in UNIX-based Operating Systems)
 282  external_dns: PUT THE FIRST ADDRESS OF THE EXTERNAL DNS LIST HERE
 283  dns_forwarder: PUT THE IP OF DNS FORWARDER FOR ONAP DEPLOYMENT'S OWN DNS SERVER
 284  oam_network_cidr: 10.0.0.0/16
 285
 286 You can use the Google Public DNS 8.8.8.8 and 4.4.4.4 address or your internal
 287 DNS servers.
 288
 289 ONAP installs a DNS server used to resolve IP addresses in the ONAP OAM private
 290 network.
 291
 292 **DCAE Parameters**
 293
 294 For Beijing Release, all the DCAE components are deployed in a single
 295 virtual machine.
 296 You must specify R2 to run R2 DCAE components.
 297 Is you are using R1 to get R1 ONAP, you must fill all the other
 298 DCAE parameters.
 299 Please refer to the Amsterdam documentation to fill these parameters.
 300 ::
 301
 302   dcae_deployment_profile: PUT DCAE DEPLOYMENT PROFILE (R1, R2MVP, R2, or R2PLUS)
 303
 304 Instantiation
 305 -------------
 306
 307 The ONAP platform can be instantiated via Horizon (OpenStack dashboard)
 308 or Command Line.
 309
 310 **Instantiation via Horizon:**
 311
 312 - Login to Horizon URL with your personal credentials
 313 - Click "Stacks" from the "Orchestration" menu
 314 - Click "Launch Stack"
 315 - Paste or manually upload the Heat template file (onap_openstack.yaml) in the
 316   "Template Source" form
 317 - Paste or manually upload the Heat environment file (onap_openstack.env) in
 318   the "Environment Source" form
 319 - Click "Next" - Specify a name in the "Stack Name" form
 320 - Provide the password in the "Password" form
 321 - Click "Launch"
 322
 323 **Instantiation via Command Line:**
 324
 325 - You need to have the OpenStack Heat service installed:
 326
 327 - Create a file (named i.e. ~/openstack/openrc) that sets all the
 328   environmental variables required to access your OpenStack tenant:
 329
 330 ::
 331
 332  export OS_AUTH_URL=INSERT THE AUTH URL HERE
 333  export OS_USERNAME=INSERT YOUR USERNAME HERE
 334  export OS_TENANT_ID=INSERT YOUR TENANT ID HERE
 335  export OS_REGION_NAME=INSERT THE REGION HERE
 336  export OS_PASSWORD=INSERT YOUR PASSWORD HERE
 337  export OS_USER_DOMAIN_NAME=INSERT YOUR DOMAIN HERE
 338  export OS_PROJECT_NAME=INSERT YOUR PROJECT NAME HERE
 339
 340 -  Run the script from command line:
 341
 342 ::
 343
 344  source ~/openstack/openrc
 345
 346 -  In order to install the ONAP platform, type:
 347
 348 ::
 349
 350  # Old Heat client
 351
 352 ::
 353
 354  heat stack-create STACK_NAME -f PATH_TO_HEAT_TEMPLATE(YAML FILE)
 355  -e PATH_TO_ENV_FILE
 356
 357  OR
 358
 359 ::
 360
 361  # New OpenStack client
 362  openstack stack create -t PATH_TO_HEAT_TEMPLATE(YAML FILE)
 363  -e PATH_TO_ENV_FILE STACK_NAME
 364
 365
 366 .. Note The Heat template deployment may take time (up to one hour)
 367    depending on your hardware environment.
 368
 369 Test the installation
 370 ---------------------
 371 Every ONAP component offers a HealthCheck REST API. The Robot Virtual Machine
 372 (*onap-robot*) can be used to test that every components run smoothly.
 373 Run the following command to perform the HealthCheck:
 374
 375 .. code-block:: bash
 376
 377   docker exec -it openecompete_container /var/opt/OpenECOMP_ETE/runTags.sh
 378   -i health
 379   -d ./html
 380   -V /share/config/integration_robot_properties.py
 381   -V /share/config/integration_preload_parameters.py
 382   -V /share/config/vm_properties.py
 383
 384 This test suite will execute 40 tests towards the various ONAP components.
 385
 386 After the installation, it is possible to deploy the various use-cases
 387 described in `ONAP wiki - demos <https://wiki.onap.org/display/DW/Running+the+ONAP+Demos>`_.
 388
 389 Detect problems
 390 ---------------
 391 If all the tests are not OK, many causes are possible.
 392 Here is a simple procedure to detect where the problem occurs:
 393
 394 * Check the OpenStack Virtual Machine logs
 395 * Connect to the Virtual Machine and check that the various containers are
 396   running.
 397
 398 The list of containers are described on the `ONAP wiki - containers <https://wiki.onap.org/display/DW/ONAP+Services+List#ONAPServicesList-ONAPServices>`_.
 399 In case some containers are missing, check the Docker logs using the following
 400 command:
 401
 402 .. code-block:: bash
 403
 404  sudo docker ps -a
 405  sudo docker logs <containerid>
 406
 407 **Portal configuration**
 408 ========================
 409 The current ONAP installation is using the *onap.org* domain.
 410 To use the portal on your desktop, you must configure the following information
 411 in your *host* file (located in /etc/host for Linux or
 412 /windows/system32/drivers/etc/hosts for Windows):
 413
 414 .. code-block:: bash
 415
 416  <onap-policy_ip>      policy.api.simpledemo.onap.org
 417  <onap-portal_ip>      portal.api.simpledemo.onap.org
 418  <onap-sdc_ip>         sdc.api.simpledemo.onap.org
 419  <onap-vid_ip>         vid.api.simpledemo.onap.org
 420  <onap-aai-inst1_ip>   aai.api.simpledemo.onap.org
 421  <onap-aai-inst2_ip>   aai.ui.simpledemo.onap.org
 422
 423
 424 You can use the Horizon dashboard to get the IP addresses associated with the
 425 Virtual Machines or use the following command line:
 426
 427 .. code-block:: bash
 428
 429  openstack server list
 430
 431 Launch the portal on the
 432 http://portal.api.simpledemo.onap.org:8989/ONAPPORTAL/login.htm
 433
 434 Various users are predefined as presented in the following table:
 435
 436   .. csv-table::
 437    :header: Role, Login
 438    :widths: 20, 20
 439
 440     Superuser,demo
 441     Designer,cs0008
 442     Tester,jm0007
 443     Governor,gv0001
 444     Ops,op0001
 445
 446 The password is *demo123456!*
 447
 448 Go to the `Portal component user guide
 449 <http://onap.readthedocs.io/en/latest/submodules/portal.git/docs/index.html>`_
 450
 451 Other UI documentation:
 452  - `CLAMP  <http://onap.readthedocs.io/en/latest/submodules/clamp.git/docs/index.html>`_
 453  - `SDC <http://onap.readthedocs.io/en/latest/submodules/sdc.git/docs/index.html>`_
 454  - `UI Use-Case <http://onap.readthedocs.io/en/latest/submodules/usecase-ui.git/docs/index.html>`_
 455
 456
 457 **Components**
 458 ==============
 459
 460 The list of various services and ports used can be found on the
 461 `ONAP wiki - services <https://wiki.onap.org/display/DW/ONAP+Services+List#ONAPServicesList-ONAPServices>`_
 462
 463 .. This work is licensed under a Creative Commons Attribution 4.0
 464 .. International License.
 465 ..  http://creativecommons.org/licenses/by/4.0
 466 .. Copyright 2017-2018 ONAP
 467
 468
 469 .. contents::