Skip to content

Uploading a package

Once you have generated a package artifact by following the instructions here, you may wish to introduce it to your deployment of kdb Insights Enterprise. Similar to the generation of your artifact, the upload to kdb Insights Enterprise is facilitated through the use of kdb Insights CLI, in particular through use of the kxi package push command. The following outlines its usage:

$ kxi package push --help
Usage: kxi package push [OPTIONS] NAMEVER

  Publish a package artifact to a running service.

  NAMEVER should be specified like 'name/ver'

Options:
  --force  Will overwrite existing packages & their dependencies
  --help   Show this message and exit.

Required configuration

To facilitate pushing your package to kdb Insights Enterprise the users must supply the following information:

Required input description CLI based input Environment variable
Insights URL The URL defining the insights instance with which you are interacting --url INSIGHTS_URL
Insights Client ID The public client identifier defining who is interacting with the Insights instance --client-id INSIGHTS_CLIENT_ID
Insights Client Secret The authorization secret associated with the public client identifier --client-secret INSIGHTS_CLIENT_SECRET

To ensure you can interact with your kdb Insights Enterprise instance you must either set these environment variables or pass their value as part of server requests.

The information required for setting this configuration can be retrieved through use of following Kubernetes command:

kubectl get secret keycloak-realm -n <user-namespace> -o json | jq -r ".data[]" |base64 -d

Once executed, you must find a serviceAccountClientID which has the realmRole insights.package.* use the value for serviceAccountClientID to define your client.id and search the available clients to find its corresponding secret value.

Note

In all the examples below unless otherwise specified it is assumed that the commands executed are using environment variable set configuration.

Performing an upload

Once you have access to the required configuration and have decided how you will set it for your use-case, you should then be in a position to upload your package. Once a named and versioned package artifact has been created using the packit command as demonstrated here, you can upload it to kdb Insights Enterprise as follows using a named or default profile.

$ export INSIGHTS_URL="https://testnamespace.location.kx.com"
$ export INSIGHTS_CLIENT_ID="testclientid"
$ export INSIGHTS_CLIENT_SECRET="testclientsecret"
$ kxi package push test_pkg/0.0.1
$ kxi package push \
--url "https://testnamespace.location.kx.com" \
--client-id "testclientid" \
--client-secret "testclientsecret" \
test_pkg/0.0.1

Packages uploaded to kdb Insights Enterprise must be defined as a unique name + version pair, specifically, should you attempt to upload a version of a package that already exists on your kdb Insights Enterprise installation, the install is skipped, resulting in a message similar to the following:

{
    "test_pkg": [
        {
            "version": "0.0.1",
            "_status": "InstallationStatus.SKIPPED"
        }
    ]
}
Error: All installations skipped

In the case that you are uploading a package and require packages to be overwritten you can use the --force option as follows:

$ kxi package push --force test_pkg/0.0.1

Inspecting uploaded packages

Once a package has been pushed to kdb Insights Enterprise it may be useful to validate it has been successfully uploaded to the server. This can be done using the remote-list command defined as follows:

$ kxi package remote-list --help
Usage: kxi package remote-list [OPTIONS]

  List all installed packages or artifacts on the remote system.

Options:
  --fields TEXT      List only the specified fields
  -f, --filter TEXT  Key value pair to filter on. In particular name and
                     version
  --artifacts        If passed, list available artifacts on the system
  --simple           If passed, list available artifacts on the system
  --help             Show this message and exit.

The following example shows listing the packages on a kdb Insights Enterprise installation containing two packages ml and test_pkg under various conditions:

  1. Default list functionality
  2. Retrieving all information about the packages uploaded using the --fields command
  3. Filtering on a specific named package with limited field information returned
$ kxi package remote-list                               
{
    "test_pkg": [
        {
            "version": "0.0.1",
            "fields": {}
        }
    ],
    "ml": [
        {
            "version": "1.0.0",
            "fields": {}
        }
    ]
}
$ kxi package remote-list --fields all
{
    "test_pkg": [
        {
            "version": "0.0.1",
            "fields": {
                "name": "test_pkg",
                "version": "0.0.1",
                "license": "",
                "dependencies": {},
                "entrypoints": {
                    "default": "init.q"
                },
                "metadata": {
                    "description": "",
                    "authors": {
                        "conormccarthy": {
                            "email": ""
                        }
                    },
                    "entitlements": {},
                    "uuid": "fadf2c54-acaa-4a44-b948-0eb10cf2edde",
                    "pakxtime": "2022-12-31T19:40:13.470337"
                },
                "system": {
                    "_pakx_version": "1.2.0rc2"
                },
                "pipelines": {},
                "udfs": {
                    "names": [
                        "udf"
                    ]
                },
                "databases": {}
            }
        }
    ],
    "ml": [
        {
            "version": "1.0.0",
            "fields": {
                "name": "ml",
                "version": "1.0.0",
                "license": "",
                "dependencies": {},
                "entrypoints": {
                    "default": "ml.q"
                },
                "metadata": {
                    "description": "lorem ipsum dolar est",
                    "authors": {
                        "conormccarthy": {
                            "email": null
                        }
                    },
                    "uuid": "15122015-75e8-4249-9d94-188d4a47d55c",
                    "pakxtime": "2022-12-28T14:17:24.795340"
                },
                "entitlements": {},
                "system": {
                    "_pakx_version": "1.2.0rc2"
                },
                "pipelines": {},
                "databases": {},
                "udfs": {
                    "names": [
                        "udf"
                    ]
                }
            }
        }
    ]
}
$ kxi package remote-list --filter name=test_pkg --fields metadata,system
{
    "test_pkg": [
        {
            "version": "0.0.1",
            "fields": {
                "metadata": {
                    "description": "",
                    "authors": {
                        "conormccarthy": {
                            "email": ""
                        }
                    },
                    "entitlements": {},
                    "uuid": "fadf2c54-acaa-4a44-b948-0eb10cf2edde",
                    "pakxtime": "2022-12-31T19:40:13.470337"
                },
                "system": {
                    "_pakx_version": "1.2.0rc2"
                }
            }
        }
    ]
}