Dynamic upgrades using the KX Sensors CLI¶
This page describes how to perform dynamic upgrades using the KX Sensors CLI, including process roles, deployment history, and the available deploy operations.
This is the recommended method of upgrade when your changes are permanent and need to be deployed in other environments. Most code and schema changes are supported except for complex modification of an existing table column.
Understand process roles¶
Some essential KXS processes have a special role in dynamic upgrades.
| Process | Description | Role within dynamic upgrade |
|---|---|---|
| DBW | The author of the on-disk database. | Performs on-disk database schema conversion. |
| SM | The source of EOX signals. | Helps coordinate the schema update sequence by sequencing a message in RT. |
View the deployment history¶
You can look up your deployment history by means of the kxsctl deploy list command. It shows a history or audit trail of all the upgrade operations performed on your system.
[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 /]#
The deployment list shows the following attributes for each deployment:
| Column | Description |
|---|---|
| Revision | The revision number associated with the directory list. |
| Nodes | The targeted nodes or <all> for all nodes. |
| Processes/Service Classes | The targeted processes/service classes or <all> for all processes/service classes. |
| Directory List | The directory list associated with the deployment. |
Generate a new deployment¶
You can generate a new deployment using a specified directory list and apply it to all nodes, or optionally to specified service classes or processes on all or a subset of nodes, by means of the kxsctl deploy add command.
Note
Any packages referenced in the add command must be located within the package directory on the nodes of interest, which is typically $KXS_ROOT/packages. This may differ depending on environment configuration, and absolute paths may additionally be specified rather than relative paths.
When you create a new deployment, KX Sensors automatically creates a unique revision number associated with the deployment. If you create a deployment by mistake, you cannot delete it through the CLI. Instead, you must roll back to a previous revision number, create your new deployment correctly and work from the updated revision number assigned to the corrected deployment.
[root@kxsa packages]# kxsctl deploy add --help
Generate a new deployment using specified directory list and applies it to all nodes, or optionally
to specified service classes or processes on all or specified nodes.
Where:
directory list: A comma or semicolon separated list of directories which must exist under the
packages directory on the hosts involved in the deployment.
Usage:
kxsctl deploy add directory-list [targets] [flags]
Flags:
-h, --help help for add
-n, --node strings Specify node
-p, --proc strings Specify process name
-s, --sc strings Specify service class
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)
The deploy add command takes the directory list as a mandatory argument, optionally followed by the processes/service classes/nodes of interest. In the example below, a new deployment with the specified directory list is created with revision 2 associated with the deployment.
[root@kxsa packages]# kxsctl du list
Revision Nodes Processes/Service Classes Directory List
-------- ----- -------------------------- ----------------
1 <all> <all> kxs-core;test-env
[root@kxsa packages]#
[root@kxsa packages]# kxsctl deploy add "kxs-core;test-env;test-pkg"
This will generate a new deployment and apply it to all nodes,
using directory list: kxs-core;test-env;test-pkg.
Continue? [yN] y
Process version registry updated, revision=2
[root@kxsa packages]#
[root@kxsa packages]# kxsctl deploy list
Revision Nodes Processes/Service Classes Directory List
-------- ----- -------------------------- --------------------------
1 <all> <all> kxs-core;test-env
2 <all> <all> kxs-core;test-env;test-pkg
[root@kxsa packages]#
Examples:
kxsctl deploy add "kxs-core;test-pkg;env"
kxsctl deploy add "kxs-core;test-pkg;env" A
kxsctl deploy add "kxs-core;test-pkg;env" RDB
kxsctl deploy add "kxs-core;test-pkg;env" B RDB
Append a package to an existing deployment¶
The deploy apply command can be used to append a package to an existing directory list by means of the -a option. It can be used to append to any existing revision number with any subset of processes/service classes/nodes. If the arguments are omitted, the revision number used is the most recent revision in effect and all targets are used.
In the example below, the package new-pkg is appended to the existing revision 2, which generates a new deployment with revision 3 and dynamically propagates the change to all processes.
[root@kxsa packages]# kxsctl deploy apply -a new-pkg
This will generate a new deployment derived from revision 2 and apply it to all nodes,
using directory list: kxs-core;test-env;test-pkg;new-pkg
Continue? [yN] y
Process version registry updated, revision=3
[root@kxsa packages]# kxsctl deploy list
Revision Nodes Processes/Service Classes Directory List
-------- ----- -------------------------- ------------------------------------
1 <all> <all> kxs-core;test-env
2 <all> <all> kxs-core;test-env;test-pkg
3 <all> <all> kxs-core;test-env;test-pkg;new-pkg
Examples:
kxsctl deploy apply -a new-pkg
kxsctl deploy apply -a new-pkg 2
kxsctl deploy apply -a new-pkg 2 RDB
Rename a package in an existing deployment¶
The deploy apply command can be used to rename a package in an existing directory list by means of the -c option. It can be used to rename in any existing revision number with any subset of processes/service classes/nodes. If the arguments are omitted, the revision number used is the most recent revision in effect and all targets are used.
In the example below, the package new-pkg is renamed to renamed-pkg for revision 3, which generates a new deployment with revision 4 and dynamically propagates the change to all processes.
[root@kxsa packages]# kxsctl deploy apply -c "new-pkg:renamed-pkg"
This will generate a new deployment derived from revision 3 and apply it to all nodes,
using directory list: kxs-core;test-env;test-pkg;renamed-pkg
Continue? [yN] y
Process version registry updated, revision=4
[root@kxsa packages]# kxsctl deploy list
Revision Nodes Processes/Service Classes Directory List
-------- ----- -------------------------- ----------------------------------------
1 <all> <all> kxs-core;test-env
2 <all> <all> kxs-core;test-env;test-pkg
3 <all> <all> kxs-core;test-env;test-pkg;new-pkg
4 <all> <all> kxs-core;test-env;test-pkg;renamed-pkg
Examples:
kxsctl deploy apply -c "new-pkg:renamed-pkg"
kxsctl deploy apply -c "new-pkg:renamed-pkg" 3
kxsctl deploy apply -c "new-pkg:renamed-pkg" 3 RDB
Delete a package from an existing deployment¶
The deploy apply command can be used to delete a package from an existing directory list by means of the -d option. It can be used to delete from any existing revision number with any subset of processes/service classes/nodes. If the arguments are omitted, the revision number used is the most recent revision in effect and all targets are used.
In the example below, the package test-pkg is deleted from revision 4, which generates a new deployment with revision 5 and dynamically propagates the change to all processes.
[root@kxsa packages]# kxsctl deploy apply -d test-pkg
This will generate a new deployment derived from revision 4 and apply it to all nodes,
using directory list: kxs-core;test-env;renamed-pkg
Continue? [yN] y
Process version registry updated, revision=5
[root@kxsa packages]# kxsctl deploy list
Revision Nodes Processes/Service Classes Directory List
-------- ----- -------------------------- ----------------------------------------
1 <all> <all> kxs-core;test-env
2 <all> <all> kxs-core;test-env;test-pkg
3 <all> <all> kxs-core;test-env;test-pkg;new-pkg
4 <all> <all> kxs-core;test-env;test-pkg;renamed-pkg
5 <all> <all> kxs-core;test-env;renamed-pkg
Examples:
kxsctl deploy apply -d test-pkg
kxsctl deploy apply -d test-pkg 4
kxsctl deploy apply -d test-pkg 4 RDB
Apply an existing deployment¶
The deploy apply command can be used to apply any existing revision number to any subset of processes/service classes/nodes.
In the example below, revision number 2 is applied to all processes and the change of directory list is dynamically propagated to all processes.
[root@kxsa packages]# kxsctl deploy apply 2
Applying revision 2 to all nodes
Continue? [yN] y
Process version registry updated, revision=2
[root@kxsa packages]# kxsctl deploy list
Revision Nodes Processes/Service Classes Directory List
-------- ----- -------------------------- ----------------------------------------
1 <all> <all> kxs-core;test-env
2 <all> <all> kxs-core;test-env;test-pkg
3 <all> <all> kxs-core;test-env;test-pkg;new-pkg
4 <all> <all> kxs-core;test-env;test-pkg;renamed-pkg
5 <all> <all> kxs-core;test-env;renamed-pkg
2 <all> <all> kxs-core;test-env;test-pkg
Examples:
kxsctl deploy apply 2
kxsctl deploy apply 2 RDB
Perform a partial release¶
When generating a deployment targeting specific service classes or processes on all or a subset of nodes, the choice of targets depends on what is being released. For example:
- When adding or modifying an API, all GWs and RPs of the involved nodes must be targeted.
- When adding an MRU table, all on-disk databases (IDBs and HDBs) including DBW must be targeted if at least one RDB is targeted.
Look up the revision number associated with processes¶
The revision number associated with a process may be viewed by using the kxsctl status command combined with the verbose option. In the following example, we can see distinct revision numbers associated with the different service classes.
[root@kxsa /]# kxsctl status DBW RDB HDB MDL SDL -vv
PID Name Active State Revision Port
--- --------- ------ ------ -------- ----
333 kxsDBW_A Y ACTIVE 2 5551
440 kxsRDB_A1 Y ACTIVE 2 5555
450 kxsHDB_A1 Y ACTIVE 2 5557
430 kxsMDL_A Y ACTIVE 1 5553
435 kxsSDL_A1 Y ACTIVE 1 5554
[root@kxsa /]#
Perform a dynamic rollback¶
You can roll back one or more releases (that is, downgrade) to the revision level by applying a previous revision number to the processes/service classes of interest on the nodes of interest. Consult with the deployment list to obtain the revision number associated with the directory list you want to roll back to.
Note
Depending on the nature of the changes being rolled back, manual intervention of process restarts may be required. Testing all operations in a suitable testing/UAT environment is strongly encouraged.
Upgrade a script or instruction file¶
In addition to deploying packages through the CLI, upgrading a q script attached to a process has its own requirements:
- If you are upgrading an existing version of the script, the script must be marked as reloadable using the
.load.once[]or.load.dyn[]predicates. - If you are adding a new script to a process, the script must be listed in the
librariesfield inprocess.yamlfor any row that controls the process in question.
Next steps¶
- Perform an offline upgrade for upgrades that require a system or node restart.
- Troubleshooting if something goes wrong during an upgrade.