Skip to content

Licensing workflow

Licensing has two phases:

  1. Enrolment:

    • Creation of a tenant
      • Top level organisation group to contain your environments
      • Used for administration, applying permissions and billing purposes
      • Tenants may be created within tenants to reflect your internal organisation structure
    • Entitlement of a tenant
      • Describes the type of licenses that may issue to registered environments
      • This process is handled by your KX account or license administrator (e.g. licadmin@kx.com)
    • Creation of one or more environments within your tenant
      • A workstation, a container, an entire cloud account, ...
      • This step creates an 'identity document' for the environment

  2. Lifecycle management of license

    • Issuing/Creation/Renewal
    • License targets an enrolled environment
    • Can only be done after the entitlement process is completed

Creating a tenant requires an active internet connection. HTTP(S) proxies are supported through use of a {http,https}_proxy environment variable, but can be done from any system.

Tenant entitlement requires the user to request the KX license administration team that they are allowed to issue their own licenses. Environment enrolment must be done from within the target environment but may be performed offline.

Life cycle management of the license may be done from any system including the target.

Enrolment

Start by authenticating with KX's license server using the instructions on Quickstart.

Once authenticated, create a tenant using the command below, replacing My Tenant with a name of your choosing:

$ klic tenant create 'My Tenant' --description "klic docs tenant"

that returns:

created new tenant eeec2610-b013-11ec-9f77-8f5916ce8c5b (owner group eeef11c2-b013-11ec-9f77-5f80737bdae9)

Once created you will be provided with a UUID (referred to as TENANT-UUID) that you will need to make a note of. Though you may recover it by listing the tenants available to you with

klic tenant list

that returns: 

tenant                                name         description    parent
------------------------------------  -----------  -------------  --------
eeec2610-b013-11ec-9f77-8f5916ce8c5b  My Tenant    klic docs

Warning

To complete onboarding, you need to send the TENANT-UUID to your account manager for them to arrange for your tenant to be entitled to issue licenses. Until this is done you will be unable to issue licenses but you may still enrol environments.

Entitlement

Send your TENANT-UUID to your account manager and licadmin@kx.com who will arrange for you to be able to issue licenses to your tenant.

Environment

Before generating licenses for a deployment, you must first enrol it into the license service. An environment describes a deployment, which covers everything from your workstation, to containers, to entire cloud provider accounts.

The process of enrolment captures an identity document for it, that licenses are then coupled to. If you change the underlying environment or try to import licenses from other environments, kdb+/q will refuse to start.

The components of an identity document are described in the Identity Document and observable with klic environment describe <ENVIRONMENT-UUID> and klic license describe <LICENSE-UUID> as shown later.

You may have zero or more environments associated under a tenant and the process of enrolment only needs to be done once. Enrolment is always carried out on the target. If the target is a container technology (Docker, Kubernetes, ...) it must be performed from inside a container.

The klic tool is required on the target to complete enrolment but once done it is no longer needed. The process to enrol an air-gapped environment (without Internet access) is described.

Offline enrolment

Described is the process for users working with environments like;

  • user workstations
  • virtual machines
  • cloud instances (GCP, AWS, Azure, ...)

Run the command below to capture the identity document for the target environment:

klic environment create <TENANT-UUID> 'My Environment' --description "klic docs environment"

created new environment bee1445e-b014-11ec-8a97-c3addb945bb9

Warning

This step requires a functioning version of kdb+ Cloud Edition 4.0 (>=202.01.31) installed at $QHOME or $HOME/q and the current directory or $QLIC to be a writable location

Once created you will be provided with a UUID (referred to as ENVIRONMENT-UUID) that you will need to make a note of, though you may recover it by listing the environments available to you with:

klic environment list <TENANT-UUID>

environment                           name            description
------------------------------------  --------------  ---------------------
bee1445e-b014-11ec-8a97-c3addb945bb9  My Environment  klic docs environment

It is crucial that you run the environment enrolment process on the target system, which usually is a straightforward process, but be aware that if the target is a container technology (Docker, Kubernetes, LXD/LXC, ...) then you must make sure you run this process from within a container.

You can inspect the identity captured during the process by running:

klic environment describe <ENVIRONMENT-UUID>

environment  bee1445e-b014-11ec-8a97-c3addb945bb9
tenant       eeec2610-b013-11ec-9f77-8f5916ce8c5b
name         My Environment
description  klic docs environment
created      2022-03-30 10:32:48.966592
modified     2022-03-30 10:32:48.966592
disabled     False
identity     ['fqdn:host.example.com', 'os:l64', 'bid:ff5e0641-f4d5-4a12-bb07-7662dc1c3c91', 'mid:a447852a9ad94a3187d96c3839c97ea3']
tags         []

For container environments, in the 'identity' section, you should see 'container' and a value for it recorded. If you do not, your container has been registered to the host and the license will not work for the containers.

