Skip to content

Latest commit

 

History

History
345 lines (257 loc) · 23.8 KB

api.md

File metadata and controls

345 lines (257 loc) · 23.8 KB
Raw

Note: Starting with v0.12.0, Prometheus Operator requires use of Kubernetes v1.7.x and up.

API Docs

This Document documents the types introduced by the Prometheus Operator to be consumed by users.

Note this document is generated from code comments. When contributing a change to this document please do so by changing the code comments.

Table of Contents

AlertingSpec

AlertingSpec defines parameters for alerting configuration of Prometheus servers.

Field Description Scheme Required
alertmanagers AlertmanagerEndpoints Prometheus should fire alerts against. []AlertmanagerEndpoints true

Back to TOC

Alertmanager

Describes an Alertmanager cluster.

Field Description Scheme Required
metadata Standard object’s metadata. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata metav1.ObjectMeta false
spec Specification of the desired behavior of the Alertmanager cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status AlertmanagerSpec true
status Most recent observed status of the Alertmanager cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status *AlertmanagerStatus false

Back to TOC

AlertmanagerEndpoints

AlertmanagerEndpoints defines a selection of a single Endpoints object containing alertmanager IPs to fire alerts against.

Field Description Scheme Required
namespace Namespace of Endpoints object. string true
name Name of Endpoints object in Namespace. string true
port Port the Alertmanager API is exposed on. intstr.IntOrString true
scheme Scheme to use when firing alerts. string false
pathPrefix Prefix for the HTTP path alerts are pushed to. string false

Back to TOC

AlertmanagerList

A list of Alertmanagers.

Field Description Scheme Required
metadata Standard list metadata More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata metav1.ListMeta false
items List of Alertmanagers []Alertmanager true

Back to TOC

AlertmanagerSpec

Specification of the desired behavior of the Alertmanager cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status

Field Description Scheme Required
podMetadata Standard object’s metadata. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata Metadata Labels and Annotations gets propagated to the prometheus pods. *metav1.ObjectMeta false
version Version the cluster should be on. string false
baseImage Base image that is used to deploy pods. string false
imagePullSecrets An optional list of references to secrets in the same namespace to use for pulling prometheus and alertmanager images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod []v1.LocalObjectReference false
replicas Size is the expected size of the alertmanager cluster. The controller will eventually make the size of the running cluster equal to the expected size. *int32 false
storage Storage is the definition of how storage will be used by the Alertmanager instances. *StorageSpec false
externalUrl The external URL the Alertmanager instances will be available under. This is necessary to generate correct URLs. This is necessary if Alertmanager is not served from root of a DNS name. string false
routePrefix The route prefix Alertmanager registers HTTP handlers for. This is useful, if using ExternalURL and a proxy is rewriting HTTP routes of a request, and the actual ExternalURL is still true, but the server serves requests under a different route prefix. For example for use with kubectl proxy. string false
paused If set to true all actions on the underlaying managed objects are not goint to be performed, except for delete actions. bool false
nodeSelector Define which Nodes the Pods are scheduled on. map[string]string false
resources Define resources requests and limits for single Pods. v1.ResourceRequirements false
affinity If specified, the pod's scheduling constraints. *v1.Affinity false
tolerations If specified, the pod's tolerations. []v1.Toleration false
securityContext SecurityContext holds pod-level security attributes and common container settings. This defaults to non root user with uid 1000 and gid 2000. *v1.PodSecurityContext false
serviceAccountName ServiceAccountName is the name of the ServiceAccount to use to run the Prometheus Pods. string false

Back to TOC

AlertmanagerStatus

Most recent observed status of the Alertmanager cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status

Field Description Scheme Required
paused Represents whether any actions on the underlaying managed objects are being performed. Only delete actions will be performed. bool true
replicas Total number of non-terminated pods targeted by this Alertmanager cluster (their labels match the selector). int32 true
updatedReplicas Total number of non-terminated pods targeted by this Alertmanager cluster that have the desired version spec. int32 true
availableReplicas Total number of available pods (ready for at least minReadySeconds) targeted by this Alertmanager cluster. int32 true
unavailableReplicas Total number of unavailable pods targeted by this Alertmanager cluster. int32 true

Back to TOC

BasicAuth

BasicAuth allow an endpoint to authenticate over basic authentication More info: https://prometheus.io/docs/operating/configuration/#endpoints

Field Description Scheme Required
username The secret that contains the username for authenticate v1.SecretKeySelector false
password The secret that contains the password for authenticate v1.SecretKeySelector false

Back to TOC

Endpoint

Endpoint defines a scrapeable endpoint serving Prometheus metrics.

