Skip to content

Testing from published images on an unmodified Checkmk

Jump to bottom
Rick Elrod edited this page Aug 10, 2026 · 4 revisions

Because we are targeting compatibility with existing check plugins, most of rustik works just fine on an unmodified Checkmk 2.5 instance.

This page documents how to test it using the published master-branch images and Helm chart.

Pull Mode

First, we deploy the in-cluster agent. Eventually, a Quick Setup will guide the user through how to do this.

Create a file, values.yaml with the following:

Warning

This test YAML is insecure by default: It disable authentication on the pull endpoints. Don't use on a cluster with sensitive data in it.

clusterName: mytest
clusterHostName: mytest
logLevel: debug

metricsFetcher:
  image:
    tag: master

metricsCache:
  image:
    tag: master

  service:
    type: NodePort
    nodePort: 30050

pull:
  enabled: true
  authentication:
    enabled: false

This will bind the metrics-cache service to port 30050 via NodePort.

Note

The test yaml above uses NodePort. If you'd rather use an Ingress and you have a controller already, you can create an Ingress manually targetting the service <release name>-cmk-rustik-metrics-cache-pull and the named port pull. Note that <release name> will be rustik if you follow the command below.

Run the following:

helm upgrade --install rustik oci://ghcr.io/checkmk/charts/cmk-rustik \
  --version 0.0.0-master \
  -n checkmk-monitoring \
  --create-namespace \
  --values values.yaml

You should see output like the following:

Release "rustik" does not exist. Installing it now.
Pulled: ghcr.io/checkmk/charts/cmk-rustik:0.0.0-master
Digest: sha256:64f1cb86135dc564fc6417b3ea4dfc2d89f6e6a1c894d0328ab53776eebdb16f
NAME: rustik
LAST DEPLOYED: Mon Aug 10 13:34:19 2026
NAMESPACE: checkmk-monitoring
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None

Wait a few seconds for things to spin up. You can check the status with kubectl get pod -n checkmk-monitoring. You should see:

  • A single metrics-cache pod; and
  • A metrics-fetcher pod for every node in the cluster
  • Everything should have status Running 
$ kubectl get pod -n checkmk-monitoring
NAME                                               READY   STATUS    RESTARTS   AGE
rustik-cmk-rustik-metrics-cache-6fbb989f5b-ncvth   1/1     Running   0          2m16s
rustik-cmk-rustik-metrics-fetcher-fc4wg            1/1     Running   0          2m16s

Now you should be able to see section data if you do curl some-node:30050/pull/sections replacing some-node with the IP address of some node in your cluster. Pull mode is now working.

Now you can use the data from it in Checkmk. Since we are assuming an unmodified Checkmk 2.5, it means we do not for now rely on a special agent. Future versions of Checkmk will have a special agent (and related ruleset) that can automatically query the above URL.

For now, in Checkmk 2.5 or later, we'll use a trick to see the pull-mode data.

First, create a host:

Note

The name of this host must exactly match the clusterHostName setting in your values.yaml (mytest in the above example).

Most defaults are fine left as-is.

image

Once the host is saved, set up a new "Individual program call instead of agent access" rule:

image

Replace localhost below with the IP of your node.

image

Then proceed to the section below on creating your DCD rule.

Push Mode

Create a file, values.yaml with the following:

clusterName: mytest
clusterHostName: mytest
logLevel: debug

metricsFetcher:
  image:
    tag: master

metricsCache:
  image:
    tag: master

push:
  enabled: true

Before we can proceed, we need to collect some information from Checkmk:

  • A one-time-token (OTT)
  • The site CA certificate for push mode registration

First, download the site certificate:

Setup > Certificate overview

image

Download the certificate with description "Signing the site certificate": image

Now, create a new host and set "Checkmk agent connection mode" to push mode. You can also set "IP address family" to "No IP".

Note

The name of this host must exactly match the clusterHostName setting in your values.yaml (mytest in the above example).

After you set "Checkmk agent connection mode" a button should appear next to the dropdown. Press this button to open a slideout.

Note