The identity document page provides details on the components that contribute to an identity document.

Identity Document

Supported targets

The target system that enrols your environment and maintains licenses must run one of the following

The system that enrols your environments (recall this must be run in the environment) and maintains licenses must run one of the following:

Warning

If WSL2 is used as a target environment, /etc/machine-id is empty and will need to be populated manually using:

cat /proc/sys/kernel/random/uuid | tr -d '-' | sudo tee /etc/machine-id >/dev/null

License management lifecycle

Issuing

Now you have enrolled your environment, you may issue licenses for it from any system (even your own workstation) by running:

klic license create <ENVIRONMENT-UUID> 'My License' --description "klic docs license"

saved 'kx.lic' to '/home/user/q/lic'
created new license 19e88cba-b01d-11ec-b34b-4fec06a3a425

Once created you will be provided with a UUID (referred to as LICENSE-UUID) that you will need to make a note of, though you may recover it by listing the licenses issued to you with:

klic license list <ENVIRONMENT-UUID>

license                               name        description
------------------------------------  ----------  -----------------
19e88cba-b01d-11ec-b34b-4fec06a3a425  My License  klic docs license

Tip

LICENSE-UUID is included in the banner when you start kdb Insights

When you create a license, the process will write out a kx.lic file to the directory pointed to by your $QLIC variable or when not present the current working directory. To use it install it into the assets directory of your target environment that is pointed to by the QLIC environment variable you have set and then run kdb+, kdb Insights or kdb Insights Enterprise. You should now be presented with a functioning instance.

The expiry time on kx.lic defaults to the maximum allowed duration of ninety (90) days but you may use --duration DAYS to shorten that when creating a license. The limit should have no impact as once ⅔rd of the validity period has passed you will be able to request a renewal using the service and continue without interruption; choosing a shorter license duration tends to result in a more reliable deployment.

Scope

By default, the enrolment process builds an identity document for the local system only making the licensing materials non-transferable.

If though your target is either an AWS, Azure or GCP instance (or container running on such an instance) you may pick a license that is scoped 'global' which is instead tied to your AWS account, Azure subscription or GCP project ID respectively.

klic license create --scope global ENVIRONMENT-UUID ...

Renewal

Like issuing, this can be done on any system, and only requires you to run:

klic license renew <LICENSE-UUID>

There is no output from this command, but it does return exit code zero (0) on success and non-zero on failure. After renewing the license, you can inspect the changes took place.

klic license describe <LICENSE-UUID>

license      050b34b6-938d-11ec-ad16-8766a33d30bd
environment  bd7259d4-9389-11ec-9907-9ffaae04230b
tenant       1453c0e8-9386-11ec-9c64-a747bf6bfc0a
name         My License
description
entitlement  87cbb7e6-938c-11ec-9c6f-43a2b6841a5e
disabled     False
created      2022-02-22 03:10:42.582202
duration     10
notbefore    2022-03-02
notafter     2022-03-12
scope        global
identity     ['cloudacct:gcp:731028316110']
features     ['insights.lib.embedq', 'insights.lib.pykx', 'insights.lib.sql', 'insights.app.rt']
tags         []

The notbefore and notafter fields have shifted.

Now the license has been renewed, you need to fetch a copy of it (again from 'any' host):

klic license fetch LICENSE-UUID

saved 'kx.lic' to '/home/user/q/lic'

There is no output from the renew command but it does return exit code zero (0) on success and non-zero on failure. After renewing you can inspect the changes using klic license describe <LICENSE-UUID>.

If you run this before the ⅔'rd mark of license validity (e.g. before day 60 of a 90 day validity) then klic license renew ... will produce an error and klic license fetch ... will continue to return the existing license. After the ⅔rds mark, the license will be renewed with an extended validity covering the next LIFETIME period.

Monitoring

It is strongly recommended you set a daily scheduled task (e.g. systemd.timer or a cron job) against your kx.lic. You should also use your monitoring platform to verify that you have at least ten days of validity for the license and to alert you when this is not the case to take action.

To obtain the number of days before your license expires, use:

    echo '-1 string("D"$.z.l 1)-.z.d;' | $QHOME/l64/q -q

As an example, for a typical 90 day duration license, you are allowed to renew it when 30 days remain; which ever is the larger of either one-third of the remaining duration or three (3) days. You should configuration the alert to sends warnings below 28 days and go critical at 10 days.

The renewal process can be automated by service accounts. Service Accounts

Tagging

Tenants, environments, licenses and groups can all be tagged with arbitrary information. You can do this during creation of the entity or later amend with the entity tag sub-command.

klic tenant create 'My Tenant' key1=value1 key2="value2a and value2b"

Also you can use the following (with no =value it is treated as a remove option):

klic tenant tag <TENANT-UUID> key1=value1b key2

You can also update the name and description of the entity by setting the case-sensitive key Name or Description respectively. Although you are able to remove the description, you may not remove the name.