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        small    Ubuntu 14.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  - private SSH key and public key SSH key for the DCAE VM
 122  - Ubuntu 14.04 image (https://cloud-images.ubuntu.com/releases/14.04/14.04/)
 123  - Ubuntu 16.04 image (https://cloud-images.ubuntu.com/releases/16.04/release/)
 124  - Set of flavors: small, medium, large, xlarge
 125
 126 .. Note: The floating IP may be private IP.
 127
 128 .. Note: Basic flavors can reuse the default flavors as defined by
 129    OpenStack
 130    <https://docs.openstack.org/horizon/latest/admin/manage-flavors.html>`_
 131
 132 Security
 133 --------
 134 The default installation assumes that the Default security group is configured
 135 to enable full access between the ONAP components.
 136 Depending on your environment, we may need to open some security groups
 137 (eg when using the portal from your desktop).
 138
 139 The list of various services and ports used can be found on the
 140 `ONAP wiki - ports <https://wiki.onap.org/display/DW/ONAP+Services+List#ONAPServicesList-ONAPServices>`_.
 141
 142 **Deployment**
 143 ==============
 144
 145 Source files
 146 ------------
 147
 148 Both following files must be downloaded and configured to match your
 149 configuration:
 150
 151 - Template file:
 152   https://git.onap.org/demo/plain/heat/ONAP/onap_openstack.yaml
 153 - Environment file:
 154   https://git.onap.org/demo/plain/heat/ONAP/onap_openstack.env
 155
 156 The environment file must be customized as described in the following sections.
 157
 158 .. Note Beijing release files
 159
 160 Description
 161 -----------
 162
 163 The ONAP Heat template spins up all the components including the DCAE.
 164 The template, onap_openstack.yaml, comes with an environment file,
 165 onap_openstack.env, in which all the default values are defined.
 166
 167 The Heat template is composed of two sections: (i) parameters, and (ii)
 168 resources.
 169 The parameter section contains the declaration and
 170 description of the parameters that will be used to spin up ONAP, such as
 171 public network identifier, URLs of code and artifacts repositories, etc.
 172 The default values of these parameters can be found in the environment
 173 file.
 174
 175 The resource section contains the definition of:
 176
 177 - ONAP Private Management Network, which ONAP components use to communicate
 178   with each other and with VNFs
 179 - ONAP Virtual Machines (VMs)
 180 - Public/private key pair used to access ONAP VMs
 181 - Virtual interfaces towards the ONAP Private Management Network
 182 - Disk volumes
 183
 184 Each VM specification includes Operating System image name, VM size
 185 (i.e. flavor), VM name, etc. Each VM has two virtual network interfaces:
 186 one towards the public network and one towards the ONAP Private
 187 Management network, as described above. Furthermore, each VM runs a
 188 post-instantiation script that downloads and installs software
 189 dependencies (e.g. Java JDK, gcc, make, Python, ...) and ONAP software
 190 packages and Docker containers from remote repositories.
 191
 192 When the Heat template is executed, the OpenStack Heat engine creates
 193 the resources defined in the Heat template, based on the parameters
 194 values defined in the environment file.
 195
 196 Environment file
 197 ----------------
 198
 199 Before running Heat, it is necessary to customize the environment file.
 200 Indeed, some parameters, namely public_net_id, pub_key,
 201 openstack_tenant_id, openstack_username, and openstack_api_key,
 202 need to be set depending on the user's environment:
 203
 204 **Global parameters**
 205
 206 ::
 207
 208  public_net_id:       PUT YOUR NETWORK ID/NAME HERE
 209  pub_key:             PUT YOUR PUBLIC KEY HERE
 210  openstack_tenant_id: PUT YOUR OPENSTACK PROJECT ID HERE
 211  openstack_username:  PUT YOUR OPENSTACK USERNAME HERE
 212  openstack_api_key:   PUT YOUR OPENSTACK PASSWORD HERE
 213  horizon_url:         PUT THE HORIZON URL HERE
 214  keystone_url:        PUT THE KEYSTONE URL HERE (do not include version number)
 215
 216 openstack_region parameter is set to RegionOne (OpenStack default). If
 217 your OpenStack is using another Region, please modify this parameter.
 218
 219 public_net_id is the unique identifier (UUID) or name of the public
 220 network of the cloud provider. To get the public_net_id, use the
 221 following OpenStack CLI command (ext is the name of the external
 222 network, change it with the name of the external network of your
 223 installation)
 224
 225 ::
 226
 227  openstack network list  | grep ext |  awk '{print $2}'
 228
 229 pub_key is string value of the public key that will be installed in
 230 each ONAP VM. To create a public/private key pair in Linux, please
 231 execute the following instruction:
 232
 233 ::
 234
 235  user@ubuntu:~$ ssh-keygen -t rsa
 236
 237 The following operations create the public/private key pair:
 238
 239 ::
 240
 241  Generating public/private rsa key pair.
 242  Enter file in which to save the key (/home/user/.ssh/id_rsa):
 243  Created directory '/home/user/.ssh'.
 244  Enter passphrase (empty for no passphrase):
 245  Enter same passphrase again:
 246  Your identification has been saved in /home/user/.ssh/id_rsa.
 247  Your public key has been saved in /home/user/.ssh/id_rsa.pub.
 248
 249 openstack_username, openstack_tenant_id (password), and
 250 openstack_api_key are user's credentials to access the
 251 OpenStack-based cloud.
 252
 253 **Images and flavors parameters**
 254
 255 ::
 256
 257  ubuntu_1404_image:  PUT THE UBUNTU 14.04 IMAGE NAME HERE
 258  ubuntu_1604_image:  PUT THE UBUNTU 16.04 IMAGE NAME HERE
 259  flavor_small:       PUT THE SMALL FLAVOR NAME HERE
 260  flavor_medium:      PUT THE MEDIUM FLAVOR NAME HERE
 261  flavor_large:       PUT THE LARGE FLAVOR NAME HERE
 262  flavor_xlarge:      PUT THE XLARGE FLAVOR NAME HERE
 263
 264 To get the images in your OpenStack environment, use the following
 265 OpenStack CLI command:
 266
 267 ::
 268
 269         openstack image list | grep 'ubuntu'
 270
 271 To get the flavor names used in your OpenStack environment, use the
 272 following OpenStack CLI command:
 273
 274 ::
 275
 276         openstack flavor list
 277
 278 **Network parameters**
 279
 280 ::
 281
 282  dns_list: PUT THE ADDRESS OF THE EXTERNAL DNS HERE (e.g. a comma-separated list
 283  of IP addresses in your /etc/resolv.conf in UNIX-based Operating Systems)
 284  external_dns: PUT THE FIRST ADDRESS OF THE EXTERNAL DNS LIST HERE
 285  dns_forwarder: PUT THE IP OF DNS FORWARDER FOR ONAP DEPLOYMENT'S OWN DNS SERVER
 286  oam_network_cidr: 10.0.0.0/16
 287
 288 You can use the Google Public DNS 8.8.8.8 and 4.4.4.4 address or your internal
 289 DNS servers.
 290
 291 ONAP installs a DNS server used to resolve IP addresses in the ONAP OAM private
 292 network.
 293
 294 **DCAE Parameters**
 295
 296 For Beijing Release, all the DCAE components are deployed in a single
 297 virtual machine.
 298 You must specify R2 to run R2 DCAE components.
 299 Is you are using R1 to get R1 ONAP, you must fill all the other
 300 DCAE parameters.
 301 Please refer to the Amsterdam documentation to fill these parameters.
 302 ::
 303
 304   dcae_deployment_profile: PUT DCAE DEPLOYMENT PROFILE (R1, R2MVP, R2, or R2PLUS)
 305
 306 Instantiation
 307 -------------
 308
 309 The ONAP platform can be instantiated via Horizon (OpenStack dashboard)
 310 or Command Line.
 311
 312 **Instantiation via Horizon:**
 313
 314 - Login to Horizon URL with your personal credentials
 315 - Click "Stacks" from the "Orchestration" menu
 316 - Click "Launch Stack"
 317 - Paste or manually upload the HEAT template file (onap_openstack.yaml) in the
 318   "Template Source" form
 319 - Paste or manually upload the HEAT environment file (onap_openstack.env) in
 320   the "Environment Source" form
 321 - Click "Next" - Specify a name in the "Stack Name" form
 322 - Provide the password in the "Password" form
 323 - Click "Launch"
 324
 325 **Instantiation via Command Line:**
 326
 327 - You need to have the OpenStack Heat service installed:
 328
 329 - Create a file (named i.e. ~/openstack/openrc) that sets all the
 330   environmental variables required to access your OpenStack tenant:
 331
 332 ::
 333
 334  export OS_AUTH_URL=INSERT THE AUTH URL HERE
 335  export OS_USERNAME=INSERT YOUR USERNAME HERE
 336  export OS_TENANT_ID=INSERT YOUR TENANT ID HERE
 337  export OS_REGION_NAME=INSERT THE REGION HERE
 338  export OS_PASSWORD=INSERT YOUR PASSWORD HERE
 339  export OS_USER_DOMAIN_NAME=INSERT YOUR DOMAIN HERE
 340  export OS_PROJECT_NAME=INSERT YOUR PROJECT NAME HERE
 341
 342 -  Run the script from command line:
 343
 344 ::
 345
 346  source ~/openstack/openrc
 347
 348 -  In order to install the ONAP platform, type:
 349
 350 ::
 351
 352  # Old Heat client
 353
 354 ::
 355
 356  heat stack-create STACK_NAME -f PATH_TO_HEAT_TEMPLATE(YAML FILE)
 357  -e PATH_TO_ENV_FILE
 358
 359  OR
 360
 361 ::
 362
 363  # New OpenStack client
 364  openstack stack create -t PATH_TO_HEAT_TEMPLATE(YAML FILE)
 365  -e PATH_TO_ENV_FILE STACK_NAME
 366
 367
 368 .. Note The Heat template deployment may take time (up to one hour)
 369    depending on your hardware environment.
 370
 371 Test the installation
 372 ---------------------
 373 Every ONAP component offers a HealthCheck REST API. The Robot Virtual Machine
 374 (*onap-robot*) can be used to test that every components run smoothly.
 375 Run the following command to perform the HealthCheck:
 376
 377 .. code-block:: bash
 378
 379   docker exec -it openecompete_container /var/opt/OpenECOMP_ETE/runTags.sh
 380   -i health
 381   -d ./html
 382   -V /share/config/integration_robot_properties.py
 383   -V /share/config/integration_preload_parameters.py
 384   -V /share/config/vm_properties.py
 385
 386 This test suite will execute 40 tests towards the various ONAP components.
 387
 388 After the installation, it is possible to deploy the various use-cases
 389 described in `ONAP wiki - demos <https://wiki.onap.org/display/DW/Running+the+ONAP+Demos>`_.
 390
 391 Detect problems
 392 ---------------
 393 If all the tests are not OK, many causes are possible.
 394 Here is a simple procedure to detect where the problem occurs:
 395
 396 * Check the OpenStack Virtual Machine logs
 397 * Connect to the Virtual Machine and check that the various containers are
 398   running.
 399
 400 The list of containers are described on the `ONAP wiki - containers <https://wiki.onap.org/display/DW/ONAP+Services+List#ONAPServicesList-ONAPServices>`_.
 401 In case some containers are missing, check the Docker logs using the following
 402 command:
 403
 404 .. code-block:: bash
 405
 406  sudo docker ps -a
 407  sudo docker logs <containerid>
 408
 409 **Portal configuration**
 410 ========================
 411 The current ONAP installation is using the *onap.org* domain.
 412 To use the portal on your desktop, you must configure the following information
 413 in your *host* file (located in /etc/host for Linux or
 414 /windows/system32/drivers/etc/hosts for Windows):
 415
 416 .. code-block:: bash
 417
 418  <onap-policy_ip>      policy.api.simpledemo.onap.org
 419  <onap-portal_ip>      portal.api.simpledemo.onap.org
 420  <onap-sdc_ip>         sdc.api.simpledemo.onap.org
 421  <onap-vid_ip>         vid.api.simpledemo.onap.org
 422  <onap-aai-inst1_ip>   aai.api.simpledemo.onap.org
 423  <onap-aai-inst2_ip>   aai.ui.simpledemo.onap.org
 424
 425
 426 You can use the Horizon dashboard to get the IP addresses associated with the
 427 Virtual Machines or use the following command line:
 428
 429 .. code-block:: bash
 430
 431  openstack server list
 432
 433 Launch the portal on the
 434 http://portal.api.simpledemo.onap.org:8989/ONAPPORTAL/login.htm
 435
 436 Various users are predefined as presented in the following table:
 437
 438   .. csv-table::
 439    :header: Role, Login
 440    :widths: 20, 20
 441
 442     Superuser,demo
 443     Designer,cs0008
 444     Tester,jm0007
 445     Governor,gv0001
 446     Ops,op0001
 447
 448 The password is *demo123456!*
 449
 450 Go to the `Portal component user guide
 451 <http://onap.readthedocs.io/en/latest/submodules/portal.git/docs/index.html>`_
 452
 453 Other UI documentation:
 454  - `CLAMP  <http://onap.readthedocs.io/en/latest/submodules/clamp.git/docs/index.html>`_
 455  - `SDC <http://onap.readthedocs.io/en/latest/submodules/sdc.git/docs/index.html>`_
 456  - `UI Use-Case <http://onap.readthedocs.io/en/latest/submodules/usecase-ui.git/docs/index.html>`_
 457
 458
 459 **Components**
 460 ==============
 461
 462 The list of various services and ports used can be found on the
 463 `ONAP wiki - services <https://wiki.onap.org/display/DW/ONAP+Services+List#ONAPServicesList-ONAPServices>`_
 464
 465 .. This work is licensed under a Creative Commons Attribution 4.0
 466 .. International License.
 467 ..  http://creativecommons.org/licenses/by/4.0
 468 .. Copyright 2017-2018 ONAP
 469
 470
 471 .. contents::