Field Description Scheme Required
port Name of the service port this endpoint refers to. Mutually exclusive with targetPort. string false
targetPort Name or number of the target port of the endpoint. Mutually exclusive with port. intstr.IntOrString false
path HTTP path to scrape for metrics. string false
scheme HTTP scheme to use for scraping. string false
params Optional HTTP URL parameters map[string][]string false
interval Interval at which metrics should be scraped string false
scrapeTimeout Timeout after which the scrape is ended string false
tlsConfig TLS configuration to use when scraping the endpoint *TLSConfig false
bearerTokenFile File to read bearer token for scraping targets. string false
honorLabels HonorLabels chooses the metric's labels on collisions with target labels. bool false
basicAuth BasicAuth allow an endpoint to authenticate over basic authentication More info: https://prometheus.io/docs/operating/configuration/#endpoints *BasicAuth false
metricRelabelings MetricRelabelConfigs to apply to samples before ingestion. []*RelabelConfig false

Back to TOC

NamespaceSelector

A selector for selecting namespaces either selecting all namespaces or a list of namespaces.

Field Description Scheme Required
any Boolean describing whether all namespaces are selected in contrast to a list restricting them. bool false
matchNames List of namespace names. []string false

Back to TOC

Prometheus

Prometheus defines a Prometheus deployment.

Field Description Scheme Required
metadata Standard object’s metadata. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata metav1.ObjectMeta false
spec Specification of the desired behavior of the Prometheus cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status PrometheusSpec true
status Most recent observed status of the Prometheus cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status *PrometheusStatus false

Back to TOC

PrometheusList

PrometheusList is a list of Prometheuses.

Field Description Scheme Required
metadata Standard list metadata More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata metav1.ListMeta false
items List of Prometheuses []*Prometheus true

Back to TOC

PrometheusSpec

Specification of the desired behavior of the Prometheus cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status

Field Description Scheme Required
podMetadata Standard object’s metadata. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata Metadata Labels and Annotations gets propagated to the prometheus pods. *metav1.ObjectMeta false
serviceMonitorSelector ServiceMonitors to be selected for target discovery. *metav1.LabelSelector false
version Version of Prometheus to be deployed. string false
paused When a Prometheus deployment is paused, no actions except for deletion will be performed on the underlying objects. bool false
baseImage Base image to use for a Prometheus deployment. string false
imagePullSecrets An optional list of references to secrets in the same namespace to use for pulling prometheus and alertmanager images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod []v1.LocalObjectReference false
replicas Number of instances to deploy for a Prometheus deployment. *int32 false
retention Time duration Prometheus shall retain data for. string false
logLevel Log level for Prometheus be configured in. string false
scrapeInterval Interval between consecutive scrapes. string false
evaluationInterval Interval between consecutive evaluations. string false
externalLabels The labels to add to any time series or alerts when communicating with external systems (federation, remote storage, Alertmanager). map[string]string false
externalUrl The external URL the Prometheus instances will be available under. This is necessary to generate correct URLs. This is necessary if Prometheus is not served from root of a DNS name. string false
routePrefix The route prefix Prometheus registers HTTP handlers for. This is useful, if using ExternalURL and a proxy is rewriting HTTP routes of a request, and the actual ExternalURL is still true, but the server serves requests under a different route prefix. For example for use with kubectl proxy. string false
storage Storage spec to specify how storage shall be used. *StorageSpec false
ruleSelector A selector to select which ConfigMaps to mount for loading rule files from. *metav1.LabelSelector false
alerting Define details regarding alerting. AlertingSpec false
resources Define resources requests and limits for single Pods. v1.ResourceRequirements false
nodeSelector Define which Nodes the Pods are scheduled on. map[string]string false
serviceAccountName ServiceAccountName is the name of the ServiceAccount to use to run the Prometheus Pods. string false
secrets Secrets is a list of Secrets in the same namespace as the Prometheus object, which shall be mounted into the Prometheus Pods. The Secrets are mounted into /etc/prometheus/secrets/. Secrets changes after initial creation of a Prometheus object are not reflected in the running Pods. To change the secrets mounted into the Prometheus Pods, the object must be deleted and recreated with the new list of secrets. []string false
affinity If specified, the pod's scheduling constraints. *v1.Affinity false
tolerations If specified, the pod's tolerations. []v1.Toleration false
remoteWrite If specified, the remote_write spec. This is an experimental feature, it may change in any upcoming release in a breaking way. []RemoteWriteSpec false
remoteRead If specified, the remote_read spec. This is an experimental feature, it may change in any upcoming release in a breaking way. []RemoteReadSpec false
securityContext SecurityContext holds pod-level security attributes and common container settings. This defaults to non root user with uid 1000 and gid 2000 for Prometheus >v2.0 and default PodSecurityContext for other versions. *v1.PodSecurityContext false

