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