index.rst

   1 ..
   2       Copyright (c) 2019 AT&T Intellectual Property. All Rights Reserved.
   3
   4       Licensed under the Apache License, Version 2.0 (the "License");
   5       you may not use this file except in compliance with the License.
   6       You may obtain a copy of the License at
   7
   8           http://www.apache.org/licenses/LICENSE-2.0
   9
  10       Unless required by applicable law or agreed to in writing, software
  11       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  12       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  13       License for the specific language governing permissions and limitations
  14       under the License.
  15
  16 Instructions for installing REC using the Regional Controller and the REC Blueprint
  17 ===================================================================================
  18
  19 1. The Regional Controller should already be running somewhere (hopefully on a machine or
  20    VM dedicated for this purpose). See here_ for instructions on how to start the regional
  21    controller.
  22
  23    .. _here: https://wiki.akraino.org/display/AK/Starting+the+Regional+Controller
  24
  25 2. Clone the *rec* repository using
  26
  27    .. code-block:: bash
  28
  29      git clone https://gerrit.akraino.org/r/rec.git
  30
  31    We will use the following files from this repository:
  32
  33   .. code-block:: bash
  34
  35     ./REC_blueprint.yaml
  36     ./objects.yaml
  37     ./workflows/gencerts.sh
  38     ./workflows/REC_create.py
  39
  40   You will need to provide a web server where some of these files may be fetched by the
  41   Regional Controller.
  42
  43 3. Edit the file *objects.yaml*.
  44
  45    - Update the *nodes* stanza to define the nodes in your cluster, including the Out of
  46      Band IP address for each node, as well as the name of the hardware type.  Currently REC
  47      is defined to run on the three types of hardware listed in the *hardware* stanza.
  48    - If you want to give the edgesite a different name, update the 'edgesites' stanza.
  49
  50 4. Edit the file *REC_blueprint.yaml* to to update the URLs (the two lines that contain
  51    ``www.example.org``) for the create workflow script (*REC_create.py*), and the
  52    *gencerts.sh* script.  These URLs should point to the web server and path where you will
  53    store these files. The rest of the blueprint should be kept unchanged.
  54
  55 5. Create and edit a copy of *user_config.yaml*.  See these instructions_ on how to create
  56    this file.
  57
  58    .. _instructions: https://wiki.akraino.org/display/AK/REC+Installation+Guide#RECInstallationGuide-Aboutuser_config.yaml
  59
  60 6. Copy the two workflows scripts and the *user_config.yaml* file to your web server.
  61    Note: the provided *gencerts.sh* just generates some self-signed certificates for use
  62    by the *remote-installer* Docker container, with some pre-defined defaults; if you want
  63    to provide your own certificates, you will need to modify or replace this script.
  64    Set and export the following variable:
  65
  66    .. code-block:: bash
  67
  68      export USER_CONFIG_URL=<URL of user_config.yaml>
  69
  70 7. Clone the *api-server* repository.  This provides the CLI tools used to interact with the
  71    Regional Controller.  Add the scripts from this repository to your PATH:
  72
  73    .. code-block:: bash
  74
  75      git clone https://gerrit.akraino.org/r/regional_controller/api-server
  76      export PATH=$PATH:$PWD/api-server/scripts
  77
  78 8. Define where the Regional Controller is located, as well as the login/password to use
  79    (the login/password shown here are the built-in values and do not need to be changed
  80    if you have not changed them on the Regional Controller):
  81
  82    .. code-block:: bash
  83
  84      export RC_HOST=<IP or DNS name of Regional Controller>
  85      export USER=admin
  86      export PW=admin123
  87
  88 9. Load the objects defined in *objects.yaml* into the Regional Controller using:
  89
  90    .. code-block:: bash
  91
  92      rc_loaddata -H $RC_HOST -u $USER -p $PW -A objects.yaml
  93
  94 10. Load the blueprint into the Regional Controller using:
  95
  96    .. code-block:: bash
  97
  98      rc_cli -H $RC_HOST -u $USER -p $PW blueprint create REC_blueprint.yaml
  99
 100 11. Get the UUIDs of the edgesite and the blueprint from the Regional Controller using:
 101
 102     .. code-block:: bash
 103
 104       rc_cli -H $RC_HOST -u $USER -p $PW blueprint list
 105       rc_cli -H $RC_HOST -u $USER -p $PW edgesite list
 106
 107     These are needed to create the POD.  You will also see the UUID of the Blueprint displayed
 108     when you create the Blueprint in step 10 (it is at the tail end of the URL that is printed).
 109     Set and export them as the environment variables ESID and BPID.
 110
 111     .. code-block:: bash
 112
 113       export ESID=<UUID of edgesite in the RC>
 114       export BPID=<UUID of blueprint in the RC>
 115
 116 12. Figure out which REC ISO images you want to use to build your cluster.  These are
 117     located here:
 118     https://nexus.akraino.org/content/repositories/images-snapshots/TA/release-1/images/
 119     Figure out which build you want, and then set and export the following variables:
 120
 121     .. code-block:: bash
 122
 123           export BUILD=<buildnumber>
 124           export ISO_PRIMARY_URL=https://nexus.akraino.org/content/repositories/images-snapshots/TA/release-1/images/$BUILD/install.iso
 125           export ISO_SECONDARY_URL=https://nexus.akraino.org/content/repositories/images-snapshots/TA/release-1/images/$BUILD/bootcd.iso
 126
 127     Note: the Akraino Release 1 image is build #9.
 128
 129 13. Create the *POD.yaml* file as follows:
 130
 131     .. code-block:: bash
 132
 133           cat > POD.yaml <<EOF
 134           name: My_Radio_Edge_Cloud_POD
 135           description: Put a description of the POD here.
 136           blueprint: $BPID
 137           edgesite: $ESID
 138           yaml:
 139             iso_primary: '$ISO_PRIMARY_URL'
 140             iso_secondary: '$ISO_SECONDARY_URL'
 141             input_yaml: '$USER_CONFIG_URL'
 142             rc_host: $RC_HOST
 143           EOF
 144
 145 14. Create the POD using:
 146
 147     .. code-block:: bash
 148
 149           rc_cli -H $RC_HOST -u $USER -p $PW pod create POD.yaml
 150
 151     This will cause the POD to be created, and the *REC_create.py* workflow script to be
 152     run on the Regional Controller's workflow engine. This in turn will pull in the ISO
 153     images, and install REC on your cluster.
 154
 155 15. If you want to monitor ongoing progess of the installation, you can issue periodic calls
 156     to monitor the POD with:
 157
 158     .. code-block:: bash
 159
 160           rc_cli -H $RC_HOST -u $USER -p $PW pod show $PODID
 161
 162     where $PODID is the UUID of the POD. This will show all the messages logged by the
 163     workflow, as well as the current status of the workflow. The status will be WORKFLOW
 164     while the workflow is running, and wil change to ACTIVE if the workflow completes
 165     succesfully, or FAILED, if the workflow fails.