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 More-over following sw packages has to be installed:
  19
  20 * for the Preparation (Part 1), the Download artifacts for offline installer (Part 2) and the application helm charts preparation and patching (Part 4)
  21     -  git
  22     -  wget
  23
  24 * for the Download artifacts for offline installer (Part 2) only
  25     -  createrepo
  26     -  dpkg-dev
  27     -  python2-pip
  28
  29 * for the Download artifacts for offline installer (Part 2) and the Populate local nexus (Part 3)
  30     -  nodejs
  31     -  jq
  32     -  docker (exact version docker-ce-17.03.2)
  33
  34 * for the Download artifacts for offline installer (Part 2) and for the Application helm charts preparation and patching (Part 4)
  35     -  patch
  36
  37 * for the Populate local nexus (Part 3)
  38     -  twine
  39
  40 Configure repos for downloading all needed rpms for download/packaging tooling:
  41
  42
  43 ::
  44
  45     ############
  46     # RHEL 7.6 #
  47     ############
  48
  49     # Register server
  50     subscription-manager register --username <rhel licence name> --password <password> --auto-attach
  51
  52     # enable epel for npm and jq
  53     rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
  54
  55     # enable rhel-7-server-e4s-optional-rpms in /etc/yum.repos.d/redhat.repo
  56
  57 Alternatively
  58
  59 ::
  60
  61    ##############
  62    # Centos 7.6 #
  63    ##############
  64
  65    # enable epel repo for npm and jq
  66    yum install -y epel-release
  67
  68 Subsequent steps are the same on both platforms:
  69
  70 ::
  71
  72     # install following packages
  73     yum install -y expect nodejs git wget createrepo python2-pip jq patch dpkg-dev
  74
  75     pip install twine
  76
  77     # install docker
  78     curl https://releases.rancher.com/install-docker/17.03.sh | sh
  79
  80 Then it is necessary to clone all installer and build related repositories and prepare the directory structure.
  81
  82 ::
  83
  84     # prepare the onap build directory structure
  85     cd /tmp
  86     git clone https://gerrit.onap.org/r/oom/offline-installer onap-offline
  87     cd onap-offline
  88
  89 Part 2. Download artifacts for offline installer
  90 ------------------------------------------------
  91
  92 .. note:: Skip this step if you have already all necessary resources and continue with Part 3. Populate local nexus
  93
  94 All artifacts should be downloaded by running the download script as follows:
  95
  96 ./build/download_offline_data_by_lists.sh <project>
  97
  98 For example:
  99
 100 ::
 101
 102   # onap_3.0.0 for casablanca                                (sign-off 30/11/2018)
 103   # onap_3.0.1 for casablanca maintenance release            (sign-off 10/12/2018)
 104   # onap_3.0.2 for latest casablanca with fixed certificates (sign-off 25/04/2019)
 105
 106   $ ./build/download_offline_data_by_lists.sh onap_3.0.2
 107
 108 Download is as reliable as network connectivity to internet, it is highly recommended to run it in screen and save log file from this script execution for checking if all artifacts were successfully collected. Each start and end of script call should contain timestamp in console output. Downloading consists of 10 steps, which should be checked at the end one-by-one.
 109
 110 **Verify:** *Please take a look on following comments to respective
 111 parts of download script*
 112
 113 [Step 1/10 Download collected docker images]
 114
 115 => image download step is quite reliable and contain retry logic
 116
 117 E.g
 118
 119 ::
 120
 121     == pkg #143 of 163 ==
 122     rancher/etc-host-updater:v0.0.3
 123     digest:sha256:bc156a5ae480d6d6d536aa454a9cc2a88385988617a388808b271e06dc309ce8
 124     Error response from daemon: Get https://registry-1.docker.io/v2/rancher/etc-host-updater/manifests/v0.0.3: Get
 125     https://auth.docker.io/token?scope=repository%3Arancher%2Fetc-host-updater%3Apull&service=registry.docker.io: net/http: TLS handshake timeout
 126     WARNING [!]: warning Command docker -l error pull rancher/etc-host-updater:v0.0.3 failed.
 127     Attempt: 2/5
 128     INFO: info waiting 10s for another try...
 129     v0.0.3: Pulling from rancher/etc-host-updater
 130     b3e1c725a85f: Already exists
 131     6a710864a9fc: Already exists
 132     d0ac3b234321: Already exists
 133     87f567b5cf58: Already exists
 134     16914729cfd3: Already exists
 135     83c2da5790af: Pulling fs layer
 136     83c2da5790af: Verifying Checksum
 137     83c2da5790af: Download complete
 138     83c2da5790af: Pull complete
 139
 140 [Step 2/10 Build own nginx image]
 141
 142 => there is no hardening in this step, if it fails it needs to be
 143 retriggered. It should end with
 144
 145 ::
 146
 147   Successfully built <id>
 148
 149 [Step 3/10 Save docker images from docker cache to tarfiles]
 150
 151 => quite reliable, retry logic in place
 152
 153 [Step 4/10 move infra related images to infra folder]
 154
 155 => should be safe, precondition is not failing step(3)
 156
 157 [Step 5/10 Download git repos]
 158
 159 => potentially unsafe, no hardening in place. If it not download all git repos. It has to be executed again. Easiest way is probably to comment-out other steps in load script and run it again.
 160
 161 E.g.
 162
 163 ::
 164
 165     Cloning into bare repository
 166     'github.com/rancher/community-catalog.git'...
 167     error: RPC failed; result=28, HTTP code = 0
 168     fatal: The remote end hung up unexpectedly
 169     Cloning into bare repository 'git.rancher.io/rancher-catalog.git'...
 170     Cloning into bare repository
 171     'gerrit.onap.org/r/testsuite/properties.git'...
 172     Cloning into bare repository 'gerrit.onap.org/r/portal.git'...
 173     Cloning into bare repository 'gerrit.onap.org/r/aaf/authz.git'...
 174     Cloning into bare repository 'gerrit.onap.org/r/demo.git'...
 175     Cloning into bare repository
 176     'gerrit.onap.org/r/dmaap/messagerouter/messageservice.git'...
 177     Cloning into bare repository 'gerrit.onap.org/r/so/docker-config.git'...
 178
 179 [Step 6/10 Download http files]
 180
 181 [Step 7/10 Download npm pkgs]
 182
 183 [Step 8/10 Download bin tools]
 184
 185 => work quite reliably, If it not download all artifacts. Easiest way is probably to comment-out other steps in load script and run it again.
 186
 187 [Step 9/10 Download rhel pkgs]
 188
 189 => this is the step which will work on rhel only, for other platform different packages has to be downloaded.
 190
 191 Following is considered as sucessfull run of this part:
 192
 193 ::
 194
 195       Available: 1:net-snmp-devel-5.7.2-32.el7.i686 (rhel-7-server-rpms)
 196         net-snmp-devel = 1:5.7.2-32.el7
 197       Available: 1:net-snmp-devel-5.7.2-33.el7_5.2.i686 (rhel-7-server-rpms)
 198         net-snmp-devel = 1:5.7.2-33.el7_5.2
 199     Dependency resolution failed, some packages will not be downloaded.
 200     No Presto metadata available for rhel-7-server-rpms
 201     https://ftp.icm.edu.pl/pub/Linux/fedora/linux/epel/7/x86_64/Packages/p/perl-CDB_File-0.98-9.el7.x86_64.rpm:
 202     [Errno 12\] Timeout on
 203     https://ftp.icm.edu.pl/pub/Linux/fedora/linux/epel/7/x86_64/Packages/p/perl-CDB_File-0.98-9.el7.x86_64.rpm:
 204     (28, 'Operation timed out after 30001 milliseconds with 0 out of 0 bytes
 205     received')
 206     Trying other mirror.
 207     Spawning worker 0 with 230 pkgs
 208     Spawning worker 1 with 230 pkgs
 209     Spawning worker 2 with 230 pkgs
 210     Spawning worker 3 with 230 pkgs
 211     Spawning worker 4 with 229 pkgs
 212     Spawning worker 5 with 229 pkgs
 213     Spawning worker 6 with 229 pkgs
 214     Spawning worker 7 with 229 pkgs
 215     Workers Finished
 216     Saving Primary metadata
 217     Saving file lists metadata
 218     Saving other metadata
 219     Generating sqlite DBs
 220     Sqlite DBs complete
 221
 222 [Step 10/10 Download sdnc-ansible-server packages]
 223
 224 => there is again no retry logic in this part, it is collecting packages for sdnc-ansible-server in the exactly same way how that container is doing it, however there is a bug in upstream that image in place will not work with those packages as old ones are not available and newer are not compatible with other stuff inside that image
 225
 226 Part 3. Populate local nexus
 227 ----------------------------
 228
 229 Prerequisites:
 230
 231 - All data lists and resources which are pushed to local nexus repository are available
 232 - Following ports are not occupied buy another service: 80, 8081, 8082, 10001
 233 - There's no docker container called "nexus"
 234
 235 .. note:: In case you skipped the Part 2 for the artifacts download, please ensure that the copy of resources data are untarred in *./onap-offline/../resources/*
 236
 237 Whole nexus blob data will be created by running script build\_nexus\_blob.sh.
 238 It will load the listed docker images, run the Nexus, configure it as npm, pypi
 239 and docker repositories. Then it will push all listed npm and pypi packages and
 240 docker images to the repositories. After all is done the repository container
 241 is stopped.
 242
 243 You can run the script as following example:
 244
 245 ``$ ./install/onap-offline/build_nexus_blob.sh onap_3.0.2``
 246
 247 Where the onap_3.0.2 is the tag to specify which lists will be used for the
 248 resources
 249
 250 Once the Nexus data blob is created, the docker images and npm and pypi
 251 packages can be deleted to reduce the package size as they won't be needed in
 252 the installation time:
 253
 254 E.g.
 255
 256 ::
 257
 258     rm -f /tmp/onap-offline/resources/offline_data/docker_images_for_nexus/*
 259     rm -rf /tmp/onap-offline/resources/offline_data/npm_tar
 260     rm -rf /tmp/onap-offline/resources/offline_data/pypi
 261
 262 Part 4. Application helm charts preparation and patching
 263 --------------------------------------------------------
 264
 265 This is about to clone oom repository and patch it to be able to use it
 266 offline. Use the following command:
 267
 268 ::
 269
 270   ./build/fetch\_and\_patch\_charts.sh <helm charts repo> <commit/tag/branch> <patchfile> <target\_dir>
 271
 272 For example:
 273
 274 ::
 275
 276   ./build/fetch_and_patch_charts.sh https://gerrit.onap.org/r/oom 3.0.2-ONAP /tmp/onap-offline/patches/casablanca.patch /tmp/oom-clone
 277
 278 Part 5. Creating offline installation package
 279 ---------------------------------------------
 280
 281 For the packagin itself it's necessary to prepare configuration. You can
 282 use ./build/package.conf as template or
 283 directly modify it.
 284
 285 There are some parameters needs to be set in configuration file.
 286 Example values below are setup according to steps done in this guide to package ONAP.
 287
 288 +---------------------------------------+------------------------------------------------------------------------------+
 289 | Parameter                             | Description                                                                  |
 290 +=======================================+==============================================================================+
 291 | HELM\_CHARTS\_DIR                     | directory with Helm charts for the application                               |
 292 |                                       |                                                                              |
 293 |                                       | Example: /tmp/oom-clone/kubernetes                                           |
 294 +---------------------------------------+------------------------------------------------------------------------------+
 295 | APP\_CONFIGURATION                    | application install configuration (application_configuration.yml) for        |
 296 |                                       | ansible installer and custom ansible role code directories if any.           |
 297 |                                       |                                                                              |
 298 |                                       | Example::                                                                    |
 299 |                                       |                                                                              |
 300 |                                       |  APP_CONFIGURATION=(                                                         |
 301 |                                       |     /tmp/onap-offline/config/application_configuration.yml              |
 302 |                                       |     /tmp/onap-offline/patches/onap-casablanca-patch-role                |
 303 |                                       |  )                                                                           |
 304 |                                       |                                                                              |
 305 +---------------------------------------+------------------------------------------------------------------------------+
 306 | APP\_BINARY\_RESOURCES\_DIR           | directory with all (binary) resources for offline infra and application      |
 307 |                                       |                                                                              |
 308 |                                       | Example: /tmp/onap-offline/resources                                         |
 309 +---------------------------------------+------------------------------------------------------------------------------+
 310 | APP\_AUX\_BINARIES                    | additional binaries such as docker images loaded during runtime   [optional] |
 311 +---------------------------------------+------------------------------------------------------------------------------+
 312
 313 Offline installer packages are created with prepopulated data via
 314 following command run from onap-offline directory
 315
 316 ::
 317
 318   ./build/package.sh <project> <version> <packaging target directory>
 319
 320 E.g.
 321
 322 ::
 323
 324   ./build/package.sh onap 3.0.2 /tmp/package
 325
 326
 327 So in the target directory you should find tar files with
 328
 329 ::
 330
 331   offline-<PROJECT\_NAME>-<PROJECT\_VERSION>-sw.tar
 332   offline-<PROJECT\_NAME>-<PROJECT\_VERSION>-resources.tar
 333   offline-<PROJECT\_NAME>-<PROJECT\_VERSION>-aux-resources.tar