Prometheus Operator: managing Prometheus through Kubernetes custom resources

What the Prometheus Operator solves on Kubernetes

Running Prometheus on Kubernetes without an operator means editing prometheus.yml by hand, restarting the process after every change, and keeping that file in step with pods that come and go. The Prometheus Operator removes that loop. It watches the Kubernetes API server for changes to its own custom resources and ensures the running Prometheus deployments match them, according to the README. Target discovery is the part that matters most in practice: instead of writing scrape_configs, you write label selectors, and the operator generates the scrape configuration from the current state of the API server. The README states that this means there is no need to learn a Prometheus specific configuration language for target configuration. The audience is platform and infrastructure teams running one or more Kubernetes clusters that already treat YAML in Git as the source of truth. If your Prometheus runs on a VM and scrapes static targets, the operator adds a Kubernetes dependency you do not need.

The CRDs the operator reconciles

The API surface is the product. Prometheus and PrometheusAgent define a desired Prometheus deployment, with the agent variant running in Agent mode. Alertmanager and ThanosRuler define the other two server components. ServiceMonitor, PodMonitor and Probe describe what to scrape, keyed on Kubernetes objects rather than host lists. ScrapeConfig exists for targets outside the cluster, which is the escape hatch when something is not a Service, Pod or Ingress. PrometheusRule holds alerting and recording rules, and the operator generates a rule file from it. AlertmanagerConfig carries subsections of the Alertmanager configuration, so routing to receivers and inhibit rules can be split across namespaces rather than living in one file. The operator detects changes to any of these objects and keeps matching deployments and configurations in sync. That control loop is the whole architecture: no sidecar agent per workload, no bespoke API, just Kubernetes objects and a reconciler watching them.

CRD stability is split across three API versions

This is the detail most introductions skip, and it should drive how you write manifests. The README marks monitoring.coreos.com/v1 as stable, with changes made in a backward-compatible way. The v1beta1 CRDs and API are called unstable, with the note that changes can happen but the team is focused on avoiding them; production use is encouraged for users who accept the risk of breaking changes. The v1alpha1 CRDs and API are also unstable, with the README stating that changes can happen frequently and suggesting they be avoided on mission-critical environments. In practice that means a manifest using a v1alpha1 resource such as ScrapeConfig or PrometheusAgent carries upgrade risk that a v1 Prometheus or ServiceMonitor does not. The operator itself is described as production ready. Those two statements are not in conflict, but they are easy to conflate: the controller is stable, the newer parts of its API are not.

Installing the Prometheus Operator and writing a first ServiceMonitor

The README points at the getting started guide for an introduction and warns that its own quickstart does not provision an entire monitoring stack. The repository ships bundle.yaml at the top level, alongside example/prometheus-operator-crd and example/rbac directories, which is where the CRDs and the operator's own permissions live. A first install therefore means applying the CRDs before anything that references them, which is what the top-level kustomization.yaml and bundle.yaml are there for. The Makefile also exposes an IMAGE_OPERATOR variable pointing at quay.io/prometheus-operator/prometheus-operator for the container image, and the Dockerfile's ENTRYPOINT is /bin/operator.

After the CRDs and operator are applied, the operator runs as a Deployment in the cluster and starts watching for the custom resources. The next step is a ServiceMonitor, the resource that most teams write first. The README describes it as declaratively specifying how groups of Kubernetes services should be monitored, with the operator generating the scrape configuration from the current state of the objects in the API server. A ServiceMonitor carries a selector over Services and a list of endpoints, and the Prometheus resource that should pick it up is chosen through its own selector. If nothing is scraped, that selector on the Prometheus resource is the first thing to check, because a ServiceMonitor that no Prometheus selects is inert. The README also notes that the operator requires at least Kubernetes version 1.16.0 and recommends the latest stable release.

The admission webhook and what it does not cover