Back to TOC

PrometheusStatus

Most recent observed status of the Prometheus cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#spec-and-status

Field Description Scheme Required
paused Represents whether any actions on the underlaying managed objects are being performed. Only delete actions will be performed. bool true
replicas Total number of non-terminated pods targeted by this Prometheus deployment (their labels match the selector). int32 true
updatedReplicas Total number of non-terminated pods targeted by this Prometheus deployment that have the desired version spec. int32 true
availableReplicas Total number of available pods (ready for at least minReadySeconds) targeted by this Prometheus deployment. int32 true
unavailableReplicas Total number of unavailable pods targeted by this Prometheus deployment. int32 true

Back to TOC

RelabelConfig

RelabelConfig allows dynamic rewriting of the label set.

Field Description Scheme Required
sourceLabels The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. []string true
separator Separator placed between concatenated source label values. default is ';'. string false
targetLabel Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. string false
regex Regular expression against which the extracted value is matched. defailt is '(.*)' string false
modulus Modulus to take of the hash of the source label values. uint64 false
replacement Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' string true
action Action to perform based on regex matching. Default is 'replace' string false

Back to TOC

RemoteReadSpec

RemoteReadSpec defines the remote_read configuration for prometheus.

Field Description Scheme Required
url The URL of the endpoint to send samples to. string true
remoteTimeout Timeout for requests to the remote write endpoint. string false
basicAuth BasicAuth for the URL. *BasicAuth false
bearerToken bearer token for remote write. string false
bearerTokenFile File to read bearer token for remote write. string false
tlsConfig TLS Config to use for remote write. *TLSConfig false
proxy_url Optional ProxyURL string false

Back to TOC

RemoteWriteSpec

RemoteWriteSpec defines the remote_write configuration for prometheus.

Field Description Scheme Required
url The URL of the endpoint to send samples to. string true
remoteTimeout Timeout for requests to the remote write endpoint. string false
writeRelabelConfigs The list of remote write relabel configurations. []RelabelConfig false
basicAuth BasicAuth for the URL. *BasicAuth false
bearerToken File to read bearer token for remote write. string false
bearerTokenFile File to read bearer token for remote write. string false
tlsConfig TLS Config to use for remote write. *TLSConfig false
proxy_url Optional ProxyURL string false

Back to TOC

ServiceMonitor

ServiceMonitor defines monitoring for a set of services.

Field Description Scheme Required
metadata Standard object’s metadata. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata metav1.ObjectMeta false
spec Specification of desired Service selection for target discrovery by Prometheus. ServiceMonitorSpec true

Back to TOC

ServiceMonitorList

A list of ServiceMonitors.

Field Description Scheme Required
metadata Standard list metadata More info: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#metadata metav1.ListMeta false
items List of ServiceMonitors []*ServiceMonitor true

Back to TOC

ServiceMonitorSpec

ServiceMonitorSpec contains specification parameters for a ServiceMonitor.

Field Description Scheme Required
jobLabel The label to use to retrieve the job name from. string false
endpoints A list of endpoints allowed as part of this ServiceMonitor. []Endpoint true
selector Selector to select Endpoints objects. metav1.LabelSelector true
namespaceSelector Selector to select which namespaces the Endpoints objects are discovered from. NamespaceSelector false

Back to TOC

StorageSpec

StorageSpec defines the configured storage for a group Prometheus servers.

Field Description Scheme Required
class Name of the StorageClass to use when requesting storage provisioning. More info: https://kubernetes.io/docs/user-guide/persistent-volumes/#storageclasses DEPRECATED string true
emptyDir EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir *v1.EmptyDirVolumeSource false
selector A label query over volumes to consider for binding. DEPRECATED *metav1.LabelSelector true
resources Resources represents the minimum resources the volume should have. More info: http://kubernetes.io/docs/user-guide/persistent-volumes#resources DEPRECATED v1.ResourceRequirements true
volumeClaimTemplate A PVC spec to be used by the Prometheus StatefulSets. v1.PersistentVolumeClaim false

Back to TOC

TLSConfig

TLSConfig specifies TLS configuration parameters.

Field Description Scheme Required
caFile The CA cert to use for the targets. string false
certFile The client cert file for the targets. string false
keyFile The client key file for the targets. string false
serverName Used to verify the hostname for the targets. string false
insecureSkipVerify Disable target certificate validation. bool false

Back to TOC