Skip to content
kix docs

Install the monitoring stack

Use kix.modules.monitoring to install the native Kix monitoring stack. The module configures Prometheus Operator, Prometheus, Alertmanager, Grafana, node-exporter, and kube-state-metrics as related package instances.

The module needs the cluster’s package catalogue. By default, buildCluster passes modules only ref and a minimal kix value. The cluster must forward the full values with specialArgs = { inherit kix packages; };, which is the first line of the snippet below. Without it the module fails to resolve the packages it instantiates.

Add the monitoring module

Section titled “Add the monitoring module”

Import the module and enable the stack in a cluster module:

how-to/package-stacks/monitoring-cluster.nix (L13–L36)
  # `kix.modules.monitoring` reads the package catalogue, which buildCluster
  # does not pass to modules on its own. specialArgs forwards it.
  specialArgs = { inherit kix packages; };


  modules = [
    kix.flavors.kind
    {
      imports = [ kix.modules.monitoring ];


      monitoring = {
        enabled = true;
        prometheus = {
          retention = "7d";
          scrapeInterval = "30s";
        };


        # Keep the local example independent of persistent storage.
        grafana.persistence.enabled = false;


        # Add the standard Kubernetes alerts, recording rules, and monitors.
        defaultRules.enabled = true;
      };
    }
  ];

View source on GitHub ↗

The example keeps Grafana storage ephemeral so it can run on a fresh local cluster. For a long-lived cluster, set the whole persistence attrset:

cluster.nix
monitoring.grafana.persistence = {
  enabled = true;
  size = "20Gi";
};

persistence is a single unstructured option, not a submodule. Defining one field replaces the complete default value rather than merging with it. Setting only monitoring.grafana.persistence.size = "20Gi" therefore removes enabled, and evaluation fails with attribute 'enabled' missing. The example can set only enabled = false because the module does not read size when persistence is disabled.

Package config options behave differently: Kix merges their defaults into the evaluated result, so partial values retain the remaining defaults. This cluster module option uses the standard module system and must be defined in full.

defaultRules.enabled adds the standard Kubernetes alert rules, recording rules, and ServiceMonitors. Disable it when you want to install the core stack first and add cluster-specific rules separately.

Before deploying, adjust these settings for the cluster:

  • monitoring.prometheus.retention and retentionSize bound stored metrics.
  • monitoring.prometheus.resources sets Prometheus CPU and memory requests and limits.
  • monitoring.prometheus.storage configures persistent Prometheus storage.
  • monitoring.grafana.replicas controls Grafana replicas. Keep one replica when its volume only supports ReadWriteOnce.
  • monitoring.nodeExporter.enabled controls the node-exporter DaemonSet.

Check the stack

Section titled “Check the stack”

Evaluate all monitoring resources:

Run in kix-examples/ 
❱ kix check how-to-package-monitoring
 TOOL         RESULT  DETAILS                                                       
 eval         pass    108 manifests evaluated                                       
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 24 warnings, 9 info

List the package instances selected by the module:

Run in kix-examples/ 
❱ kix list packages --cluster how-to-package-monitoring
 NAME                 VERSION  OWNER     STATUS                        
 alertmanager         v0.33.1  platform  installed [monitoring-system] 
 default-rules        84.5.0   platform  installed [monitoring-system] 
 grafana              13.1.1   platform  installed [monitoring-system] 
 kube-state-metrics   v2.19.1  platform  installed [monitoring-system] 
 node-exporter        v1.12.1  platform  installed [monitoring-system] 
 platform-dns         -        -         import [kube-system]          
 platform-storage     -        -         import [kube-system]          
 prometheus-operator  v0.92.1  platform  installed [monitoring-system] 
 prometheus-server    v3.13.1  platform  installed [monitoring-system]

The list includes the operator and the components it manages. The flavor’s DNS and storage entries are imports supplied by the target platform.

Deploy and inspect

Section titled “Deploy and inspect”

Deploy the cluster, then check readiness:

Run in kix-examples/ 
❱ kix deploy how-to-package-monitoring
❱ kix status how-to-package-monitoring

On a small local cluster, Prometheus and Grafana can take several minutes to become ready while their images are pulled.

To open Grafana locally, forward its port:

Run in kix-examples/ 
❱ kix pf how-to-package-monitoring grafana 3000:3000

Open http://127.0.0.1:3000 while the forward is running. Stop it with Ctrl-C.

If a component remains pending, use kix status to find its workload, then check node capacity, PVC provisioning, and any pod security restrictions on the target cluster.