[opensourcedex]

prometheus-operator is a free, open source monitoring & observability project written in Go and released under Apache-2.0. It has 9,976 GitHub stars, 3,878 forks and 296 open issues, and was last pushed 7 hours ago. On this registry it ranks #47 of 191 tracked projects in Monitoring & Observability, with 5 head-to-head comparisons available.

What is prometheus-operator?

Prometheus Operator is an Apache-2.0 licensed, Go-based controller that provides Kubernetes-native deployment and management of Prometheus and its related monitoring components, and it is built for platform and infrastructure engineers who operate a Prometheus monitoring stack on Kubernetes clusters.

What it is

The project lives in the Kubernetes ecosystem and supplies a set of Kubernetes custom resources that describe Prometheus, Alertmanager, and related monitoring components. The operator watches the Kubernetes API server for changes to those objects and ensures the components running in the cluster match the declared state. In practice it acts as the control plane for a cluster's monitoring stack, so the pieces that make up that stack are created, configured, and kept in sync by Kubernetes rather than by a separate deployment process.

The concrete problem it solves is Prometheus configuration and lifecycle management. Without it, an operator writes Prometheus configuration files and manages Prometheus and Alertmanager deployments by hand. The Prometheus Operator replaces that with Kubernetes resources and Kubernetes label queries, so monitoring targets are generated automatically and there is no need to learn a Prometheus-specific configuration language. The fundamentals of a deployment — Prometheus versions, persistence, retention policies, and replicas — are declared from a native Kubernetes resource.

Key capabilities

  • Deploys and manages Prometheus, Alertmanager, and related monitoring components through Kubernetes custom resources.
  • Configures Prometheus versions, persistence, retention policies, and replicas directly from a native Kubernetes resource.
  • Generates Prometheus target configurations automatically from Kubernetes label queries.
  • Reconciles state by monitoring the Kubernetes API server for changes to specific objects.
  • Ships versioned APIs under the monitoring.coreos.com group: v1 is stable and changed in a backward-compatible way, v1beta1 is unstable, and v1alpha1 is unstable and may change frequently.
  • Publishes release container images to the quay.io/prometheus-operator/prometheus-operator repository.
  • Exposes a Go library at github.com/prometheus-operator/prometheus-operator, documented on pkg.go.dev, and runs a #prometheus-operator channel on the Kubernetes Slack.

Who uses it and how

  • Platform teams that need Prometheus on Kubernetes use it as the base layer, with kube-prometheus supplying example configurations for a complete cluster monitoring stack: multiple Prometheus and Alertmanager instances, metrics exporters such as the node_exporter, scrape target configuration linking Prometheus to metrics endpoints, and example alerting rules.
  • Teams that prefer a packaged install run the prometheus-community/kube-prometheus-stack Helm chart, which offers a similar feature set and is maintained by the Prometheus community, with the operator underneath.
  • Operators on v1beta1 APIs can deploy in production if they accept the risk of breaking changes; v1alpha1 usage is advised against in mission-critical environments.
  • Any deployment requires Kubernetes version 1.16.0 or later, and the project recommends running the latest stable release.

Getting started

The README directs new users to the getting started guide at Documentation/developer/getting-started.md and to the latest stable release, whose container images are published in the quay.io/prometheus-operator/prometheus-operator repository.

How it compares

Prometheus Operator is the lower-level component; kube-prometheus builds on it to provide example configurations for an entire cluster monitoring stack, and the prometheus-community/kube-prometheus-stack Helm chart provides a similar feature set for users who want a chart-driven install. The README treats the three as complementary layers of the same stack rather than as competing products.

When to use it — and when not to

Choose it when monitoring runs on Kubernetes and the goal is to declare Prometheus, Alertmanager, and targets as custom resources instead of maintaining configuration files by hand. Do not choose it if the infrastructure is not Kubernetes, or if the cluster cannot be kept at version 1.16.0 or later, since the operator requires that minimum. Be aware that v1beta1 and v1alpha1 custom resources are explicitly unstable, so a deployment leaning on those APIs takes on breaking-change risk, and the repository currently carries a substantial open-issue backlog.

project readme (upstream, from github) — read inline

Prometheus Operator

Build Status Go Reference Latest Release Slack

Overview

The Prometheus Operator provides Kubernetes native deployment and management of Prometheus and related monitoring components. The purpose of this project is to simplify and automate the configuration of a Prometheus based monitoring stack for Kubernetes clusters.

The Prometheus operator includes, but is not limited to, the following features:

  • Kubernetes Custom Resources: Use Kubernetes custom resources to deploy and manage Prometheus, Alertmanager, and related components.

  • Simplified Deployment Configuration: Configure the fundamentals of Prometheus like versions, persistence, retention policies, and replicas from a native Kubernetes resource.

  • Prometheus Target Configuration: Automatically generate monitoring target configurations based on familiar Kubernetes label queries; no need to learn a Prometheus specific configuration language.

For an introduction to the Prometheus Operator, see the getting started guide.

Project Status

The operator in itself is considered to be production ready. Please refer to the Custom Resource Definition (CRD) versions for the status of each CRD:

  • monitoring.coreos.com/v1: stable CRDs and API, changes are made in a backward-compatible way.
  • monitoring.coreos.com/v1beta1: unstable CRDs and API, changes can happen but the team is focused on avoiding them. We encourage usage in production for users that accept the risk of breaking changes.
  • monitoring.coreos.com/v1alpha1: unstable CRDs and API, changes can happen frequently, and we suggest avoiding its usage on mission-critical environments.

