diff options
| -rw-r--r-- | docs/heat.rst | 236 | ||||
| -rw-r--r-- | docs/index.rst | 11 |
2 files changed, 243 insertions, 4 deletions
diff --git a/docs/heat.rst b/docs/heat.rst new file mode 100644 index 000000000..b1dd1fef0 --- /dev/null +++ b/docs/heat.rst @@ -0,0 +1,236 @@ +ONAP HEAT Template +------------------ + +Source files +~~~~~~~~~~~~ + +- Template file: https://git.onap.org/demo/plain/heat/ONAP/onap_openstack.yaml +- Environment file: https://git.onap.org/demo/plain/heat/ONAP/onap_openstack.env + +Description +~~~~~~~~~~~ + +The ONAP HEAT template spins up the entire ONAP platform. The template, +onap\_openstack.yaml, comes with an environment file, +onap\_openstack.env, in which all the default values are defined. + +.. note:: + onap\_openstack.yaml AND onap\_openstack.env ARE THE HEAT TEMPLATE + AND ENVIRONMENT FILE CURRENTLY SUPPORTED. + onap\_openstack\_float.yaml/env AND onap\_openstack\_nofloat.yaml/env + AREN'T UPDATED AND THEIR USAGE IS NOT SUGGESTED. + +The HEAT template is composed of two sections: (i) parameters, and (ii) +resources. +The parameter section contains the declaration and +description of the parameters that will be used to spin up ONAP, such as +public network identifier, URLs of code and artifacts repositories, etc. +The default values of these parameters can be found in the environment +file. + +The resource section contains the definition of: + +- ONAP Private Management Network, which ONAP components use to communicate with each other and with VNFs +- ONAP Virtual Machines (VMs) +- Public/private key pair used to access ONAP VMs +- Virtual interfaces towards the ONAP Private Management Network +- Disk volumes. + +Each VM specification includes Operating System image name, VM size +(i.e. flavor), VM name, etc. Each VM has two virtual network interfaces: +one towards the public network and one towards the ONAP Private +Management network, as described above. Furthermore, each VM runs a +post-instantiation script that downloads and installs software +dependencies (e.g. Java JDK, gcc, make, Python, ...) and ONAP software +packages and docker containers from remote repositories. + +When the HEAT template is executed, the Openstack HEAT engine creates +the resources defined in the HEAT template, based on the parameters +values defined in the environment file. + +Environment file +~~~~~~~~~~~~~~~~ + +Before running HEAT, it is necessary to customize the environment file. +Indeed, some parameters, namely public\_net\_id, pub\_key, +openstack\_tenant\_id, openstack\_username, and openstack\_api\_key, +need to be set depending on the user's environment: + +**Global parameters** + +:: + + public_net_id: PUT YOUR NETWORK ID/NAME HERE + pub_key: PUT YOUR PUBLIC KEY HERE + openstack_tenant_id: PUT YOUR OPENSTACK PROJECT ID HERE + openstack_username: PUT YOUR OPENSTACK USERNAME HERE + openstack_api_key: PUT YOUR OPENSTACK PASSWORD HERE + horizon_url: PUT THE HORIZON URL HERE + keystone_url: PUT THE KEYSTONE URL HERE (do not include version number) + +openstack\_region parameter is set to RegionOne (OpenStack default). If +your OpenStack is using another Region, please modify this parameter. + +public\_net\_id is the unique identifier (UUID) or name of the public +network of the cloud provider. To get the public\_net\_id, use the +following OpenStack CLI command (ext is the name of the external +network, change it with the name of the external network of your +installation) + +:: + + openstack network list | grep ext | awk '{print $2}' + +pub\_key is string value of the public key that will be installed in +each ONAP VM. To create a public/private key pair in Linux, please +execute the following instruction: + +:: + + user@ubuntu:~$ ssh-keygen -t rsa + +The following operations to create the public/private key pair occur: + +:: + + Generating public/private rsa key pair. + Enter file in which to save the key (/home/user/.ssh/id_rsa): + Created directory '/home/user/.ssh'. + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /home/user/.ssh/id_rsa. + Your public key has been saved in /home/user/.ssh/id_rsa.pub. + +openstack\_username, openstack\_tenant\_id (password), and +openstack\_api\_key are user's credentials to access the +OpenStack-based cloud. + +**Images and flavors parameters** + +:: + + ubuntu\_1404\_image: PUT THE UBUNTU 14.04 IMAGE NAME HERE + ubuntu\_1604\_image: PUT THE UBUNTU 16.04 IMAGE NAME HERE + flavor\_small: PUT THE SMALL FLAVOR NAME HERE + flavor\_medium: PUT THE MEDIUM FLAVOR NAME HERE + flavor\_large: PUT THE LARGE FLAVOR NAME HERE + flavor\_xlarge: PUT THE XLARGE FLAVOR NAME HERE + flavor\_xxlarge: PUT THE XXLARGE FLAVOR NAME HERE + +To get the images in your OpenStack environment, use the following +OpenStack CLI command: + +:: + + openstack image list | grep 'ubuntu' + +To get the flavor names used in your OpenStack environment, use the +following OpenStack CLI command: + +:: + + openstack flavor list + +**DNS parameters** + +:: + + dns\_list: PUT THE ADDRESS OFTHE EXTERNAL DNS HERE (e.g. a comma-separated list of IP addresses in your /etc/resolv.conf in UNIX-based Operating Systems). THIS LIST MUST INCLUDE THE DNS SERVER THAT OFFERS DNS AS AS SERVICE (see DCAE section below for more details) + external\_dns: PUT THE FIRST ADDRESS OF THE EXTERNAL DNS LIST HERE oam\_network\_cidr: 10.0.0.0/16 + +You can use the Google Public DNS 8.8.8.8 and 4.4.4.4 address or your internal DNS servers + +**DCAE Parameters** + +DCAE spins up ONAP's data collection and analytics system in two phases. +The first is the launching of a bootstrap VM that is specified in the +ONAP Heat template. This VM requires a number of deployment specific +conifiguration parameters being provided so that it can subsequently +bring up the DCAE system. There are two groups of parameters. + +The first group relates to the launching of DCAE VMs, including parameters such as +the keystone URL and additional VM image IDs/names. DCAE VMs are +connected to the same internal network as the rest of ONAP VMs, but +dynamically spun up by the DCAE core platform. Hence these parameters +need to be provided to DCAE. Note that although DCAE VMs will be +launched in the same tenant as the rest of ONAP, because DCAE may use +MultiCloud node as the agent for interfacing with the underying cloud, +it needs a separate keystone URL (which points to MultiCloud node +instead of the underlying cloud). + +The second group of configuration parameters relate to DNS As A Service support (DNSaaS). +DCAE requires DNSaaS for registering its VMs into organization-wide DNS service. For +OpenStack, DNSaaS is provided by Designate. Designate support can be +provided via an integrated service endpoint listed under the service +catalog of the OpenStack installation; or proxyed by the ONAP MultiCloud +service. For the latter case, a number of parameters are needed to +configure MultiCloud to use the correct Designate service. These +parameters are described below: + +:: + + dcae_keystone_url: PUT THE KEYSTONE URL OF THE OPENSTACK INSTANCE WHERE DCAE IS DEPLOYED (Note: put the MultiCloud proxy URL if the DNSaaS is proxyed by MultiCloud) + dcae_centos_7_image: PUT THE CENTOS7 IMAGE ID/NAME AVAILABLE AT THE OPENSTACK INSTANCE WHERE DCAE IS DEPLOYED + dcae_security_group: PUT THE SECURITY GROUP ID/NAME TO BE USED AT THE OPENSTACK INSTANCE WHERE DCAE IS DEPLOYED + dcae_key_name: PUT THE ACCESS KEY-PAIR NAME REGISTER AT THE OPENSTACK INSTANCE WHERE DCAE IS DEPLOYED + dcae_public_key: PUT THE PUBLIC KEY OF A KEY-PAIR USED FOR DCAE BOOTSTRAP NODE TO COMMUNICATE WITH DCAE VMS + dcae_private_key: PUT THE PRIVATE KEY OF A KEY-PAIR USED FOR DCAE BOOTSTRAP NODE TO COMMUNICATE WITH DCAE VMS + + dnsaas_config_enabled: true or false FOR WHETHER DNSAAS IS PROXYED + dnsaas_region: PUT THE REGION OF THE OPENSTACK INSTANCE WHERE DNSAAS IS PROVIDED + dnsaas_tenant_id: PUT THE TENANT ID/NAME OF THE OPENSTACK INSTANCE WHERE DNSAAS IS PROVIDED + dnsaas_keystone_url: PUT THE KEYSTONE URL OF THE OPENSTACK INSTANCE WHERE DNSAAS IS PROVIDED + dnsaas_username: PUT THE USERNAME OF THE OPENSTACK INSTANCE WHERE DNSAAS IS PROVIDED + dnsaas_password: PUT THE PASSWORD OF THE OPENSTACK INSTANCE WHERE DNSAAS IS PROVIDED + +Instantiation +~~~~~~~~~~~~~ + +The ONAP platform can be instantiated via Horizon (OpenStack dashboard) +or Command Line. + +**Instantiation via Horizon:** + +- Login to Horizon URL with your personal credentials +- Click "Stacks" from the "Orchestration" menu +- Click "Launch Stack" +- Paste or manually upload the HEAT template file (onap\_openstack.yaml) in the "Template Source" form +- Paste or manually upload the HEAT environment file (onap\_openstack.env) in the "Environment Source" form +- Click "Next" - Specify a name in the "Stack Name" form +- Provide the password in the "Password" form +- Click "Launch" + +**Instantiation via Command Line:** + +- Install the HEAT client on your machine, e.g. in Ubuntu (ref. http://docs.openstack.org/user-guide/common/cli-install-openstack-command-line-clients.html): + +:: + + apt-get install python-dev python-pip + pip install python-heatclient # Install heat client + pip install python-openstackclient # Install the Openstack client to support multiple services + +- Create a file (named i.e. ~/openstack/openrc) that sets all the + environmental variables required to access Rackspace: + +:: + + export OS_AUTH_URL=INSERT THE AUTH URL HERE + export OS_USERNAME=INSERT YOUR USERNAME HERE + export OS_TENANT_ID=INSERT YOUR TENANT ID HERE + export OS_REGION_NAME=INSERT THE REGION HERE + export OS_PASSWORD=INSERT YOUR PASSWORD HERE + +- Run the script from command line: + +:: + + source ~/openstack/openrc + +- In order to install the ONAP platform, type: + +:: + + heat stack-create STACK_NAME -f PATH_TO_HEAT_TEMPLATE(YAML FILE) -e PATH_TO_ENV_FILE # Old HEAT client, OR + openstack stack create -t PATH_TO_HEAT_TEMPLATE(YAML FILE) -e PATH_TO_ENV_FILE STACK_NAME # New Openstack client + diff --git a/docs/index.rst b/docs/index.rst index 833e1aa96..f018fc6ce 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,11 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -TODO Add files to toctree and delete this header ------------------------------------------------- -.. toctree:: - :maxdepth: 1 +INTEGRATION +=========== +The Integration project provides the followning artifacts: +- Heat template to deploy ONAP instance +- Test suites to check the various ONAP components based on Robot Framework +- Artifacts for the use-case deployments +.. include:: heat.rst |