In Checkmk master/3.0 there is currently a bug where this button does not show after selecting pull mode. To work around this, click show more on the right side of the "Basic settings" section of the "Add host" page, and click the check box next to "Monitored on relay" (keep the value set to the default, "No Relay"). This will force the button to show up.

image

In the slideout, keep the default selection: Linux > DEB. Click "Save host & next step".

Important

Do not run any command provided by the slideout. We are only doing this to generate a one-time token.

image

Click "Generate one-time token" and click "Next step: Register agent". Again, do not run (or save) any command provided by the slideout.

image

On the "Register agent" step, click "Generate one-time token"

image

This will generate the token we need:

image

Copy the string beginning with (and including) 0:, in this example, copy 0:c9081d9e-4b01-40c7-86b0-ef1afe91f918. Also take note of the server hostname and port number in the output. Once you have copied the token to your clipboard, you can complete the rest of the slideout and save the host.

Run the following:

helm upgrade --install rustik oci://ghcr.io/checkmk/charts/cmk-rustik \
  --version 0.0.0-master \
  -n checkmk-monitoring \
  --create-namespace \
  --values values.yaml \
  --set-file push.siteCaCertificate=<path to your downloaded ca.pem> \
  --set push.registrationToken=<your token including the 0: at the start> \
  --set push.url=https://<hostname>:<port number>/<site name>

For example, the last three arguments might be something like:

  --set-file push.siteCaCertificate=$HOME/Downloads/ca.pem \
  --set push.registrationToken=0:c9081d9e-4b01-40c7-86b0-ef1afe91f918 \
  --set push.url=https://localhost:8000/heute

Note

Helm's --set-file does not expand ~, use $HOME instead if you need to refer to your home directory.

You should see output like the following:

Release "rustik" does not exist. Installing it now.
Pulled: ghcr.io/checkmk/charts/cmk-rustik:0.0.0-master
Digest: sha256:64f1cb86135dc564fc6417b3ea4dfc2d89f6e6a1c894d0328ab53776eebdb16f
NAME: rustik
LAST DEPLOYED: Mon Aug 10 13:34:19 2026
NAMESPACE: checkmk-monitoring
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None

Wait a few seconds for things to spin up. You can check the status with kubectl get pod -n checkmk-monitoring. You should see:

  • A single metrics-cache pod; and
  • A metrics-fetcher pod for every node in the cluster
  • Everything should have status Running 
$ kubectl get pod -n checkmk-monitoring
NAME                                               READY   STATUS    RESTARTS   AGE
rustik-cmk-rustik-metrics-cache-6fbb989f5b-ncvth   1/1     Running   0          2m16s
rustik-cmk-rustik-metrics-fetcher-fc4wg            1/1     Running   0          2m16s

If all goes well, you should also see a secret get created called metrics-cache-cmk-push-cert in the checkmk-monitoring namespace (along with several others):

[tmp]$ kubectl get secret -n checkmk-monitoring 
NAME                                  TYPE                 DATA   AGE
metrics-cache-cmk-push-cert           Opaque               4      68s  # <---- success!
rustik-cmk-rustik-intra-cluster-ca    kubernetes.io/tls    3      162m
rustik-cmk-rustik-push-registration   Opaque               2      69s
sh.helm.release.v1.rustik.v1          helm.sh/release.v1   1      69s

Now push should be working. If you run into issues, check kubectl logs on the metrics-cache pod. Otherwise, you should see log lines like:

2026-08-10T14:15:56.264526Z DEBUG Successfully pushed metrics to Checkmk server

Then proceed to the section below on creating your DCD rule.

Creating your DCD rule

Now that you have data coming into Checkmk, we must create a DCD rule so that piggyback hosts get created from the sections.

Go to Setup > Dynamic host management:

image

Click "Add connection", and set up a new Piggyback connector:

image

Now activate your changes and wait for DCD to run (up to two minutes in the worst case: one minute per DCD cycle and one minute per Push cycle from the in-cluster agent).

Soon, resources will begin to show up as hosts (note that pod hosts are disabled by default so you will not see them):

image

Clone this wiki locally