Prometheus Operator vs. kube-prometheus vs. community Helm chart

Prometheus Operator

The Prometheus Operator uses Kubernetes custom resources to simplify the deployment and configuration of Prometheus, Alertmanager, and related monitoring components.

kube-prometheus

kube-prometheus provides example configurations for a complete cluster monitoring stack based on Prometheus and the Prometheus Operator. This includes deployment of multiple Prometheus and Alertmanager instances, metrics exporters such as the node_exporter for gathering node metrics, scrape target configuration linking Prometheus to various metrics endpoints, and example alerting rules for notification of potential issues in the cluster.

Helm chart

The prometheus-community/kube-prometheus-stack Helm chart provides a similar feature set to kube-prometheus. This chart is maintained by the Prometheus community. For more information, please see the chart's readme

Prerequisites

The Prometheus Operator requires at least Kubernetes version 1.16.0. If you are just starting out with the Prometheus Operator, it is highly recommended to use the latest stable release.

CustomResourceDefinitions

A core feature of the Prometheus Operator is to monitor the Kubernetes API server for changes to specific objects and ensure that the current Prometheus deployments match these objects. The Operator acts on the following Custom Resource Definitions (CRDs):

  • Prometheus, which defines a desired Prometheus deployment.

  • PrometheusAgent, which defines a desired Prometheus deployment, but running in Agent mode.

  • Alertmanager, which defines a desired Alertmanager deployment.

  • ThanosRuler, which defines a desired Thanos Ruler deployment.

  • ServiceMonitor, which declaratively specifies how groups of Kubernetes services should be monitored. The Operator automatically generates Prometheus scrape configuration based on the current state of the objects in the API server.

  • PodMonitor, which declaratively specifies how group of pods should be monitored. The Operator automatically generates Prometheus scrape configuration based on the current state of the objects in the API server.

  • Probe, which declaratively specifies how groups of ingresses or static targets should be monitored. The Operator automatically generates Prometheus scrape configuration based on the definition.

  • ScrapeConfig, which declaratively specifies scrape configurations to be added to Prometheus. This CustomResourceDefinition helps with scraping resources outside the Kubernetes cluster.

  • PrometheusRule, which defines a desired set of Prometheus alerting and/or recording rules. The Operator generates a rule file, which can be used by Prometheus instances.

  • AlertmanagerConfig, which declaratively specifies subsections of the Alertmanager configuration, allowing routing of alerts to custom receivers, and setting inhibit rules.

The Prometheus operator automatically detects changes in the Kubernetes API server to any of the above objects, and ensures that matching deployments and configurations are kept in sync.

To learn more about the CRDs introduced by the Prometheus Operator have a look at the design page.

Dynamic Admission Control

To prevent invalid Prometheus alerting and recording rules from causing failures in a deployed Prometheus instance, an admission webhook is provided to validate PrometheusRule resources upon initial creation or update.

For more information on this feature, see the user guide.

Quickstart

Note: this quickstart does not provision an entire monitoring stack; if that is what you are looking for, see the kube-prometheus project. If you want the whole stack, but have already applied the bundle.yaml, delete the bundle first (kubectl delete -f bundle.yaml).

To quickly try out just the Prometheus Operator inside a cluster, choose a release and run the following command which deploys the operator in the default namespace:

kubectl create -f bundle.yaml

If you want to deploy the Prometheus operator in a different namespace, you also need kustomize:

NAMESPACE=my_namespace kustomize edit set namespace $NAMESPACE && kubectl create -k .

Note: make sure to adapt the namespace in the ClusterRoleBinding if deploying in a namespace other than the default namespace.

To run the Operator outside of a cluster:

make
scripts/run-external.sh <kubectl cluster name>

Removal

To remove the operator and Prometheus, first delete any custom resources you created in each namespace. The operator will automatically shut down and remove Prometheus and Alertmanager pods, and associated ConfigMaps.

for n in $(kubectl get namespaces -o jsonpath={..metadata.name}); do
  kubectl delete --all --namespace=$n prometheus,servicemonitor,podmonitor,alertmanager
done

After a couple of minutes you can go ahead and remove the operator itself.

kubectl delete -f bundle.yaml

The operator automatically creates services in each namespace where you created a Prometheus or Alertmanager resources, and defines three custom resource definitions. You can clean these up now.

for n in $(kubectl get namespaces -o jsonpath={..metadata.name}); do
  kubectl delete --ignore-not-found --namespace=$n service prometheus-operated alertmanager-operated
done

kubectl delete --ignore-not-found customresourcedefinitions \
  prometheuses.monitoring.coreos.com \
  servicemonitors.monitoring.coreos.com \
  podmonitors.monitoring.coreos.com \
  alertmanagers.monitoring.coreos.com \
  prometheusrules.monitoring.coreos.com \
  alertmanagerconfigs.monitoring.coreo

readme truncated — read the full docs on github

Frequently asked questions

Is prometheus-operator free to use?

prometheus-operator is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does prometheus-operator do?

Prometheus Operator creates/configures/manages Prometheus clusters atop Kubernetes

What is prometheus-operator written in?

prometheus-operator is primarily written in Go. Its source is publicly available at https://github.com/prometheus-operator/prometheus-operator, and it has 9,976 GitHub stars.