blob: 2653d63d2ca48ece60555ef28f20cddd3ab840c5 [file] [log] [blame]
Lusheng Ji768421b2018-06-01 16:36:54 -04001.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2.. http://creativecommons.org/licenses/by/4.0
Lusheng Jia73548f2017-11-05 19:24:05 -05003
Lusheng Ji768421b2018-06-01 16:36:54 -04004OpenStack Heat Orchestration Template Based DCAE Deployment
5===========================================================
6
7This document describes the details of the OpenStack Heat Orchestration Template deployment process and how to configure DCAE related parameters in the Heat template and its parameter file.
Lusheng Jia73548f2017-11-05 19:24:05 -05008
9
Lusheng Jic02a89f2017-11-20 11:35:35 -050010ONAP Deployment Overview
11------------------------
Lusheng Jia73548f2017-11-05 19:24:05 -050012
Lusheng Ji768421b2018-06-01 16:36:54 -040013ONAP R2 supports an OpenStack Heat template based system deployment. The Heat Orchestration Template file and its parameter input file can be found under the **heat/ONAP** directory of the **demo** repo.
14
15When a new "stack" is created using the template, the following virtual resources will be launched in the target OpenStack tenant:
Lusheng Jia73548f2017-11-05 19:24:05 -050016
17* A four-character alphanumerical random text string, to be used as the ID of the deployment. It is denoted as {{RAND}} in the remainder of this document.
18* A private OAM network interconnecting all ONAP VMs, named oam_onap_{{RAND}}.
19* A virtual router interconnecting the private OAM network with the external network of the OpenStack installation.
20* A key-pair named onap_key_{{RAND}}.
21* A security group named onap_sg_{{RAND}}.
Lusheng Ji768421b2018-06-01 16:36:54 -040022* A list of VMs for ONAP components. Each VM has one NIC connected to the OAM network and assigned a fixed IP. Each VM is also assigned a floating IP address from the external network. The VM hostnames are name consistently across different ONAP deployments, a user defined prefix, denoted as {{PREFIX}}, followed by a descriptive string for the ONAP component this VM runs, and optionally followed by a sub-function name. In the parameter env file supplied when running the Heat template, the {{PREFIX}} is defined by the **vm_base_name** parameter. The VMs of the same ONAP role across different ONAP deployments will always have the same OAM network IP address. For example, the Message Router will always have the OAM network IP address of 10.0.11.1. The list below provides the IP addresses and hostnames for ONAP components
23that are relevant to DCAE.
Lusheng Jia73548f2017-11-05 19:24:05 -050024
25 ============== ========================== ==========================
26 ONAP Role VM (Neutron) hostname OAM IP address(s)
27 ============== ========================== ==========================
28 A&AI {{PREFIX}}-aai-inst1 10.0.1.1
Lusheng Jia73548f2017-11-05 19:24:05 -050029 SDC {{PREFIX}}-sdc 10.0.3.1
Lusheng Ji768421b2018-06-01 16:36:54 -040030 DCAE {{PREFIX}}-dcae 10.0.4.1
Lusheng Jia73548f2017-11-05 19:24:05 -050031 Policy {{PREFIX}}-policy 10.0.6.1
32 SD&C {{PREFIX}}-sdnc 10.0.7.1
Lusheng Jia73548f2017-11-05 19:24:05 -050033 Robot TF {{PREFIX}}-robot 10.0.10.1
34 Message Router {{PREFIX}}-message-router 10.0.11.1
35 CLAMP {{PREFIX}}-clamp 10.0.12.1
Lusheng Jia73548f2017-11-05 19:24:05 -050036 Private DNS {{PREFIX}}-dns-server 10.0.100.1
37 ============== ========================== ==========================
Lusheng Jic02a89f2017-11-20 11:35:35 -050038* Each of the above VMs will also be associated with a floating IP address from the external network.
Lusheng Jia73548f2017-11-05 19:24:05 -050039
Lusheng Jia73548f2017-11-05 19:24:05 -050040
Lusheng Ji768421b2018-06-01 16:36:54 -040041DCAE Deployment
42---------------
Lusheng Jia73548f2017-11-05 19:24:05 -050043
Lusheng Ji768421b2018-06-01 16:36:54 -040044Within the Heat template yaml file, there is a section which specifies the DCAE VM as a "service". Majority of the service block is the script that the VM will execute after being launched. This is known as the "cloud-init" script. This script writes configuration parameters to VM disk files under the /opt/config directory of the VM file system, one parameter per file, with the file names matching with the parameter names. At the end, the cloud-init script invokes DCAE's installtioan script dcae2-install.sh, and DCAE deployment script dcae2_vm_init.sh. While the dace2_install.sh script installs the necessary software packages, the dcae2_vm_init.sh script actually deploys the DCAE Docker containers to the DCAE VM.
Lusheng Jia73548f2017-11-05 19:24:05 -050045
Lusheng Ji768421b2018-06-01 16:36:54 -040046Firstly, during the execution of the dcae2_vm_init.sh script, files under the **heat** directory of the **dcaegen2/deployments** repo are downloaded and any templates in these files referencing the configuration files under the /opt/config directories are expanded by the contents of the corresponding files. For example, a template of {{ **dcae_ip_addr** }} is replaced with the contents of the file /opt/config/**dcae_ip_addr**.txt file. The resultant files are placed under the /opt/app/config directory of the DCAE VM file system.
Lusheng Jia73548f2017-11-05 19:24:05 -050047
Lusheng Ji768421b2018-06-01 16:36:54 -040048In addition, the dcae2_vm_init.sh script also calls the scripts to register the components with Consul about their health check APIs, and their default configurations.
Lusheng Jia73548f2017-11-05 19:24:05 -050049
Lusheng Ji768421b2018-06-01 16:36:54 -040050Next, the dcae2_vm_init.sh script deploys the resources defined in the docker-compose-1.yaml and docker-compose-2.yaml files, with proper waiting in between to make sure the resource in docker-compose-1.yaml file have entered ready state before deploying the docker-compose-2.ayml file because the formers are the dependencies of the latter. These resources are a number of services components and their minimum supporting platform components (i.e. Consul server and Config Binding Service). With these resources, DCAE is able to provide a minimum configuration that supports the ONAP R2 use cases, namely, the vFW/vDNS, vCPE, cVoLTE use cases. However, lacking the DCAE full platform, this configuration does not support CLAMP and Policy update from Policy Framework. The only way to change the configurations of the service components (e.g. publishing to a different DMaaP topic) can only be accomplished by changing the value on the Consul for the KV of the service component, using Consul GUI or API call.
Lusheng Jic02a89f2017-11-20 11:35:35 -050051
Lusheng Ji768421b2018-06-01 16:36:54 -040052For more complete deployment, the dcae2_vm_init.sh script further deploys docker-compose-3.yaml file, which deploys the rest of the DCAE platform components, and if configured so docker-compose-4.yaml file, which deploys DCAE R2 stretch goal service components such as PRH, Missing Heartbeat, etc.
Lusheng Jic02a89f2017-11-20 11:35:35 -050053
Lusheng Ji768421b2018-06-01 16:36:54 -040054After all DCAE components are deployed, the dcae2_vm_init.sh starts to provide health check results. Due to the complexity of the DCAE system, a proxy is set up for returning a single binary result for DCAE health check instead of having each individual DCAE component report its health status. To accomplish this, the dcae2_vm_init.sh script deploys a Nginx reverse proxy then enters an infinite health check loop.
Lusheng Jic02a89f2017-11-20 11:35:35 -050055
Lusheng Ji768421b2018-06-01 16:36:54 -040056During each iteration of the loop, the script checks Consul's service health status API and compare the received healthy service list with a pre-determined list to assess whether the DACE system is healthy. The list of services that must be healthy for the DCAE system to be assessed as healthy depends on the deployment profile which will be covered in the next subsection. For example, if the deployment profile only calls for a minimum configuration for passing use case data, whether DCAE platform components such as Deployment Handler are heathy does not affect the result.
Lusheng Jic02a89f2017-11-20 11:35:35 -050057
Lusheng Ji768421b2018-06-01 16:36:54 -040058If the DCAE system is considered healthy, the dcae2_vm_init.sh script will generate a file that lists all the healthy components and the Nginx will return this file as the body of a 200 response for any DCAE health check. Otherwise, the Nginx will return a 404 response.
Lusheng Jic02a89f2017-11-20 11:35:35 -050059
Lusheng Jia73548f2017-11-05 19:24:05 -050060
61Heat Template Parameters
Lusheng Jic5e03752017-11-22 00:38:22 -050062------------------------
Lusheng Jia73548f2017-11-05 19:24:05 -050063
Lusheng Ji768421b2018-06-01 16:36:54 -040064In DCAE R2, the configuration for DCAE deployment in Heat is greatly simplified. In addition to paramaters such as docker container image tags, the only parameter that configures DCAE deployment behavior is dcae_deployment_profiles.
Lusheng Jia73548f2017-11-05 19:24:05 -050065
Lusheng Ji768421b2018-06-01 16:36:54 -040066* dcae_deployment_profile: the parameter determines which DCAE components (containers) will be deployed. The following profiles are supported for R2:
67 * R2MVP: This profile includes a minimum set of DACE components that will support the vFW/vDNS, vCPE. and vVoLTE use cases. It will deploy the following components:
68 * Consul server,
69 * Config Binding Service,
70 * Postgres database,
71 * VES collector
72 * TCA analytics
73 * Holmes rule management
74 * Holmes engine management.
75 * R2: This profile also deploys the rest of the DCAE platform. With R2 deployment profile, DCAE supports CLAMP and full control loop functionalities. These additional components are:
76 * Cloudify Manager,
77 * Deployment Handler,
78 * Policy Handler,
79 * Service Change Handler,
80 * Inventory API.
81 * R2PLUS: This profile deploys the DCAE R2 stretch goal service components, namely:
82 * PNF Registration Handler,
83 * SNMP Trap collector,
84 * Missing Heartbeat Detection analytics,
85 * Universal Mapper.
Lusheng Jic02a89f2017-11-20 11:35:35 -050086
87
Lusheng Jia73548f2017-11-05 19:24:05 -050088
Lusheng Jic02a89f2017-11-20 11:35:35 -050089
Lusheng Jic5e03752017-11-22 00:38:22 -050090Tips for Manual Interventions
91-----------------------------
92
93During DCAE deployment, there are several places where manual interventions are possible:
94
95* Running dcae2_install.sh
96* Running dcae2_vm_init.sh
Lusheng Ji768421b2018-06-01 16:36:54 -040097* Individual docker-compose-?.yaml file
Lusheng Jic5e03752017-11-22 00:38:22 -050098
Lusheng Ji768421b2018-06-01 16:36:54 -040099All these require ssh-ing into the dcae VM, then change directory or /opt and sudo.
Lusheng Jic5e03752017-11-22 00:38:22 -0500100Configurations injected from the Heat template and cloud init can be found under /opt/config.
101DCAE run time configuration values can be found under /opt/app/config. After any parameters are changed, the dcae2_vm_init.sh script needs to be rerun.
102
Lusheng Ji768421b2018-06-01 16:36:54 -0400103Redpeloying/updating resources defines in docker-compose-?.yaml files can be achieved by running the following:
104
105 $ cd /opt/app/config
106 $ /opt/docker/docker-compose -f ./docker-compose-4.yaml down
107 $ /opt/docker/docker-compose -f ./docker-compose-4.yaml up -d
108
109
110Some manual interventions may also require interaction with the OpenStack environment. This can be
Lusheng Jic5e03752017-11-22 00:38:22 -0500111done by using the OpenStack CLI tool. OpenStack CLI tool comes very handy for various uses in deployment and maintenance of ONAP/DCAE.
112
113It is usually most convenient to install OpenStack CLI tool in a Python virtual environment. Here are the steps and commands::
114
115 # create and activate the virtual environment, install CLI
116 $ virtualenv openstackcli
117 $ . openstackcli/bin/activate
118 $ pip install --upgrade pip python-openstackclient python-designateclient python-novaclient python-keystoneclient python-heatclient
119
120 # here we need to download the RC file form OpenStack dashboard:
121 # Compute->Access & Security_>API Aceess->Download OpenStack RC file
122
123 # activate the environment variables with values point to the taregt OpenStack tenant
124 (openstackcli) $ . ./openrc.sh
125
126Now we are all set for using OpenStack cli tool to run various commands. For example::
127
128 # list all tenants
129 (openstackcli) $ openstack project list
130
Lusheng Jic5e03752017-11-22 00:38:22 -0500131Finally to deactivate from the virtual environment, run::
132
133 (openstackcli) $ deactivate
134
135