Configure a Package
This page provides detailed instructions for configuring your package to enable seamless deployment, management across environments, and debugging and logging.
The CLI can act on files in any of the following locations:
-
The current working folder.
-
The package path (
KX_PACKAGE_PATH): Packages in this location are known to be installed locally. -
The
.kxipackage path (KX_ARTIFACT_PATH): The location where.kxipackages are stored. Optionally, before uploading to kdb Insights Enterprise, packages can be packed as.kxipackage files. -
The kdb Insights Enterprise URL: Packages can be uploaded, deployed, torn down, and removed from kdb Insights Enterprise.
Configure environment variables
You can specify the packaging specific variables as environment variables or in the ~/.insights/pakx-config file as defined below:
| variable | file | key in config | default | description |
|---|---|---|---|---|
KX_PACKAGE_PATH |
pakx-config |
KX_PACKAGE_PATH |
/tmp |
Where "installed" packages are stored |
KX_ARTIFACT_PATH |
pakx-config |
KX_ARTIFACT_PATH |
/tmp |
Where .kxi packages are stored |
Environment variables take precedence over keys in the configuration file. For example: export KX_PACKAGE_PATH=/some/where.
Recommendations when setting these variables.
-
If the
KX_PACKAGE_PATHis not set, it will be set to a temporary directory (which your OS may clean up unexpectedly). -
KX_PACKAGE_PATHandKX_ARTIFACT_PATHshould not be set to the same folder.
❯ cat ~/.insights/pakx-config | head -5
[envvars]
KX_PACKAGE_PATH = ""
KX_ARTIFACT_PATH = ""
KX_PACKAGE_FORMAT = ".yaml"
After configuring the tool to connect to a running kdb Insights Enterprise instance as described in the CLI authentication, you can verify the connection by running the following command:
kxi pm list
This command returns all available packages in your kdb Insights Enterprise deployment.
Configure debugging and logging flags
In addition to passing in the various directory variables as command line arguments, you can also pass in debug and log level flags. Use the kxi package --help command for more information and a full list of possible arguments.
Log level
To increase log verbosity, add the -v modifier to the kxi package command. You can add this modifier multiple times to increase the log level further. The following example demonstrates this:
kxi package -vvv <subcommand>
Debug mode
Debug mode controls whether the error traceback gets printed and is intended to be helpful for developers:
kxi package --debug <subcommand>
Quiet mode
Quiet mode minimizes the printout to only the result without any other messages. This can be helpful if you need to pipe the output:
kxi package -q <subcommand>
Debug and log level flags need to be directly after kxi package when running the command
For example:
kxi package --debug --add database
Package help
The kxi package --help command provides detailed information about kxi Insights Packages, including available options and commands for managing packages within kdb Insights Enterprise. This command is useful for understanding how to build, configure, and manage packages effectively.
Run the kxi package --help command for more information and a full list of possible arguments.
kxi package --help
Usage: kxi package [OPTIONS] COMMAND [ARGS]...
Insights Package Building CLI.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version Show the version and exit. │
│ --artifact-store DIRECTORY │
│ --pkg-lib DIRECTORY │
│ --debug Enable stacktrace print statements and │
│ increase verbosity for easier │
│ debugging. │
│ --verbose -v INTEGER RANGE Increase verbosity level │
│ --quiet -q Disable logs. Only print errors. │
│ --stacktrace Enable stacktrace print statements. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Remote group of commands ───────────────────────────────────────────────────╮
│ remote Insights Package Manager Service commands. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ For managing configuration ─────────────────────────────────────────────────╮
│ config Local configuration options. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ For managing components added to package ───────────────────────────────────╮
│ add Add an entity to the specified package. │
│ copy Copy an entity from the specified package. │
│ rm Remove an entity from the specified package. │
│ field Find, list or mutate fields within a package. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ For local development ──────────────────────────────────────────────────────╮
│ init Creates a bare package at the specified target path. │
│ install Install a package given a requirement or path. │
│ list List all installed packages or artifacts. │
│ lock Lock the q files within a source directory. Files whose first │
│ line is /dnc or //dnc will be ignored. │
│ packit Create a package artifact given a source code directory. │
│ uninstall Uninstall specified locally installed packages and artifacts. │
│ unpack Unpack an artifact to a specified location. │
│ validate Validate the contents of a source directory to ensure it is a │
│ valid package. │
│ checkpoint Create a package artifact given a source code directory. │
│ convert Converts Assembly specs to packages or changes package format. │
│ info show some info about the package │
│ refresh Refresh a package, picking up any available changes from disk │
│ overlay Overlay a package using a spec file containing a subset of │
│ fields. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Deprecated commands, use `kxi pm` group instead ────────────────────────────╮
│ pull (Deprecated) Download an artifact from the running insights │
│ package manager service to your local directory. Where │
│ NAMEVER is the 'name[/version]' of the artifact we want to │
│ pull from the service. │
│ push (Deprecated) Publish an artifact to the running insights │
│ package manager service. Where ARTIFACT is either the │
│ filepath or the 'name/version' of the artifact. │
│ remote-list (Deprecated) List all installed packages or artifacts on the │
│ running insights package manager service. │
│ remote-remove (Deprecated) Remove packages or artifacts from the running │
│ insights package manager service. │
│ remote-convert (Deprecated) Convert V1/V2 assemblies into Packages with the │
│ server. Optionally keep the package installed on the │
│ server. │
│ remote-config (Deprecated) Set a configuration option for the remote │
│ package manager. │
│ deploy (Deprecated) Deploy a package to an insights instance. │
│ teardown (Deprecated) Teardown one or multiple deployed packages │
│ running on an insights instance. │
╰──────────────────────────────────────────────────────────────────────────────╯
Next steps
- Find out how to create a package.