Intended audience

This page is aimed at developers who wish to publish an upgrade package for a new release of a Sentinel product.

Creating the bundle

Creating a minor upgrade bundle requires:

  • the product SDK

  • the orca-bundler tool

The orca-bundler will:

  • put the product SDK in offline mode with an offline repository

  • zip the product SDK

  • combine the orca tools with the product SDK to create the minor upgrade bundle

To create the minor upgrade bundle:

  • get the latest version of orca-bundler.zip from operational-tools

  • decompress it

  • run generate-orca-bundle minor-upgrade to bundle the offline SDK with orca

$ unzip orca-bundler.zip
$ ./generate-orca-bundle minor-upgrade --release-sdk product sdk>.zip --out <the upgrade bundle>.zip

The upgrade package will contain:

Item Description

README

Contains information about the minor upgrade: how to use it, what components it changes, and what problems it fixes

orca

The orca tool

helpers directory

Contains set of scripts used by orca

core directory

Contains set of scripts used by orca

workflows directory

Contains set of scripts used by orca

resources directory

Contains the properties used by orca

licenses directory

License information for third party libraries used by the patch runner

packages directory

Contains package files and the package.cfg

The package files directory contains:

  • the packages.cfg file

  • the SDK in offline mode

  • a rhino install (optional)

  • a rhino config JSON file (optional)

  • a license (optional)

  • a new JDK (java) (optional)

  • the post install package or custom package (optional)

  • the post configure package (optional)

The orca-bundler will create the zip file specified in <the upgrade bundle>.zip with the offline product SDK, the orca tool, the optional packages and a README file explaining how to install the minor upgrade. It is important to review this file and add or change any information before handing the upgrade to the customer.

Adding a new Rhino package to the upgrade bundle

To also update Rhino during a minor update, include a Rhino install tar in the bundle. To update any of the configuration properties of the new Rhino cluster, include a Rhino config json file in the bundle.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle minor-upgrade --release-sdk <product sdk>.zip\
                                       --out <the upgrade bundle>.zip\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>

The Rhino package

The Rhino package is the tar file used to distribute Rhino. It contains the Rhino binaries, tools and the installation script.

rhino-install.tar

The Rhino config json file

This file contains configuration that will be applied to Rhino during its installation. The file is formatted as JSON and it includes the Rhino config file destination, the properties and values. Rhino has several configuration attributes in several files with different formats. Currently orca applies the changes to the config_variables and rhino-config.xml file.

The json file format is:

[
  {
     "filename": "file name with path relative to Rhino node installation",
     "filetype:" "properties",
     "settings:" [{settings 1},{settings 2},...,{settings n}]
  },

  {
     "filename": "file name with path relative to Rhino node installation",
     "filetype:" "xml",
     "settings:" [{settings 1},{settings 2},...,{settings n}]
  },
  ....
  {
     "filename": "file name with path relative to Rhino node installation",
     "filetype:" "sh",
     "settings:" [{settings 1},{settings 2},...,{settings n}]
  }
]
Note The filename path is relative to the Rhino node installation. e.g for rhino-config.xml it should be config/rhino-config.xml

The filetype attribute accepts the following values:

  • properties to deal with Rhino key=value config properties)

  • xml to deal with rhino xml config files, e.g rhino-config.xml

  • sh to deal with read-config-variables file

The parameters in the settings attribute should match the expected format defined by the filetype:

  • a property if filetype is properties or sh

  • an XPath if filetype is xml

Example from sentinel-volte-upgrade-rhino-config.json

[
  {
    "filename": "config/config_variables",
    "filetype": "properties",
    "settings": [
      {
        "name": "HEAP_SIZE",
        "type": "minimum",
        "units": "m",
        "value": 6144
      }
    ]
  },

  {
    "filename": "config/rhino-config.xml",
    "filetype": "xml",
    "settings": [
      {
        "xpath": ".//memdb[jndi-name='ManagementDatabase']/committed-size",
        "type": "minimum",
        "units": "M",
        "value": 400
      }
    ]
  }
]
Note Currently the only supported values for type are value and minimum.

For the example above, orca will change the value of the HEAP_SIZE property to 6144m if the current value is lower than that. It will also change the committed-size for element memdb with jndi-name equals to 'ManagementDatabase'.

Concretely it will change

 <memdb>
       <jndi-name>ManagementDatabase</jndi-name>
       <committed-size>128M</committed-size>
 </memdb>

to

 <memdb>
       <jndi-name>ManagementDatabase</jndi-name>
       <committed-size>400M</committed-size>
 </memdb>
Note Use the flag --skip-rhino-version-check in the bundler while creating test upgrade bundles against non released versions of Rhino.

Adding a new License to the upgrade bundle

A new license can be installed during a minor update by including it in the bundle.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle minor-upgrade --release-sdk <product sdk>.zip\
                                       --out <the upgrade bundle>.zip\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>\
                                       --license <license file>

Adding a new JDK to the upgrade bundle

To also update the JDK (Java) used to run rhino, include a new JDK package in the bundle.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle minor-upgrade --release-sdk <product sdk>.zip\
                                       --out <the upgrade bundle>.zip\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>\
                                       --license <new-license.license>\
                                       --java-package <jdk-package>

Adding custom packages to the upgrade bundle

In case the minor upgrade requires a custom package, the best solution is to include it with the upgrade bundle. Use the options --post-install-package and/or --post-configure-package to add a custom module and a post configuration module, respectively.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle minor-upgrade --release-sdk <product sdk>.zip\
                                       --out <the upgrade bundle>.zip\
                                       --post-install-package <custom package>\
                                       --post-configure-package <configure package>

You can also generate the upgrade package in two stages by taking the SDK offline first and then using it to create the upgrade package.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle prepare-sdk --release-sdk <product sdk>.zip\
                                     --out <the offline SDK>.zip

$ ./generate-orca-bundle minor-upgrade --offline-sdk the offline SDK>.zip\
                                       --out <the upgrade bundle>.zip
                                       --post-install-package <custom package>\
                                       --post-configure-package <configure package>

Post-install and post-configure packages

During the upgrade procedure the custom packages will be installed if they are present in the packages.cfg.

Note
"Post-install" and "post-configuration" customizations

Note that orca will install the post-install package after installing the main product SDK but before applying any configuration. The post-configure package will be installed after the configuration is applied. If different customizations are required at these points then you must create two separate custom packages.

The custom packages must conform to the following specification:

  • be a .zip file

  • contain an executable file named install (no extension) in the root directory of the zip.

orca extracts the packages to ~/install/<package name> on the Rhino node and runs the install script from this directory. It calls the install script with one command-line parameter, which is the full path to the uplevel Rhino installation.

It is recommended that the package developer edits the README in the upgrade bundle to include the extra details on the custom package(s).

You can also manually add the post-install and post-configure packages to the upgrade bundle, but it is not recommended. To do so, add the optional packages major upgrade to the bundle zip file after running the above commands. The optional packages have to be in the packages directory and the packages.cfg needs to have the packages names.

Example of the contents of a packages.cfg:

[packages]
sdk=sentinel-ipsmgw-2.6.0.17-offline-sdk.zip
rhino_package=rhino-install.tar
license=new.license
rhino_config_json=sentinel-volte-upgrade-rhino-config.json
post_install_package=custom-package-2.6.0.17.zip
post_configure_package=after-configuration-package-2.6.0.17.zip

[versions]
sdk=2.6.0.17
rhino=2.5.0.5
Previous page Next page