Invalid alerting or recording rules can break a running Prometheus, so the project ships an admission webhook that validates PrometheusRule resources on creation or update, per the README. That is a genuine safeguard, and it is opt-in in the sense that it has to be deployed; the repository keeps its manifests under example/admission-webhook. The limitation is scope. The webhook validates PrometheusRule. It does not validate a ServiceMonitor whose selector matches nothing, a PodMonitor pointing at a port name that no container exposes, or an AlertmanagerConfig route that silently drops alerts. Those failures are quiet: the object is accepted, the operator reconciles it, and the effect is missing metrics or missing pages. Nothing in the README claims otherwise, but the presence of a validating webhook can create the impression that the API is typed end to end. It is not. Treat the webhook as protection against malformed rules, not as a correctness check on your monitoring design.

Prometheus Operator, kube-prometheus and the Helm chart

The README draws a line between three things that are often used interchangeably. The Prometheus Operator is the controller and the CRDs. kube-prometheus provides example configurations for a complete cluster monitoring stack built on the operator, including multiple Prometheus and Alertmanager instances, exporters such as node_exporter, scrape target configuration linking Prometheus to metrics endpoints, and example alerting rules. The prometheus-community/kube-prometheus-stack Helm chart offers a similar feature set to kube-prometheus and is maintained by the Prometheus community rather than by this project. The practical difference is who owns the YAML. Installing the operator alone leaves you writing every ServiceMonitor, rule and AlertmanagerConfig yourself, which is the right level of control if your monitoring is bespoke. kube-prometheus and the chart give you a working stack with defaults you then modify. Choosing the chart means your upgrade path runs through the chart's release cycle, and the README is explicit that the chart is maintained elsewhere.

Where the operator is the wrong tool

The clearest boundary is the one the README sets itself: the quickstart does not provision an entire monitoring stack, and the project expects you to reach for kube-prometheus or the chart if that is what you want. A second boundary is Kubernetes itself. The operator requires at least Kubernetes 1.16.0, and every mechanism it offers, from label-based target discovery to AlertmanagerConfig routing, assumes the objects being monitored live in the API server. Prometheus scraping a fleet of VMs, or a single Prometheus server managed by configuration management, gains nothing here and takes on a controller, CRDs and their upgrade cadence. A third is the unstable API surface. If your design depends on ScrapeConfig or PrometheusAgent, you are building on v1alpha1, which the README says can change frequently. That is a deliberate trade the project documents, not a defect, but it belongs in the decision rather than in a footnote discovered during an upgrade.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-21, the same day as the most recent activity in the release list. Releases arrive on a roughly monthly cadence: v0.94.0 on 2026-09-09, v0.93.1 on 2026-08-10, v0.93.0 on 2026-07-28. The version numbers are pre-1.0, and the CRD versioning scheme is how the project expresses stability rather than the release number. Upgrading means applying new CRDs before new controller images, and the v1beta1 and v1alpha1 resources are where breaking changes can land. The operator is Apache-2.0, and the Dockerfile labels the image with the same licence. Apache-2.0 permits commercial use and modification, and it includes a patent grant; it also requires that notices be preserved. The repository ships a NOTICE file alongside LICENSE, and the ADOPTERS.md and MAINTAINERS.md files describe who uses and who maintains the project. None of this is legal advice; if you redistribute the operator or a derivative, read LICENSE and NOTICE with your own counsel.

Editorial conclusion

Adopt the Prometheus Operator if you run Prometheus on Kubernetes and want targets, rules and Alertmanager routing expressed as custom resources that the operator keeps in sync. Do not adopt it for a single static Prometheus instance outside Kubernetes, or if you cannot accept the v1alpha1 CRD warning that changes can happen frequently. Before committing, check which CRD versions your manifests use, since monitoring.coreos.com/v1 is the only one the README calls stable, and confirm the admission webhook is deployed if you rely on PrometheusRule validation.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. prometheus-operator/prometheus-operator on GitHub
4. README
5. Releases