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     # docker-images-collector.sh script uses oom/kubernetes/onap/resources/overrides/onap-all.yaml file to find what subsystems
 101     are enabled. By default all subsystems are enabled there. Modify the file if want to drop some subsystems.
 102
 103     #run the collector providing path the the project
 104     ./build/creating_data/docker-images-collector.sh /tmp/oom/kubernetes/onap
 105
 106    For the other options check the usage of the script.
 107
 108 .. note:: Skip this step if you have already all necessary resources and continue with Part 3. Populate local nexus
 109
 110
 111 A RPM repository containing packages to be installed on all nodes needs to be created:
 112
 113 ::
 114
 115     # run the docker container with -d parameter for destination directory with RPM packages
 116     ./offline-installer/build/create_repo.sh -d $(pwd)
 117
 118 .. note:: If script fails due to permissions issue, it could be a problem with SeLinux. It can be fixed by running:
 119     ::
 120
 121       # Change security context of directory
 122       chcon -Rt svirt_sandbox_file_t $(pwd)
 123
 124 It's possible to download rest artifacts in single ./download.py execution. Recently we improved reliability of download scripts
 125 so one might try following command to download most of the required artifacts in single shot.
 126
 127 ::
 128
 129         # following arguments are provided
 130         # all data lists are taken from ./build/data_lists/ folder
 131         # all resources will be stored in expected folder structure within ../resources folder
 132
 133         ./build/download/download.py --docker ./build/data_lists/infra_docker_images.list ../resources/offline_data/docker_images_infra \
 134         --http ./build/data_lists/infra_bin_utils.list ../resources/downloads
 135
 136         # following docker images do not necessarily need to be stored under resources as they load into repository in next part
 137         # if second argument for --docker is not present, images are just pulled and cached.
 138         # Warning: script must be run twice separately, for more details run download.py --help
 139         ./build/download/download.py --docker ./build/data_lists/rke_docker_images.list \
 140         --docker ./build/data_lists/k8s_docker_images.list \
 141         --docker ./build/data_lists/onap_docker_images.list \
 142
 143
 144 This concludes SW download part required for ONAP offline platform creating.
 145
 146 Part 3. Populate local nexus
 147 ----------------------------
 148
 149 Prerequisites:
 150
 151 - All data lists and resources which are pushed to local nexus repository are available
 152 - Following ports are not occupied by another service: 80, 8081, 8082, 10001
 153 - There's no docker container called "nexus"
 154
 155 .. 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/*
 156
 157 ::
 158
 159         #Whole nexus blob data will be created by running script build_nexus_blob.sh.
 160         ./onap-offline/build/build_nexus_blob.sh
 161
 162 It will load the listed docker images, run the Nexus, configure it as npm, pypi
 163 and docker repositories. Then it will push all listed docker images to the repositories. After all is done the repository container is stopped.
 164
 165 .. 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.
 166
 167
 168 Part 4. Packages preparation
 169 --------------------------------------------------------
 170
 171 ONAP offline deliverable consist of 3 packages:
 172
 173 +---------------------------------------+------------------------------------------------------------------------------+
 174 | Package                               | Description                                                                  |
 175 +=======================================+==============================================================================+
 176 | sw_package.tar                        | Contains installation software and configuration for infrastructure and ONAP |
 177 +---------------------------------------+------------------------------------------------------------------------------+
 178 | resources_package.tar                 | Contains all input files  needed to deploy infrastructure and ONAP           |
 179 +---------------------------------------+------------------------------------------------------------------------------+
 180 | aux_package.tar                       | Contains auxiliary input files that can be added to ONAP                     |
 181 +---------------------------------------+------------------------------------------------------------------------------+
 182
 183 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.
 184
 185 From onap-offline directory run:
 186
 187 ::
 188
 189   ./build/package.py <helm charts repo> --build-version <version> --application-repository_reference <commit/tag/branch> --output-dir <target\_dir> --resources-directory <target\_dir>
 190
 191 For example:
 192
 193 ::
 194
 195   ./build/package.py https://gerrit.onap.org/r/oom --application-repository_reference master --output-dir /tmp/packages --resources-directory /tmp/resources
 196
 197
 198 In the target directory you should find tar files:
 199
 200 ::
 201
 202   sw_package.tar
 203   resources_package.tar
 204   aux_package.tar
 205