Skip to content

KDB-X Workload YAML (Beta)

This page describes the schema used in the workload.yaml file and how to modify it.

When you run kxi package add --to <packagename> workload for the first time, the command creates a workload.yaml file to manage the workloads in the package. Each subsequent call to kxi package add --to <packagename> workload appends a new workload configuration to the existing workload.yaml file.

Resource Types

The workload.yaml consists of the following resource types:

KdbXGroupSpec

KdbXGroupSpec defines the desired state of a KDB-X group.

A KDB-X group is a collection of KDB-X instances with shared persistent storage.

Field Description
instances KdbXMap A map of KdbX instance specifications.
The map key is the unique name for each instance.
When deployed, each instance name is prefixed with the group name.
Example: an instance named tp in a group named tick is deployed as 'tick-tp'.
storage KdbXGroupSharedStorage Defines the optional Persistent Volume Claim (PVC) configuration.
If configured, the system creates a PVC and mounts it to every KDB-X
instance in the group
Note: The PVC must use a StorageClass that supports the ReadWriteMany access mode.
Refer to Access Modes for details.

KdbXGroupSharedStorage

KdbXGroupSharedStorage defines a Persistent Volume Claim (PVC) that all KDB‑X instances in the group share.

Appears in: KdbXGroupSpec

Field Description Default Validation
enabled (boolean) When set to true, the system creates a PersistentVolumeClaim (PVC) and provides shared storage for all instances. false Type: boolean
name string Specifies the unique identifier for the PersistentVolumeClaim (PVC).
The system uses this name to mount the PVC into every instance in the group.
If you leave this field empty, the system generates a default name.		 MaxLength: 63
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Type: string
mountPath string Specifies the absolute path within the KdbX instance container where the volume is mounted.
Important: Do not include the colon (:) character in the path.		 /app/shared Pattern: ^\/+([a-zA-Z0-9_.-]+\/*)+$
Type: string
accessModes PersistentVolumeAccessMode array Defines how the volume can be mounted.
Common values are ReadWriteOnce (RWO), ReadOnlyMany (ROX) or ReadWriteMany (RWX).

RWO - Best for pod only storage
RWX - Required for shared storage across pods

Refer to Access Modes		 [ReadWriteMany] for details.
storageClass string Specifies the name of the StorageClass that the volume should use.
If you omit this field or set it to an empty string (""), the cluster uses its default.
Refer to Storage Classes for more information.		 Type: string
size string Defines the capacity of the volume.
Use standard Kubernetes resource‑quantity formats (for example, Gi, Mi, or Ti).		 20Gi Pattern: ^([0-9]+(\.[0-9]+)?)([EPTGMK]i?)?$
Type: string

KdbXMap

Underlying type: map[string]*KdbXSpec

KdbXMap defines a mapping of unique instance names to their corresponding KDB‑X instance specifications.

Appears in: KdbXGroupSpec

KdbXSpec

KdbXSpec defines the desired state of a KDB-X instance.

Appears in: KdbXMap

Field Description Default Validation
attach boolean When set to true, enables TTY and STDIN on the instance containers.
This allows you to 'attach' to a running container for interactive debugging.		 false Type: boolean
replicas integer Defines the desired number of pods for the instance.
This is a pointer, allowing the system to distinguish an explicitly set value of 0 from an unspecified value.		 1 Minimum: 1
Type: integer
port integer Specifies the container port to expose. 5000 ExclusiveMaximum: true
Maximum: 65535
Minimum: 1
Type: integer
env EnvVar array Provides a list of environment variable to inject into the container.
Refer to Define Environment Variables for details.
args string array Defines the list of arguments to be passed to the container's entrypoint.
Refer to the Define Command Arguments documentation.
package PackageDependency Defines the primary dependency that the KdbX instance loads
on initialization.
Examples:
package-dependency==1.2.3
package-dependency>1.2.3
package-dependency!=1.2.3		 Pattern: ^[a-zA-Z][a-zA-Z0-9-]*(\s*(==\|>=\|<=\|>\|<\|~=\|===\|!=)\s*[0-9a-zA-Z.+-]+(\s*,\s*(==\|>=\|<=\|>\|<\|~=\|===\|!=)\s*[0-9a-zA-Z.+-]+)*)?$
Type: string
initFile string Specifies the script to execute on KdbX instance initialization.
The script must exist within the package.		 Type: string
dependencies PackageDependencyList Lists the packages that this KdbX instance depends on.
Dependencies are sourced and loaded by KdbX instance init container.		 Pattern: ^[a-zA-Z][a-zA-Z0-9-]*(\s*(==\|>=\|<=\|>\|<\|~=\|===\|!=)\s*[0-9a-zA-Z.+-]+(\s*,\s*(==\|>=\|<=\|>\|<\|~=\|===\|!=)\s*[0-9a-zA-Z.+-]+)*)?$
Type: string
serviceType ServiceType Determines how the instance is exposed within or outside the cluster.
If you omit or set to None the system does not create a Service resource.

ClusterIP - Exposes the service internally within the cluster only.
NodePort - Exposes the service externally using a node’s external IP and an allocated port.
LoadBalancer - Exposes the service externally using a load‑balancer‑provisioned IP and service port.

Refer to Service Types for more details.
 Enum: [None ClusterIP NodePort LoadBalancer]
exposeAPIs boolean When set to true, exposes an HTTP endpoint externally.

Note: Requires that ServiceType to be set to a value other than None.		 Type: boolean
volumes VolumeAndMountList Defines a list of Kubernetes volumes and their mount locations in the container.
Each list item is an object combining the Kubernetes Core Volume and VolumeMount resources.
This allows you to mount external resource such a ConfigMaps, Secrets or PVCs.
storage KdbXStorage Defines the configuration for optional persistent storage for the
KdbX instance.

Note: The system creates one PersistentVolumeClaim (PVC) per ordinal of the KdbX instance's StatefulSet.

KdbXStorage

KdbXStorage defines the configuration for data persistence of the KDB-X instance.

Appears in: KdbXSpec

Field Description Default Validation
enabled boolean When set to true, triggers the creation of a PersistentVolume (PVC) to
provide storage for the instance.

Note: The system creates one PVC per ordinal of the KdbX instance’s StatefulSet.		 false Type: boolean
mountPath string Specifies the absolute path within the KdbX instance container where the volume is mounted.
Important: Do not include the colon (:) character in the path.		 /app/data Pattern: ^\/+([a-zA-Z0-9_.-]+\/*)+$
Type: string
accessModes PersistentVolumeAccessMode array Defines how volume can be mounted.
Common values are ReadWriteOnce (RWO), ReadOnlyMany (ROX) or ReadWriteMany (RWX).

RWO - Best for pod only storage
RWX - Required for shared storage across pods

Refer to Access Modes for details.		 [ReadWriteOnce]
storageClass string StorageClass specifies the name of the StorageClass that the volume should use.
If you omit this field or set it to an empty string (""), the cluster uses its default.
Refer to Storage Classes for more information.		 Type: string
size string Defines the capacity of the volume.
Use standard Kubernetes resource‑quantity formats (for example, Gi, Mi, or Ti).		 20Gi Pattern: ^([0-9]+(\.[0-9]+)?)([EPTGMK]i?)?$
Type: string
persist boolean Determines the lifecycle of the persistent volume and claim when the
Owner pod resource is removed during a deletion or scale event.

True - Sets the equivalent Retain policy.
False - Sets the equivalent Delete policy.

Refer to PVC Retention for details.		 true Type: boolean

PackageDependency

Underlying type: string

Name of a package to be sourced and loaded by an instance.

Validation: - Pattern: ^[a-zA-Z][a-zA-Z0-9-]*(\s*(==|>=|<=|>|<|~=|===|!=)\s*[0-9a-zA-Z.+-]+(\s*,\s*(==|>=|<=|>|<|~=|===|!=)\s*[0-9a-zA-Z.+-]+)*)?$ - Type: string

Appears in:

PackageDependencyList

Underlying type: PackageDependency

List of packages to be sourced and loaded by an instance.

Validation: - Pattern: ^[a-zA-Z][a-zA-Z0-9-]*(\s*(==|>=|<=|>|<|~=|===|!=)\s*[0-9a-zA-Z.+-]+(\s*,\s*(==|>=|<=|>|<|~=|===|!=)\s*[0-9a-zA-Z.+-]+)*)?$ - Type: string

Appears in: KdbXSpec

VolumeAndMount

VolumeAndMount provides a simplified way to define both a Kubernetes Volume and its corresponding VolumeMount within the container

Appears in: VolumeAndMountList

Field Description Default Validation
volume Volume Defines the Kubernetes Volume resources.
This allows you to define any Kubernetes Volume source such as ConfigMap, Secret or PVC.
Refer to Storage Volumes for more details.
readOnly boolean When set to true, prevents the mounting container instance from
writing to the volume.		 false Type: boolean
mountPath string Specifies the absolute path within the KdbX instance container
where the volume is mounted.
Important: Do not include the colon (:) character in the path.		 Type: string

VolumeAndMountList

Underlying type: VolumeAndMount

VolumeAndMountList defines a list of VolumeMount resources.

Appears in: KdbXSpec

Workload creation examples

The following examples show how the workload.yaml file is defined when you use the CLI to create specific workloads.

  • Create a workload that includes its own PVC and exposes a port.

    kxi package add --to packagename workload --storage type="",dst=/opt/kdbx/data,size=10Gi --expose \--port 6000 \ --service ClusterIP \
--name test --entrypoint init.q

    Resulting workload.yaml file:

    metadata:
name: packagename
apiVersion: insights.kx.com/v2
kind: KdbXGroup
spec:
    instances:
    test:
        replicas: 1
        exposeAPIs: true
        env: []
        args: []
        initFile: init.q
        package: packagename
        port: 6000
        serviceType: ClusterIP
        storage:
        enabled: true
        storageClass: ''
        mountPath: /opt/kdbx/data
        size: 10G
    storage: {}

  • Create a workload file that includes two workloads: one from the previous example and another that uses a q file from a different package as its entrypoint.

    kxi package add --to packagename workload --storage type="",dst=/opt/kdbx/data,size=10Gi --expose --port 6000 --service ClusterIP --name test --entrypoint init.q
kxi package add --to packagename workload --deps otherpackage --storage type="",dst=/opt/kdbx/data,size=10Gi --name test2 --entrypoint otherpackage:source.q

    Resulting workload.yaml file

    metadata:
name: packagename
apiVersion: insights.kx.com/v2
kind: KdbXGroup
spec:
  instances:
    test:
      dependencies: []
      replicas: 1
      exposeAPIs: true
      env: []
      args: []
      initFile: init.q
      package: packagename
      port: 6000
      serviceType: ClusterIP
      storage:
        enabled: true
        storageClass: ''
        mountPath: /opt/kdbx/data
        size: 10G
    test2:
      dependencies:
        - otherpackage
      replicas: 1
      exposeAPIs: false
      env: []
      args: []
      initFile: source.q
      package: otherpackage
      port: 5000
      serviceType: null
      storage: {}
  storage: {}

  • Create a workload that depends on modules and packages, uses a shared Rook‑Ceph PVC, sets environment variables (including a reference to the shared PVC), enables metrics, and exposes a port.

    kxi package add --to packagename workload --deps dbutils,schemas --env WRITE_TO_LOG=1 --env TPLOG_DIR=/kdbx/data --service ClusterIP --group-storage type="rook-cephfs",dst=/kdbx/data,size=2Gi,accessMode=ReadWriteMany --metrics tickmets:10s --expose --name tp --entrypoint init.q --group-metrics tickmets:10s

    Resulting workload.yaml file

    apiVersion: insights.kx.com/v2
kind: KdbXGroup
metadata:
  name: packagename
  annotations:
      kdbx.kx.com/metrics: '{"enabled": true, "endpoint": "tickmets", "interval": "10s"}'
spec:
  instances:
    tp:
      dependencies:
        - dbutils
        - schemas
      replicas: 1
      exposeAPIs: true
      env:
        - name: WRITE_TO_LOG
          value: '1'
        - name: TPLOG_DIR
          value: /kdbx/data
      args: []
      initFile: init.q
      package: packagename
      port: 5000
      serviceType: ClusterIP
      storage: {}
  storage:
    storageClass: rook-cephfs
    mountPath: /kdbx/data
    size: 2Gi
    accessModes:
      - ReadWriteMany

Next steps

  • Explore the Development guide to understand how workload.yaml is created and used when building KDB‑X workloads.
  • Use kxi CLI workload commands to create, update, and manage workloads.