docs/BuildGuide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2019 Samsung Electronics Co., Ltd.
   4
   5 OOM ONAP Offline Installer Package Build Guide
   6 =============================================================
   7
   8 This document is describing procedure for building offline installer packages. It is supposed to be triggered on server with internet connectivity and will download all artifacts required for ONAP deployment based on our static lists. The server used for the procedure in this guide is preferred to be separate build server.
   9
  10 Procedure was completely tested on RHEL 7.6 as it’s tested target platform, however with small adaptations it should be applicable also for other platforms.
  11 Some discrepancies when Centos 7.6 is used are described below as well.
  12
  13 Part 1. Preparations
  14 --------------------
  15
  16 We assume that procedure is executed on RHEL 7.6 server with \~300G disc space, 16G+ RAM and internet connectivity
  17
  18 Some additional sw packages are required by ONAP Offline platform building tooling. in order to install them
  19 following repos has to be configured for RHEL 7.6 platform.
  20
  21
  22
  23 .. note::
  24    All commands stated in this guide are meant to be run in root shell.
  25
  26 ::
  27
  28     ############
  29     # RHEL 7.6 #
  30     ############
  31
  32     # Register server
  33     subscription-manager register --username <rhel licence name> --password <password> --auto-attach
  34
  35     # required by special centos docker recommended by ONAP
  36     yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  37
  38     # required by docker dependencies i.e. docker-selinux
  39     subscription-manager repos --enable=rhel-7-server-extras-rpms
  40
  41     # epel is required by npm within blob build
  42     rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
  43
  44 Alternatively
  45
  46 ::
  47
  48    ##############
  49    # Centos 7.6 #
  50    ##############
  51
  52    # required by special centos docker recommended by ONAP
  53    yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  54
  55    # enable epel repo for npm and jq
  56    yum install -y epel-release
  57
  58 Subsequent steps are the same on both platforms:
  59
  60 ::
  61
  62     # install following packages
  63     yum install -y docker-ce-18.09.5 python-pip git createrepo expect nodejs npm jq
  64
  65     # install Python 3 (download scripts don't support Python 2 anymore)
  66     yum install -y python36 python36-pip
  67
  68     # docker daemon must be running on host
  69     service docker start
  70
  71 Then it is necessary to clone all installer and build related repositories and prepare the directory structure.
  72
  73 ::
  74
  75     # prepare the onap build directory structure
  76     cd /tmp
  77     git clone https://gerrit.onap.org/r/oom/offline-installer onap-offline
  78     cd onap-offline
  79
  80     # install required pip packages for build and download scripts
  81     pip3 install -r ./build/requirements.txt
  82     pip3 install -r ./build/download/requirements.txt
  83
  84 Part 2. Download artifacts for offline installer
  85 ------------------------------------------------
  86
  87 .. note::
  88    It is possible to generate actual list of docker images using docker-images-collector.sh (helm is required) from cloned OOM directory
  89    based on enabled subsystems.
  90
  91    In the beginning of the generated list is written commit number from which it was created - the same commit number should be used
  92    in Part 4. Packages preparation.
  93
  94    Following example will create the list to the default path:
  95    ::
  96
  97     # clone the OOM repository
  98     git clone https://gerrit.onap.org/r/oom -b master --recurse-submodules /tmp/oom
  99
 100     # enable subsystems in oom/kubernetes/onap/values.yaml as required
 101
 102     #run the collector providing path the the project
 103     ./build/creating_data/docker-images-collector.sh /tmp/oom/kubernetes/onap
 104
 105    If the list does not contain any image, no subsystem is enabled in the oom/kubernetes/onap/values.yaml
 106
 107    For the other options check the usage of the script.
 108
 109 .. note:: Skip this step if you have already all necessary resources and continue with Part 3. Populate local nexus
 110
 111
 112 There need to be created RPM repository containing packages which need to be installed on all nodes.
 113
 114 ::
 115
 116     # run the docker container with -d parameter for destination directory with RPM packages
 117     ./offline-installer/build/create_repo.sh -d $(pwd)
 118
 119 .. note:: If script fails with permissions, problem could be with SeLinux. Issue is possible to solve by:
 120     ::
 121
 122       # Change security context of directory
 123       chcon -Rt svirt_sandbox_file_t $(pwd)
 124
 125 It's possible to download rest artifacts in single ./download.py execution. Recently we improved reliability of download scripts
 126 so one might try following command to download most of the required artifacts in single shot.
 127
 128 ::
 129
 130         # following arguments are provided
 131         # all data lists are taken from ./build/data_lists/ folder
 132         # all resources will be stored in expected folder structure within ../resources folder
 133
 134         ./build/download/download.py --docker ./build/data_lists/infra_docker_images.list ../resources/offline_data/docker_images_infra \
 135         --http ./build/data_lists/infra_bin_utils.list ../resources/downloads
 136
 137         # following docker images does not neccessary need to be stored under resources as they load into repository in next part
 138         # if second argument for --docker is not present, images are just pulled and cached.
 139         # Warning: script must be run twice separately, for more details run download.py --help
 140         ./build/download/download.py --docker ./build/data_lists/rke_docker_images.list \
 141         --docker ./build/data_lists/k8s_docker_images.list \
 142         --docker ./build/data_lists/onap_docker_images.list \
 143
 144
 145 Alternatively, step-by-step procedure is described in Appendix 1.
 146
 147 This concludes SW download part required for ONAP offline platform creating.
 148
 149 Part 3. Populate local nexus
 150 ----------------------------
 151
 152 Prerequisites:
 153
 154 - All data lists and resources which are pushed to local nexus repository are available
 155 - Following ports are not occupied by another service: 80, 8081, 8082, 10001
 156 - There's no docker container called "nexus"
 157
 158 .. note:: In case you skipped the Part 2 for the artifacts download, please ensure that the onap docker images are cached and copy of resources data are untarred in *./onap-offline/../resources/*
 159
 160 ::
 161
 162         #Whole nexus blob data will be created by running script build_nexus_blob.sh.
 163         ./onap-offline/build/build_nexus_blob.sh
 164
 165 It will load the listed docker images, run the Nexus, configure it as npm, pypi
 166 and docker repositories. Then it will push all listed docker images to the repositories. After all is done the repository container is stopped.
 167
 168 .. note:: In the current release scope we aim to maintain just single example data lists set, tags used in previous releases are not needed. Datalists are also covering latest versions verified by us despite user is allowed to build data lists on his own.
 169
 170
 171 Part 4. Packages preparation
 172 --------------------------------------------------------
 173
 174 ONAP offline deliverable consist of 3 packages:
 175
 176 +---------------------------------------+------------------------------------------------------------------------------+
 177 | Package                               | Description                                                                  |
 178 +=======================================+==============================================================================+
 179 | sw_package.tar                        | Contains installation software and configuration for infrastructure and ONAP |
 180 +---------------------------------------+------------------------------------------------------------------------------+
 181 | resources_package.tar                 | Contains all input files  needed to deploy infrastructure and ONAP           |
 182 +---------------------------------------+------------------------------------------------------------------------------+
 183 | aux_package.tar                       | Contains auxiliary input files that can be added to ONAP                     |
 184 +---------------------------------------+------------------------------------------------------------------------------+
 185
 186 All packages can be created using script build/package.py. Beside of archiving files gathered in the previous steps, script also builds docker images used in on infra server.
 187
 188 From onap-offline directory run:
 189
 190 ::
 191
 192   ./build/package.py <helm charts repo> --build-version <version> --application-repository_reference <commit/tag/branch> --output-dir <target\_dir> --resources-directory <target\_dir>
 193
 194 For example:
 195
 196 ::
 197
 198   ./build/package.py https://gerrit.onap.org/r/oom --application-repository_reference master --output-dir /tmp/packages --resources-directory /tmp/resources
 199
 200
 201 In the target directory you should find tar files:
 202
 203 ::
 204
 205   sw_package.tar
 206   resources_package.tar
 207   aux_package.tar
 208