Release Compatibility#
This shows the compatibility of materialize-monitoring with various technologies.
It is also where changes we absorb from outside this repo are recorded — a Materialize metric rename, a Grafana schema bump, an upstream chart moving a value. For what we guarantee about our own names, and the notice you get before one changes, see Stability Guarantees and Deprecation Policy.
materialize-terraform-self-managed#
| materialize-terraform-self-managed | materialize-monitoring | Clouds | Observability default |
|---|---|---|---|
| v11.0.0+ | 0.17.0 | AWS, GCP, Azure | On — enable_observability defaults to true |
| v10.0.0 – v10.1.1 | 0.12.0 – 0.15.0 | AWS, GCP, Azure | Off — opt-in |
| ≤ v9.0.2 | none (a vendored copy of the env-top dashboard only) | — | — |
The Terraform module ships inside the materialize-monitoring component rather than on a version stream of its own, so one number covers both: a module ref of materialize-monitoring/vX.Y.Z installs chart X.Y.Z. There is no mapping to maintain between the two.
v11 made the monitoring stack opt-out rather than opt-in and completed the per-cloud rollout, so Azure no longer uses the previous Prometheus + Grafana modules.
Kubernetes#
We support the non-EOL Kubernetes releases — v1.34 and newer.
The charts declare kubeVersion: ">=1.27.0-0", but that is a floor rather than a support statement: older releases may work and are not supported.
Cloud-provided distributions offering extended support past a release’s upstream EOL are supported on a best-effort basis, and may run into issues.
Materialize product#
Dashboards (v0.8.0+) generally require the mz_object_info metric introduced in v26.29.0,
however they will gracefully degrade without it.
The env-upgrade dashboard requires v26.41.0 for its operator signals: the reconciliation metrics
(orchestratord_reconciliations_total and friends) and the Kubernetes events the operator publishes for reconciliation
failures and Materialize lifecycle transitions.
It degrades rather than breaking on an older release, and not uniformly — the floor is narrower than the dashboard:
| Tab | On a release older than v26.41.0 |
|---|---|
| Generations | Fully working. Every panel reads metrics that predate it, and the blue/green split comes from pod names rather than anything the operator newly exports. |
| Events | The Kubernetes Activity row works — those events come from the kubelet and the scheduler. The Rollout and Operator Health rows are empty. |
| Reconciliation | Empty, apart from Reconciling Replicas and Environments Needing Update, whose gauges predate the rest. |
The env-ingress dashboard, Materialize Ingress (Balancer, Console), reads the console’s request metrics, which
Materialize publishes from v26.49.0, and balancerd’s connection timings and server-side error count, which it
publishes from v26.50.0.
On versions without them, it degrades by tab:
| Tab | On a Materialize version without them |
|---|---|
| Overview | Open Connections works, and so do the balancerd rate and error panels. Their error count includes clients that hung up, and leaves out connections balancerd refused. The latency, Taking New Connections, and console panels are empty. |
| Load Balancer | Unaffected. Its provider rows depend on the gateway pulling the load balancer’s metrics, not on Materialize. |
| Balancer | Connections, the connection limit, resources, autoscaling, and logs work. The watermarks, Taking New Connections by Pod, and Connection Timing are empty on versions that also predate balancerd’s watermarks. |
| Console | Only the logs row works. |
| SQL and HTTP API | Fully working. Every panel reads environmentd. |
The Balancer tab’s Autoscaling row draws any HorizontalPodAutoscaler that targets balancerd’s Deployment.
For the autoscaler to keep the count it sets, the Materialize resource needs balancerdExternallyScaled: true, which
Materialize supports from v26.48.0.
Earlier versions reset balancerd’s replica count to balancerdReplicas.
Each dashboard also carries its floor as a monitoring.materialize.cloud/min-mz-version annotation, which the docsite’s
dashboard table shows.
Scrapers (v0.1.1+) require the app.kubernetes.io/name label that Materialize sets on environmentd pods from v26.24.0.
The balancerd and console monitors (v0.6.0+) select on the same label, which Materialize sets on those pods from the
same version.
The console monitor scrapes the console pod’s internal-http port, which the Materialize operator declares from
v26.49.0, the same version that publishes the console’s metrics.
What you see depends on which of the two you have upgraded:
| Operator | Console image | What the console monitor does |
|---|---|---|
| Without the port | Any | Finds no target. Nothing fails, and the Console tab stays empty. |
| With the port | Without the metrics | Scrapes a port that refuses connections, so up reads 0 for each console pod. |
| With the port | With the metrics | Collects mz_console_*. |
The operator picks the console image from the environment’s Materialize version.
Upgrading the operator before an environment therefore leaves that environment’s console pods in the second row until
you upgrade the environment too.
To skip the failed scrapes for that window, set materialize.console.serviceMonitor.enabled to false.
Grafana#
Dashboards (v0.8.0+) require Grafana v13+ for the dashboard schema v2. Grafana v12 is generally known to work, but may run into issues.
Google Kubernetes Engine (GKE)#
GKE works generally with the dashboards. Managed collection (enabling it) is on by default from v1.27 and provides the PodMonitoring CRDs the GMP scrapers use.
Container metrics no longer depend on what GMP exposes.
The Alloy gateway scrapes /metrics/cadvisor on every kubelet itself, which yields a fuller set than GMP’s default
collection.
That is what retired the GCP-specific dashboard variants: there is now one render per dashboard, carrying the same
container_* and kube_* families and percentage-based panels everywhere.
See Container metrics from the kubelet.
Google Cloud Monitoring Dashboards#
Importing Grafana dashboards into Google Cloud Monitoring is not yet fully supported.
The shipped dashboards do have some improvements but there are still some known issues:
$__rangeand$__rate_intervalneed to be replaced with constants- Horizontal bar charts are not rendered
- Tabs and rows are not supported, so there is no layout
- Switch variables are not supported (e.g. “show system clusters”)
- This breaks the downstream cluster selector variable