Skip to content

Before you begin

This page covers CLI prerequisites, best practices, and revision numbering conventions to review before performing dynamic upgrades.

Command line interface

Dynamic upgrade operations are controlled through the KX Sensors CLI. These commands may be executed on any node regardless of the node or nodes involved in the upgrade. From the operating system, you can access the commands via:

kxsctl deploy [command]

You can look up further information on the commands by means of the help option.

[root@kxsa /]# kxsctl deploy --help
Perform a dynamic upgrade operation

Usage:
  kxsctl deploy [command]

Aliases:
  deploy, du

Available Commands:
  add         Add a new directory list and deploys it to all nodes or specified targets
  apply       Apply an existing deployment or a new one derived from an existing deployment to all nodes or specified targets
  list        List deployments

Flags:
  -h, --help   help for deploy

Global Flags:
      --endpoints strings   Specify etcd endpoints (default [localhost:20000])
  -q, --quiet                Skip confirmation prompts
  -v, --verbose count        Display progressively more verbose detail (-vv, -vvv)

Use "kxsctl deploy [command] --help" for more information about a command.

Best practices

The following sequence is highly recommended by KX when making code and schema changes:

Test UAT Production
You make your code and schema changes and cut a package in your test environment. You deploy your newly cut package in your UAT environment, either through a dynamic or offline upgrade. If there are no error messages and you are satisfied with the results in UAT, you deploy the new package in your production environment.

About revision numbering

KX Sensors maintains a log of all deployments that have been used in an environment. Each sequential revision number represents an upgrade to the directory list of the system with process, service class and node specifications, which may contain code, configuration, schema, API, etc. changes.

These revision numbers may be viewed by use of the kxsctl deploy list command.

In the example below, the revision number is incremented following each change to the directory list. The revision numbers 1 through 4 can be applied to any process, service class or node specification of interest. The final row in this instance represents a rollback of every process to revision 1.

[root@kxsa /]# kxsctl deploy list
Revision  Nodes  Processes/Service Classes  Directory List
--------  -----  --------------------------  ----------------------------------
1         <all>  <all>                       kxs-core;kxs-utilities;pkg;test-env
2         <all>  <all>                       kxs-core;kxs-utilities;pkg;test-env;base-pkg
3         <all>  RDB                         kxs-core;kxs-utilities;pkg;test-env;base-pkg;pkg1
3         <all>  DBW,MDL,SDL,HDB             kxs-core;kxs-utilities;pkg;test-env;base-pkg;pkg1
4         <all>  DBW,MDL,SDL,HDB             kxs-core;kxs-utilities;pkg;test-env;base-pkg;pkg1;pkg2
4         <all>  RDB                         kxs-core;kxs-utilities;pkg;test-env;base-pkg;pkg1;pkg2
2         <all>  DBW,MDL,SDL,RDB,HDB         kxs-core;kxs-utilities;pkg;test-env;base-pkg
4         <all>  RDB                         kxs-core;kxs-utilities;pkg;test-env;base-pkg;pkg1;pkg2
4         <all>  DBW,MDL,SDL,HDB             kxs-core;kxs-utilities;pkg;test-env;base-pkg;pkg1;pkg2
2         <all>  DBW,MDL,SDL,RDB,HDB         kxs-core;kxs-utilities;pkg;test-env;base-pkg
1         <all>  <all>                       kxs-core;kxs-utilities;pkg;test-env
[root@kxsa /]#

Note

The version number pkg.version contained in the package's .pkg file is completely unrelated to the revision numbers assigned by KX Sensors. Package version numbers are user defined at the package level, while revision numbers are system generated by Sensors at point of deployment.

Set up default values in schema.yaml

If your schema upgrade includes new columns in existing tables with non-null default values, you must define these default values in the corresponding schema.yaml while adding the column. This can be controlled through the init field while defining the new column:

Attribute Description
name Column name.
type Column type.
init Specifies how pre-existing rows are populated when column is added to the table.

The init field itself takes the following attributes, which together specify the default value or function used to populate the new column:

Attribute Description
default Default value to apply during addition of the column.
fn Function (monadic) to apply during addition of the column. It can be in one of the forms: <function-name> or <file-path>:<function-name>, where <file-path> refers to a file which is loaded before the function is invoked. The function is presented with a table containing the columns specified by inputCols.
inputCols Columns to present to function. If no columns are specified, then the function gets an empty dictionary. 
- name: newCol1 # New column
  type: integer
- name: newCol2 # New column with default value
  type: float
  init:
    default: 100
- name: newCol3 # New column initialized using custom function
  type: long
  init:
    fn: src/upgrade/upgrade.q:.upg.newCol3
- name: newCol4 # New column initialized using custom function which takes existing columns as input
  type: long
  init:
    fn: src/upgrade/upgrade.q:.upg.newCol4
    inputCols: [ col1, col2 ]

Next steps