Kube-Prometheus-Stack Tutorial: Install to Your First Dashboard

This tutorial walks through kube-prometheus-stack end to end on a real (test) cluster — not just installing it, but actually monitoring something with it: deploying a sample app, scraping its metrics, building a dashboard panel, and wiring up an alert.

What You'll Build

By the end, you'll have kube-prometheus-stack running, a small sample application deployed and being scraped by Prometheus through a ServiceMonitor, a custom Grafana panel showing its metrics, and a PrometheusRule alerting if it goes down. You'll need a Kubernetes cluster (any of the ones covered in our distribution guide work) and Helm 3.

Step 1 — Install the Stack

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
kubectl create namespace monitoring
helm install monitoring prometheus-community/kube-prometheus-stack -n monitoring

Step 2 — Verify Everything Is Running

kubectl get pods -n monitoring

Wait until every pod shows Running. If something is stuck, the troubleshooting guide covers the most common causes.

Step 3 — Log Into Grafana

kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80
# Open http://localhost:3000 — default login admin / prom-operator

Change this default password before going anywhere near production — see the Grafana access guide for how.

Step 4 — Deploy a Sample App That Exposes Metrics

Any container exposing Prometheus-format metrics on /metrics works. A minimal example using a Deployment and Service:

kubectl create deployment demo-app --image=brancz/prometheus-example-app -n monitoring
kubectl expose deployment demo-app --port=8080 -n monitoring

Step 5 — Add a ServiceMonitor

This is the piece that tells Prometheus the new service exists. See our full ServiceMonitor guide for every field; the minimum needed here:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: demo-app
  namespace: monitoring
  labels:
    release: monitoring
spec:
  selector:
    matchLabels:
      app: demo-app
  endpoints:
    - port: 8080

The release: monitoring label matters — it's how Prometheus's default serviceMonitorSelector finds it (see our troubleshooting guide if it doesn't get picked up).

Step 6 — Build a Grafana Panel

In Grafana, create a new dashboard, add a panel, and set its query to the metric the sample app exposes (http_requests_total for the example app above) with the Prometheus datasource. Within a minute or two of the ServiceMonitor being picked up, the graph should start showing live data.

Step 7 — Add an Alert Rule

Finally, wire up an alert if the app goes down, using a PrometheusRule:

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: demo-app-alerts
  namespace: monitoring
  labels:
    release: monitoring
spec:
  groups:
    - name: demo-app
      rules:
        - alert: DemoAppDown
          expr: up{job="demo-app"} == 0
          for: 2m

Set up where this actually notifies using the Alertmanager configuration guide.

Frequently Asked Questions

How long does this tutorial take?

About 20-30 minutes, most of it waiting for pods to become Ready rather than active work.

Do I need my own app?

No — the tutorial uses a small sample app that already exposes Prometheus metrics.

What's next after this?

Point a ServiceMonitor at your real application, then move on to production concerns like storage and resource limits.

Conclusion

That's the full loop: install, deploy something real, scrape it, visualize it, and alert on it. Everything else on this site — values.yaml tuning, Thanos for long-term storage, GitOps deployment — builds on exactly this same ServiceMonitor-and-PrometheusRule pattern at production scale.