Prometheus

Installation

There are a number of ways to install Prometheus, including:

via Helm
via kubeyaml
in split mode

The best option depends on how the rest of the infrastructure is installed. By far the simplest way, which the Platformatic team uses in @platformatic/desk, is to install the kube-prometheus-stack and prometheus-adapter through their Helm charts. This will cover all the requirements for ICC as well as leave open the possibility of having seperate storage in the future.

Requirements

The following CRDs are used to track the state of Platformatic and watt applications.

PodMonitor
ServiceMonitor

The kube-state-metrics agent is also required for accessing pod and deployment metadata.

CRDs

First, validate that the current installation has the required CRDs. With access via kubectl, the command and output should look something like this:

> kubectl get crds | grep '.monitors.monitoring.coreos.com'
podmonitors.monitoring.coreos.com           2025-09-30T23:39:21Z
servicemonitors.monitoring.coreos.com       2025-09-30T23:39:21Z

If the monitors are available, move on to agent configuration.

The promethes-operator-crds Helm chart includes all the CRDs for Prometheus Operator and is the easiest way to install the required CRDs, if Prometheus is already installed.

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm install prom-op-crds prometheus-community/prometheus-operator-crds

To avoid installing all CRDs, use this values file with the chart:

crds:
  servicemonitors:
    enabled: true
  podmonitors:
    enabled: true

  alertmanagerconfigs:
    enabled: false
  alertmanagers:
    enabled: false
  probes:
    enabled: false
  prometheusagents:
    enabled: false
  prometheuses:
    enabled: false
  prometheusrules:
    enabled: false
  scrapeconfigs:
    enabled: false
  thanosrulers:
    enabled: false

It can be applied like this:

helm install prom-op-crds prometheus-community/prometheus-operator-crds --values prom-op-crds.yaml

Alternatively, the CRDs may be installed when using other installation methods. For example, when using kube-prometheus-stack, make sure crds.enable is set to true for the ServiceMonitor and PodMonitor CRDs to be installed.

Agent configuration

The following labels are used by Platformatic for accurate scaling and monitoring of watt applications. These need to be added to the allow list of the kube-state-metrics agent configuration.

platformatic.dev/application-id
platformatic.dev/deployment-id
platformatic.dev/monitor
platformatic.dev/scale-min
platformatic.dev/scale-max

These labels can be added during Helm installation:

# When using `kube-prometheus-stack` chart
kube-state-metrics:
  extraArgs:
    - --metric-labels-allowlist=pods=["platformatic.dev/application-id","platformatic.dev/deployment-id","platformatic.dev/monitor","platformatic.dev/scale-min","platformatic.dev/scale-max"]

# When using `kube-state-metrics` chart
metricLabelsAllowlist:
  - pods=[platformatic.dev/application-id,platformatic.dev/deployment-id,platformatic.dev/monitor,platformatic.dev/scale-min,platformatic.dev/scale-max]

or to the CLI arguments of the agent:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG
        name: kube-state-metrics
        args:
        - --metric-labels-allowlist=pods=["platformatic.dev/application-id","platformatic.dev/deployment-id","platformatic.dev/monitor","platformatic.dev/scale-min","platformatic.dev/scale-max"]

AWS Managed Prometheus

A scalable Prometheus system may seperate the storage and querying of metrics from the scraping.

If AMP is not already configured, use one of the following methods to create a workspace:

With a configured workspace, metrics ingestion will need to be configured next. AWS documentation includes the most up to date configuration steps. If Prometheus server and kube-state-metrics agent have already been installed, the following changes will need to be made:

updating the remoteWrite settings of the Prometheus server
adding an IAM role
attaching the role to a service account

All of these steps are found in the AWS documentation for metrics ingestion.