Prometheus Community Helm Chart
This guide walks you through the steps required to monitor the performance and
overall health of your Materialize instance using the prometheus-community/prometheus
helm chart.
Before you begin
Ensure you have:
- A self-managed instance of Materialize installed with helm values
observability.enabled=true
,observability.podMetrics.enabled=true
, andprometheus.scrapeAnnotations.enabled=true
- Helm version 3.2.0+ installed
- kubectl installed and configured
! Important: This guide assumes you have administrative access to your Kubernetes cluster and the necessary permissions to install Prometheus.
1. Install Prometheus to your Kubernetes cluster using prometheus-community/prometheus
-
Download the Materialize Prometheus scrape configuration file:
curl -O https://raw.githubusercontent.com/MaterializeInc/materialize/refs/heads/self-managed-docs/v25.2/doc/user/data/self_managed/prometheus.yml
-
Download the prometheus-community default chart values:
curl -O https://raw.githubusercontent.com/prometheus-community/helm-charts/refs/heads/main/charts/prometheus/values.yaml
-
Replace
values.yaml
’sserverFiles > prometheus.yml > scrape_configs
withprometheus.yml
’sscrape_configs
. It should look something like:serverFiles: prometheus.yml: scrape_configs: - job_name: kubernetes-pods ...
-
Create a
prometheus
namespacekubectl create namespace prometheus
-
Install the operator with the scrape configuration
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts helm repo update helm install --namespace prometheus prometheus prometheus-community/prometheus \ --values values.yaml
2. Validate through the Prometheus UI
NOTE: The port forwarding method described below is for testing purposes only. For production environments, configure an ingress controller to securely expose the Prometheus UI.
-
Set up port forwarding to access the Prometheus UI:
MZ_POD_PROMETHEUS=$(kubectl get pods -n prometheus -l app.kubernetes.io/name=prometheus -o custom-columns="NAME:.metadata.name" --no-headers) kubectl port-forward pod/$MZ_POD_PROMETHEUS 9090:9090 -n prometheus
-
Access the Prometheus UI by navigating to
localhost:9090
in your web browser.