How to Deploy the Runtime Provisioner

This guide shows you how to pull the Runtime Provisioner chart, set the four environment variables it requires, install it with the Role-Based Access Control (RBAC) the chart creates, and confirm it is ready to provision KSML applications.

Type

How-to guide

Goal

Get the Runtime Provisioner running so KSML applications can be deployed from Self-Service.

Audience

Platform Operator with Helm access to the target namespace and permission to create Roles and RoleBindings in it.

When to use

Use this guide when adding KSML to an installation, at stage 5 of the installation order.

The Provisioner is what turns a KSML application defined in Self-Service into a running pod. It pulls the KSML Helm chart itself, which is why it needs both a registry to pull from and permissions in the namespace it deploys into.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Access to the Axual chart registry. See Working with Helm Charts for how to gain it.

  • Permission to create a ServiceAccount, Role and RoleBinding in the target namespace. The chart creates these by default.

Tools and versions required

You need the following tools:

  • helm >= 3.12.

  • kubectl >= 1.28.

Resources that must exist before starting

The following must already exist:

  • A running Axual Platform installation with the governance layer in place, since KSML applications are defined in Self-Service.

  • An OCI-compatible Helm registry holding the KSML chart the Provisioner will pull.

  • A Prometheus Operator in the cluster, if you want the ServiceMonitor the Provisioner creates for each KSML pod to be picked up.

Limitations

Two constraints decide whether this deployment works, so check them before installing.

  1. The Provisioner deploys KSML applications only into the Kubernetes cluster it runs in. A KSML application on another cluster needs its own Provisioner.

  2. The Provisioner pulls charts from OCI-compatible registries only. A Nexus registry is not supported.

Pull the chart

Pull the runtime-provisioner chart from the Axual registry to get a base values.yaml to work from.

helm registry login registry.axual.io --username <YOUR_USERNAME>

helm pull oci://registry.axual.io/axual-charts/runtime-provisioner \
  --version <CHART_VERSION> \
  --untar
Replace every <VALUE> placeholder with your own value before running a command. Version 0.8.0 is the first release published under the runtime-provisioner name. If a later version is available, use that one instead.

Deploying with the shipped values.yaml unchanged gives a Provisioner on the chart’s defaults, which is enough for a first look but sets no registry, so it cannot pull the KSML chart yet.

Set the required environment variables

Four environment variables have no usable default, and the Provisioner cannot pull the KSML chart without them.

env:
  - name: NAMESPACE
    value: "<TARGET_NAMESPACE>"
  - name: REGISTRY_URL
    value: "<OCI_REGISTRY_URL>"
  - name: CHART_NAME
    value: "<KSML_CHART_NAME>"
  - name: CHART_VERSION
    value: "<KSML_CHART_VERSION>"

For what each one does, and for the optional variables, see Runtime Provisioner Reference.

Install the chart

Install the chart with the values file you edited. Under a GitOps workflow, commit the values instead and let the pipeline apply them; see Deployment Strategy.

helm upgrade --install runtime-provisioner \
  oci://registry.axual.io/axual-charts/runtime-provisioner \
  --version <CHART_VERSION> \
  --namespace <TARGET_NAMESPACE> \
  --create-namespace \
  -f runtime-provisioner-values.yaml

helm upgrade --install is idempotent, so it is safe to re-run after changing a value.

Leave rbac.create and serviceAccount.create at their defaults unless you have a reason not to. The chart then creates a ServiceAccount with exactly the permissions listed in Required Kubernetes permissions, which is otherwise your job to reproduce.

Confirm the Provisioner is ready

A Running pod does not prove the Provisioner works. Both failure modes, an unreachable registry and missing Kubernetes permissions, surface only when it first tries to deploy an application, so check the pod and then its logs.

kubectl get pods --namespace <TARGET_NAMESPACE> -l app.kubernetes.io/name=runtime-provisioner

Then read the logs for the two errors that a pod check cannot show:

kubectl logs --namespace <TARGET_NAMESPACE> \
  -l app.kubernetes.io/name=runtime-provisioner --tail=100

A registry error names the REGISTRY_URL the Provisioner could not reach or authenticate against. A permissions error is a Kubernetes 403 naming the verb and resource the ServiceAccount was refused. That means the Role does not carry what Required Kubernetes permissions lists. Clean logs and a Running pod together mean the Provisioner is ready.

Then follow How to Enable KSML Support for an Instance and deploy one application as the end-to-end check. To change the namespace it deploys into, the ServiceAccount it uses, or the values it applies to each KSML pod, see How to Customise KSML Application Deployments.