Runtime Provisioner Reference

This reference lists the Runtime Provisioner’s required and optional environment variables, the settings that control Kafka Connect (KC) log reading, the variables its OpenTelemetry exporter reads, the Kubernetes permissions it needs in the namespace it deploys into, and the naming scheme it gives the resources it creates.

Type

Reference

Goal

Look up a Provisioner environment variable, a required permission, or the name a KSML resource will get.

Audience

Platform Operator configuring the Provisioner, or anyone locating the Kubernetes resources of a KSML application.

When to use

While configuring the Provisioner, and when a KSML resource cannot be found by the name you expected.

For the procedure that applies these values, see How to Deploy the Runtime Provisioner.

Contents

The sections below cover each area in this reference:

Required configuration

These four environment variables have no usable default. The Provisioner cannot pull the KSML chart without all of them.

Environment Variables Description

NAMESPACE

The Kubernetes namespace the Provisioner deploys a KSML application into.

REGISTRY_URL

The Helm Chart Registry URL where KSML Helm Charts are pulled from.

CHART_NAME

The name of the KSML Helm Chart.

CHART_VERSION

The version of the KSML Helm Chart.

Optional configuration

Everything below has a working default. Set one only to change the behaviour it controls.

Environment Variables Description

REGISTRY_AUTH_ENABLED

Set to true if Helm Chart registry requires authentication. Default false.

REGISTRY_USERNAME

Username of the Helm Chart Registry defined in REGISTRY_URL.

REGISTRY_PASSWORD

Password of the Helm Chart Registry defined in REGISTRY_URL.

CUSTOM_VALUES_FILE

Path to a custom values file containing extra configurations for KSML deployment. This is useful when configs like resources, securityContext, topologySpreadConstraints etc need to be passed.

CLIENT_CA_FILE

Path to a base64-encoded PEM file containing one or more CA certificates. It is used to validate the Helm Registry’s server certificate.

INSECURE_SKIP_TLS_VERIFY

If true, skips validation of the Helm Registry’s server certificate. This opens the connection to man-in-the-middle attacks, so do not set it in production. Default false.

DISTRIBUTED_TRACING_ENABLED

If true, enables distributed tracing with OpenTelemetry. The exporter variables are listed in OpenTelemetry exporter configuration. Default false.

Kafka Connect log reading

These chart values decide whether the Provisioner reads Kafka Connect (KC) worker logs, which namespaces it reads them from, and how much it reads per request. Each one sets the environment variable beside it.

Values key Environment variable Description

connect.enabled

CONNECT_ENABLED

Switches KC log reading on. Default false, which makes /kafkaconnect/logs answer 501. Setting it to true also creates the read-only Role and RoleBinding in each namespace listed below.

connect.namespaces

CONNECT_NAMESPACES

Namespaces to search for KC worker pods, as a list that the chart joins with commas. KC clusters usually run in a different namespace from the Provisioner, so an empty list finds no pods and /kafkaconnect/logs answers 404. Readiness checks these same namespaces, so list only ones the service account may read.

connect.containerName

CONNECT_CONTAINER_NAME

Names the worker container to read from. Needed only for a pod with several containers where none matches the strimzi.io/name label.

connect.filterWindowPercent

CONNECT_FILTER_WINDOW_PERCENT

Raw lines read per worker pod when a request filters by connector, as a percentage of the lines asked for. Default 2000. A value below 100 is clamped to 100, so lowering it never reads more.

connect.filterWindowMaxLines

CONNECT_FILTER_WINDOW_MAX_LINES

Ceiling on that read window, in lines. Default 50000.

connect.downloadCapBytes

CONNECT_DOWNLOAD_CAP_BYTES

Most a whole-log download may copy in total across every worker, in bytes. Default 67108864, which is 64 MiB. Zero or less falls back to that default.

maxConcurrentLogStreams

MAX_CONCURRENT_LOG_STREAMS

How many log reads may run at once, counting KSML and KC together. It counts pod streams rather than requests, because one KC request reads every worker of the cluster. Default 200.

connect.namespaces is also the tenancy boundary. The chart grants read permission only for the namespaces it lists, so the Provisioner cannot read one that is absent from it. Tenants that must not see each other’s logs need separate namespaces, or a Provisioner of their own.

Set KSML_ENABLED to false to serve KC logs only. The Provisioner then starts without any of the Helm or registry settings in Required configuration.

OpenTelemetry exporter configuration

The Provisioner reads these variables only while DISTRIBUTED_TRACING_ENABLED is true. They tell the exporter where the collector is and under which name the traces arrive.

Environment Variables Description

OTEL_EXPORTER_OTLP_ENDPOINT

Endpoint of the OpenTelemetry collector. Must start with http or https and include the port number.

OTEL_EXPORTER_OTLP_HEADERS

Optional headers sent to the collector, for the credentials a secured collector requires.

OTEL_SERVICE_NAME

A unique name that identifies the service in the collector.

For the procedure that sets these values, see How to Customise KSML Application Deployments.

Required Kubernetes permissions

The Provisioner needs the permissions below on its service account to deploy KSML applications.

The Provisioner Helm chart creates the service account, role and role binding itself, so no extra configuration is needed. The table lists what that role grants:

Kubernetes Resource API Group Permissions

configmaps

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

pods

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

pods/log

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

secrets

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

serviceaccounts

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

services

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

statefulsets

apps

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

prometheusrules

monitoring.coreos.com

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

servicemonitors

monitoring.coreos.com

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

ingresses

networking.k8s.io/v1

GET, LIST, WATCH, CREATE, PATCH, UPDATE, DELETE

KSML resource naming

The name of a KSML Kubernetes resource (a pod, StatefulSet or ConfigMap) combines the tenant, instance, environment and application short names:

{tenant}-{instance}-{environment}-{application}-ksml

Kubernetes limits label values to 63 characters. When the base name (without the -ksml suffix) exceeds 47 characters, the Provisioner replaces it with the first 16 characters of the SHA-256 hash of that base name:

{hash-string}-ksml

A hashed resource name keeps the original identity in its labels, so this query finds the resources whatever the name became:

kubectl get pods -n <namespace> \
  -l axual.io/tenant=<tenant>,axual.io/instance=<instance>,axual.io/environment=<environment>,axual.io/application=<application>

Docker container labels

In Docker runtime mode the Provisioner labels every container it creates, and the bulk /status endpoint matches those labels to decide which containers to report.

Label How /status matches it

axual.io/managed-by

Matched on its key, not its value. The value is runtime-provisioner from 0.8.0 and was ksml-provisioner on 0.7.x, so containers created by either version appear in the same answer and none has to be recreated after an upgrade.

axual.io/tenant, axual.io/instance

Matched on their values, so a second tenant on the same Docker daemon stays out of the answer.