Skip to content

Container enrolment

If your deployment intends to run kdb+/q within a container you need to expose part of the host identity to the container.

This method does not cover environments where the underlying hosts are dynamic, such as Kubernetes (k8s).

License pinning approaches

There are several options and the best fit for your deployments running kdb+/q in a container is a personal choice though we have listed them in our recommended descending order of preference:

Product UUID

Arrange for /sys/devices/virtual/dmi/id/product_uuid to be readable by non-root users using one of two approaches.

  1. bind mount

    sudo cp -a /sys/devices/virtual/dmi/id/product_uuid .
chmod 444 product_uuid
docker run -it --rm -v "$PWD/product_uuid":/sys/devices/virtual/dmi/id/product_uuid:ro --user $(id -u nobody):$(id -g nobody) debian:bullseye-slim

  2. volume mount

    docker volume create kx-lic-id
sudo cat /sys/devices/virtual/dmi/id/product_uuid | docker run --rm -i -v kx-lic-id:/id debian:bullseye-slim tee /id/product_uuid >/dev/null
docker run -t --rm -v kx-lic-id:/id debian:bullseye-slim chmod 444 id/product_uuid
docker run -it --rm -v kx-lic-id:/sys/devices/virtual/dmi/id:ro --user $(id -u nobody):$(id -g nobody) debian:bullseye-slim

KX_MID

Pass a unique value for the KX_MID environment variable in your container

  • for Docker this would look like:
docker run -it --rm -e KX_MID=$(cat /etc/machine-id) debian:bullseye-slim`

This acts as a substitute for mid described in the Identity Document. Alternatively you can generate a unique value with:

cat /proc/sys/kernel/random/uuid | tr -d '-'`.

New license

Recreate your license after each reboot. The identity is tied to bid as describe in the Identity Document.

Run as root

Run the enrollment and your processes as root (not recommended).

Enrolment

Once you have picked a strategy that suits you, the process to enrol a container environment is identical to a single system though now includes a verification step that the environment identity (klic environment describe ..) captures an identifier representing the environment is a container.

After running klic environment create .., check for the presence of container:... and one of cid:..., bid:... or emid:... in the identity captured for the registered environment.

klic environment describe <ENVIRONMENT-UUID>
environment  bd7259d4-9389-11ec-9907-9ffaae04230b
tenant       1453c0e8-9386-11ec-9c64-a747bf6bfc0a
name         My Environment
description
disabled     False
identity     ['fqdn:bc81549b15d1', 'os:l64', 'emid:0a46bc70719b4a29bcfda85ee67b9af3', 'container:cgroup']
tags         []

License Issuing

On any host verify that you have one or more entitlements assigned to your tenant.

klic entitlement list 1453c0e8-9386-11ec-9c64-a747bf6bfc0a
tenant                                entitlement                           name              description    tier
------------------------------------  ------------------------------------  ------            -------------  ------
1453c0e8-9386-11ec-9c64-a747bf6bfc0a  87cbb7e6-938c-11ec-9c6f-43a2b6841a5e  Your Entitlement                 core

For this example, the 'entitlement UUID' is 87cbb7e6-938c-11ec-9c6f-43a2b6841a5e that we will refer to as using the placeholder <ENTITLEMENT-UUID> for the rest of the document.

The entitlement can be examined.

klic entitlement describe 87cbb7e6-938c-11ec-9c6f-43a2b6841a5e
tenant       1453c0e8-9386-11ec-9c64-a747bf6bfc0a
entitlement  87cbb7e6-938c-11ec-9c6f-43a2b6841a5e
name         Your Entitlement
description
disabled     False
tier         core
scope        global
duration     10
created      2022-02-22 03:07:12.459386
modified     2022-02-22 03:07:12.459386
tags         []

Note

Though typically ninety (90) days, this example entitlement has a maximum license validity duration that is ten (10) days.

A license can then be created by as below (replacing 'My License' with a short relevant name):

klic license create ENVIRONMENT-UUID 'My License' --entitlement ENTITLEMENT-UUID --duration 10
saved 'kx.lic' to '/home/user/q/lic'
created new license 050b34b6-938d-11ec-ad16-8766a33d30bd

This emits a 'license UUID' (example above shows 050b34b6-938d-11ec-ad16-8766a33d30bd). This is used to refetch and renew the license later. At any point you can examine the contents using klic license describe <LICENSE UUID>.

Installing the license

The next step is to run your containers on the generated license. The simplest way to do this is to inject the license into the container and set $QLIC to point at the location.

The example below assumes you've;

  • built a container on top of kdb+/q
  • fetched a license valid for your container environment to $HOME/q/lic/kx.lic
docker run -it --rm -v "$HOME/q/lic":/opt/kx/lic:ro -e QLIC=/opt/kx/lic <IMAGE>

For KX Insights Microservices or any other images built with qpacker, support is available for mounting licenses as a file or as an environment variable. See the docs for more information.

Qpacker

Warn

Remember to also include any additional settings (such as bind/volume mounts or environment variable) you used whilst enrolling the container earlier, to expose the host identity to the container.