mirrors/prometheus-operator
mirrors/prometheus-operator
1
0
Fork 0
mirror of https://github.com/prometheus-operator/prometheus-operator.git synced 2025-04-21 11:48:53 +00:00
Code Activity

generate api docs

Browse source
This commit is contained in:
Frederic Branczyk 2017-03-06 16:24:59 +01:00
parent ac6ade2b99
commit c158ee5acc
No known key found for this signature in database
GPG key ID: CA14788B1E48B256
9 changed files with 491 additions and 173 deletions

27
Documentation/alertmanager.md
View file

@ -1,27 +0,0 @@
# Alertmanager
The `Alertmanager` third party resource (TPR) declaratively defines a desired Alertmanager setup to run in a Kubernetes cluster. It provides options to configure replication and persistent storage.
For each `Alertmanager` TPR, the Operator deploys a properly configured `StatefulSet` in the same namespace. The Alertmanager pods are configured to include a ConfigMap called `<alertmanager-name>` which holds the used configuration file.
When there are two or more configured replicas the operator runs the Alertmanager instances in high availability mode.
## Specification
### `Alertmanager`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| spec | Specification of the Alertmanager object | true | AlertmanagerSpec | |
### `AlertmanagerSpec`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| version | Alertmanager version to deploy. Must match a tag of the container image. | false | string | v0.5.0 |
| baseImage | The base container image (without tag) to use. | false | string | quay.io/prometheus/alertmanager |
| replicas | Number of Alertmanager instances to deploy. | false | integer (int32) | 1 |
| storage | Configuration of persistent storage volumes to attach to deployed Alertmanager pods. | false | [StorageSpec](prometheus.md#storagespec) | |
| externalUrl | External URL Alertmanager will be reachable under. Used for registering routes. | false | string | |
| paused | If true, the operator won't process any changes affecting the Alertmanager setup | false | bool | false |

193
Documentation/api.md Normal file
View file

@ -0,0 +1,193 @@
# 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.
## AlertingSpec
AlertingSpec defines paramters for alerting configuration of Prometheus servers.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| alertmanagers | AlertmanagerEndpoints Prometheus should fire alerts against. | `[]AlertmanagerEndpoints` | true |
## Alertmanager
Describes an Alertmanager cluster.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| metadata | Standard object’s metadata. More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata | `metav1.ObjectMeta` | false |
| spec | Specification of the desired behavior of the Alertmanager cluster. More info: http://releases.k8s.io/HEAD/docs/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: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status | `*AlertmanagerStatus` | false |
## 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` | true |
## AlertmanagerList
A list of Alertmanagers.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| metadata | Standard list metadata More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata | `metav1.ListMeta` | false |
| items | List of Alertmanagers | `[]Alertmanager` | true |
## AlertmanagerSpec
Specification of the desired behavior of the Alertmanager cluster. More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| version | Version the cluster should be on. | `string` | false |
| baseImage | Base image that is used to deploy pods. | `string` | 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 | ExternalURL is the URL under which Alertmanager is externally reachable (for example, if Alertmanager is served via a reverse proxy). Used for generating relative and absolute links back to Alertmanager itself. If the URL has a path portion, it will be used to prefix all HTTP endpoints served by Alertmanager. If omitted, relevant URL components will be derived automatically. | `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 |
## 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: http://releases.k8s.io/HEAD/docs/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 |
## 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 |
| interval | Interval at which metrics should be scraped | `string` | false |
| tlsConfig | TLS configuration to use when scraping the endpoint | `*TLSConfig` | false |
| bearerTokenFile | File to read bearer token for scraping targets. | `string` | false |
## 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 |
## Prometheus
Prometheus defines a Prometheus deployment.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| metadata | Standard object’s metadata. More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata | `metav1.ObjectMeta` | false |
| spec | Specification of the desired behavior of the Prometheus cluster. More info: http://releases.k8s.io/HEAD/docs/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: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status | `*PrometheusStatus` | false |
## PrometheusList
PrometheusList is a list of Prometheuses.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| metadata | Standard list metadata More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata | `metav1.ListMeta` | false |
| items | List of Prometheuses | `[]*Prometheus` | true |
## PrometheusSpec
Specification of the desired behavior of the Prometheus cluster. More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| 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 |
| replicas | Number of instances to deploy for a Prometheus deployment. | `*int32` | false |
| retention | Time duration Prometheus shall retain data for. | `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 |
| 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 |
## 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: http://releases.k8s.io/HEAD/docs/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 |
## ServiceMonitor
ServiceMonitor defines monitoring for a set of services.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| metadata | Standard object’s metadata. More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata | `metav1.ObjectMeta` | false |
| spec | Specification of desired Service selection for target discrovery by Prometheus. | `ServiceMonitorSpec` | true |
## ServiceMonitorList
A list of ServiceMonitors.
| Field | Description | Scheme | Required |
| ----- | ----------- | ------ | -------- |
| metadata | Standard list metadata More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata | `metav1.ListMeta` | false |
| items | List of ServiceMonitors | `[]*ServiceMonitor` | true |
## 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` | false |
| selector | Selector to select Endpoints objects. | `metav1.LabelSelector` | true |
| namespaceSelector | Selector to select which namespaces the Endpoints objects are discovered from. | `NamespaceSelector` | false |
## 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 | `string` | true |
| selector | A label query over volumes to consider for binding. | `*metav1.LabelSelector` | true |
| resources | Resources represents the minimum resources the volume should have. More info: http://kubernetes.io/docs/user-guide/persistent-volumes#resources | `v1.ResourceRequirements` | true |
## 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 |

37
Documentation/design.md Normal file
View file

@ -0,0 +1,37 @@
# Design
This document describes the design and interaction between the third party resources that the Prometheus Operator introduces.
## Prometheus
The `Prometheus` third party resource (TPR) declaratively defines a desired Prometheus setup to run in a Kubernetes cluster. It provides options to configure replication, persistent storage, and Alertmanagers to which the deployed Prometheus instances send alerts to.
For each `Prometheus` TPR, the Operator deploys a properly configured `StatefulSet` in the same namespace. The Prometheus `Pod`s are configured to include two ConfigMaps, `<prometheus-name>` and `<prometheus-name>-rules`, which respectively hold the used configuration file and multiple Prometheus rule files that may contain alerting and recording rules.
The TPR allows to specify which [`ServiceMonitor`s](./service-monitor.md) should be covered by the deployed Prometheus instances based on label selection. The Operator then generates a configuration based on the included `ServiceMonitor`s and updates it in the ConfigMap. It continuously does so for all changes that are made to `ServiceMonitor`s or the `Prometheus` TPR itself.
If no selection of `ServiceMonitor`s is provided, the Operator leaves management of the ConfigMap to the user, which allows to provide custom configurations while still benefiting from the Operator's capabilities of managing Prometheus setups.
## ServiceMonitor
The `ServiceMonitor` third party resource (TPR) allows to declaratively define how a dynamic set of services should be monitored. Which services are selected to be monitored with the desired configuration is defined using label selections. This allows an organization to introduce conventions around how metrics are exposed, and then following these conventions new services are automatically discovered, without the need to reconfigure the system.
For Prometheus to monitor any application within Kubernetes an `Endpoints` object needs to exist. `Endpoints` objects are essentially lists of IP addresses. Typically an `Endpoints` object is populated by a `Service` object. A `Service` object discovers `Pod`s by a label selector and adds those to the `Endpoints` object.
A `Service` may expose one or more service ports, which are backed by a list of multiple endpoints that point to a `Pod` in the common case. This is reflected in the respective `Endpoints` object as well.
The `ServiceMonitor` object introduced by the Prometheus Operator in turn discovers those `Endpoints` objects and configures Prometheus to monitor those `Pod`s.
The `endpoints` section of the `ServiceMonitorSpec`, is used to configure which ports of these `Endpoints` are going to be scraped for metrics, and with which parameters. For advanced use cases one may want to monitor ports of backing `Pod`s, which are not directly part of the service endpoints. Therefore when specifying an endpoint in the `endpoints` section, they are strictly used.
> Note: `endpoints` (lowercase) is the TPR field, while `Endpoints` (capitalized) is the Kubernetes object kind.
While `ServiceMonitor`s must live in the same namespace as the `Prometheus` TPR, discovered targets may come from any namespace. This is important to allow cross-namespace monitoring use cases, e.g. for meta-monitoring. Using the `namespaceSelector` of the `ServiceMonitorSpec`, one can restrict the namespaces the `Endpoints` objects are allowed to be discovered from.
## Alertmanager
The `Alertmanager` third party resource (TPR) declaratively defines a desired Alertmanager setup to run in a Kubernetes cluster. It provides options to configure replication and persistent storage.
For each `Alertmanager` TPR, the Operator deploys a properly configured `StatefulSet` in the same namespace. The Alertmanager pods are configured to include a ConfigMap called `<alertmanager-name>` which holds the used configuration file.
When there are two or more configured replicas the operator runs the Alertmanager instances in high availability mode.

57
Documentation/prometheus.md
View file

@ -1,57 +0,0 @@
# Prometheus
The `Prometheus` third party resource (TPR) declaratively defines a desired Prometheus setup to run in a Kubernetes cluster. It provides options to configure replication, persistent storage, and Alertmanagers to which the deployed Prometheus instances send alerts to.
For each `Prometheus` TPR, the Operator deploys a properly configured `StatefulSet` in the same namespace. The Prometheus `Pod`s are configured to include two ConfigMaps, `<prometheus-name>` and `<prometheus-name>-rules`, which respectively hold the used configuration file and multiple Prometheus rule files that may contain alerting and recording rules.
The TPR allows to specify which [`ServiceMonitor`s](./service-monitor.md) should be covered by the deployed Prometheus instances based on label selection. The Operator then generates a configuration based on the included `ServiceMonitor`s and updates it in the ConfigMap. It continuously does so for all changes that are made to `ServiceMonitor`s or the `Prometheus` TPR itself.
If no selection of `ServiceMonitor`s is provided, the Operator leaves management of the ConfigMap to the user, which allows to provide custom configurations while still benefiting from the Operator's capabilities of managing Prometheus setups.
## Specification
### `Prometheus`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| spec | Specification of the Prometheus object | true | PrometheusSpec | |
### `PrometheusSpec`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| serviceMonitorSelector | The `ServiceMonitor` TPRs to be covered by the Prometheus instances. | false | [unversioned.LabelSelector](http://kubernetes.io/docs/api-reference/v1/definitions/#_unversioned_labelselector) | |
| version | Prometheus version to deploy. Must match a tag of the container image. | false | string | v1.3.0 |
| paused | If true, the operator won't process any changes affecting the Prometheus setup | false | bool | false |
| baseImage | The base container image (without tag) to use. | false | string | quay.io/prometheus/prometheus |
| replicas | Number of Prometheus instances to deploy. | false | integer (int32) | 1 |
| retention | The duration for which ingested metrics are stored. | false | duration | 24h |
| storage | Configuration of persistent storage volumes to attach to deployed Prometheus pods. | false | StorageSpec | |
| alerting | Configuration of alerting | false | AlertingSpec | |
| resources | Resource requirements of single Prometheus server | false | [v1.ResourceRequirements](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_resourcerequirements) | |
| nodeSelector | [Select nodes](https://kubernetes.io/docs/tasks/administer-cluster/assign-pods-nodes/) to be used to run the Prometheus pods on | false | [object](https://kubernetes.io/docs/user-guide/node-selection/) | |
| externalUrl | External URL Prometheus will be reachable under. Used for generating links, and registering routes. | false | string | |
| routePrefix | Prefix used to register routes. Overrides `externalUrl` route. Useful for proxies, that rewrite URLs. | false | string | |
### `StorageSpec`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| class | The storage class to use. | false | string | |
| selector | Selector over candidate persistent volumes. | false | [unversioned.LabelSelector](http://kubernetes.io/docs/api-reference/v1/definitions/#_unversioned_labelselector) | |
| resources | Resource requirements for the created persistent volume claim. | false | [v1.ResourceRequirements](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_resourcerequirements)| |
### `AlertingSpec`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| alertmanagers | Alertmanagers alerts are sent to. | false | AlertmanagerEndpoints array | |
### `AlertmanagerEndpoints`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| namespace | Namespace of the Alertmanager endpoints. | true | string | |
| name | Name of the Alertmanager endpoints. This equals the targeted Alertmanager service. | true | string |
| port | Name or number of the service port to push alerts to | false | integer or string |
| scheme | HTTP scheme to use when pushing alerts | false | http |

64
Documentation/service-monitor.md
View file

@ -1,64 +0,0 @@
# ServiceMonitor
The `ServiceMonitor` third party resource (TPR) allows to declaratively define how a dynamic set of services should be monitored. Which services are selected to be monitored with the desired configuration is defined using label selections. This allows an organization to introduce conventions around how metrics are exposed, and then following these conventions new services are automatically discovered, without the need to reconfigure the system.
## Design
For Prometheus to monitor any application within Kubernetes an `Endpoints` object needs to exist. `Endpoints` objects are essentially lists of IP addresses. Typically an `Endpoints` object is populated by a `Service` object. A `Service` object discovers `Pod`s by a label selector and adds those to the `Endpoints` object.
A `Service` may expose one or more service ports, which are backed by a list of multiple endpoints that point to a `Pod` in the common case. This is reflected in the respective `Endpoints` object as well.
The `ServiceMonitor` object introduced by the Prometheus Operator in turn discovers those `Endpoints` objects and configures Prometheus to monitor those `Pod`s.
The `endpoints` section of the `ServiceMonitorSpec`, is used to configure which ports of these `Endpoints` are going to be scraped for metrics, and with which parameters. For advanced use cases one may want to monitor ports of backing `Pod`s, which are not directly part of the service endpoints. Therefore when specifying an endpoint in the `endpoints` section, they are strictly used.
> Note: `endpoints` (lowercase) is the TPR field, while `Endpoints` (capitalized) is the Kubernetes object kind.
While `ServiceMonitor`s must live in the same namespace as the `Prometheus` TPR, discovered targets may come from any namespace. This is important to allow cross-namespace monitoring use cases, e.g. for meta-monitoring. Using the `namespaceSelector` of the `ServiceMonitorSpec`, one can restrict the namespaces the `Endpoints` objects are allowed to be discovered from.
## Specification
### `ServiceMonitor`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| spec | Specification of the ServiceMonitor object. | true | ServiceMonitorSpec | |
### `ServiceMonitorSpec`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| jobLabel | Service label of which the value is used to assemble a job name of the form `<label value>-<port>`. If no label is specified, the service name is used. | false | string | |
| selector | Label selector for services the `ServiceMonitor` applies to. | true | [unversioned.LabelSelector](http://kubernetes.io/docs/api-reference/v1/definitions/#_unversioned_labelselector) | |
| namespaceSelector | Namespaces from which services are selected. | false | NamespaceSelector | same namespace only |
| endpoints | The endpoints to be monitored for endpoints of the selected services. | true | Endpoint array | |
### `Endpoint`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| port | Name of the service port this endpoint refers to. Mutually exclusive with targetPort. | false | string | |
| targetPort | Name or number of the target port of the endpoint. Mutually exclusive with port. | false | integer or string | |
| path | HTTP path to scrape for metrics. | false | string | /metrics |
| scheme | HTTP scheme to use for scraping | false | string | http |
| interval | Interval at which metrics should be scraped | false | duration | 30s |
| tlsConfig | TLS configuration to use when scraping the endpoint | false | TLSConfig | |
| bearerTokenFile | File to read bearer token for scraping targets. | false | string | |
### `TLSConfig`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| caFile | Path to the CA file. | false | string | |
| certFile | Path to client certificate file | false | |
| keyFile | Path to client key file | false | |
| serverName | Server name used to verify host name | |
| insecureSkipVerify | Skip certificate verification | false | bool | false |
### `NamespaceSelector`
| Name | Description | Required | Schema | Default |
| ---- | ----------- | -------- | ------ | ------- |
| any | Match any namespace | false | bool | false |
| matchNames | Explicit list of namespace names to select | false | string array | |

13
Makefile
View file

@ -53,7 +53,14 @@ embedmd:
GOARCH=$(subst x86_64,amd64,$(patsubst i%86,386,$(shell uname -m))) \
go get github.com/campoy/embedmd
docs: embedmd
embedmd -w `find Documentation -name "*.md"`
apidocgen:
@GOOS=$(shell uname -s | tr A-Z a-z) \
GOARCH=$(subst x86_64,amd64,$(patsubst i%86,386,$(shell uname -m))) \
go install github.com/coreos/prometheus-operator/cmd/apidocgen
.PHONY: all build crossbuild test format check-license container e2e-test e2e-status e2e clean-e2e embedmd docs
docs: embedmd apidocgen
embedmd -w `find Documentation -name "*.md"`
apidocgen pkg/client/monitoring/v1alpha1/types.go > Documentation/api.md
.PHONY: all build crossbuild test format check-license container e2e-test e2e-status e2e clean-e2e embedmd apidocgen docs

8
README.md
View file

@ -70,16 +70,18 @@ in the migration will from now on be managed by the Prometheus Operator.
The Operator acts on the following [third party resources (TPRs)](http://kubernetes.io/docs/user-guide/thirdpartyresources/):
* **[`Prometheus`](./Documentation/prometheus.md)**, which defines a desired Prometheus deployment.
* **`Prometheus`**, which defines a desired Prometheus deployment.
The Operator ensures at all times that a deployment matching the resource definition is running.
* **[`ServiceMonitor`](./Documentation/service-monitor.md)**, which declaratively specifies how groups
* **`ServiceMonitor`**, which declaratively specifies how groups
of services should be monitored. The Operator automatically generates Prometheus scrape configuration
based on the definition.
* **[`Alertmanager`](./Documentation/alertmanager.md)**, which defines a desired Alertmanager deployment.
* **`Alertmanager`**, which defines a desired Alertmanager deployment.
The Operator ensures at all times that a deployment matching the resource definition is running.
To learn more about the TPRs introduced by the Prometheus Operator have a look
at the [design doc](Documentation/design.md).
## Installation

185
cmd/apidocgen/main.go Normal file
View file

@ -0,0 +1,185 @@
package main
import (
"bytes"
"fmt"
"go/ast"
"go/doc"
"go/parser"
"go/token"
"os"
"reflect"
"strings"
)
const (
firstParagraph = `# 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.`
)
func main() {
fmt.Println(firstParagraph)
types := ParseDocumentationFrom(os.Args[1])
for _, t := range types {
strukt := t[0]
fmt.Printf("\n## %s\n\n%s\n\n", strukt.Name, strukt.Doc)
fmt.Println("| Field | Description | Scheme | Required |")
fmt.Println("| ----- | ----------- | ------ | -------- |")
fields := t[1:(len(t))]
for _, f := range fields {
fmt.Println("|", f.Name, "|", f.Doc, "| `"+f.Type+"` |", f.Mandatory, "|")
}
}
}
// Pair of strings. We keed the name of fields and the doc
type Pair struct {
Name, Doc, Type string
Mandatory bool
}
// KubeTypes is an array to represent all available types in a parsed file. [0] is for the type itself
type KubeTypes []Pair
// ParseDocumentationFrom gets all types' documentation and returns them as an
// array. Each type is again represented as an array (we have to use arrays as we
// need to be sure for the order of the fields). This function returns fields and
// struct definitions that have no documentation as {name, ""}.
func ParseDocumentationFrom(src string) []KubeTypes {
var docForTypes []KubeTypes
pkg := astFrom(src)
for _, kubType := range pkg.Types {
if structType, ok := kubType.Decl.Specs[0].(*ast.TypeSpec).Type.(*ast.StructType); ok {
var ks KubeTypes
ks = append(ks, Pair{kubType.Name, fmtRawDoc(kubType.Doc), "", false})
for _, field := range structType.Fields.List {
typeString := fieldType(field.Type)
fieldMandatory := fieldRequired(field)
if n := fieldName(field); n != "-" {
fieldDoc := fmtRawDoc(field.Doc.Text())
ks = append(ks, Pair{n, fieldDoc, typeString, fieldMandatory})
}
}
docForTypes = append(docForTypes, ks)
}
}
return docForTypes
}
func astFrom(filePath string) *doc.Package {
fset := token.NewFileSet()
m := make(map[string]*ast.File)
f, err := parser.ParseFile(fset, filePath, nil, parser.ParseComments)
if err != nil {
fmt.Println(err)
return nil
}
m[filePath] = f
apkg, _ := ast.NewPackage(fset, m, nil, nil)
return doc.New(apkg, "", 0)
}
func fmtRawDoc(rawDoc string) string {
var buffer bytes.Buffer
delPrevChar := func() {
if buffer.Len() > 0 {
buffer.Truncate(buffer.Len() - 1) // Delete the last " " or "\n"
}
}
// Ignore all lines after ---
rawDoc = strings.Split(rawDoc, "---")[0]
for _, line := range strings.Split(rawDoc, "\n") {
line = strings.TrimRight(line, " ")
leading := strings.TrimLeft(line, " ")
switch {
case len(line) == 0: // Keep paragraphs
delPrevChar()
buffer.WriteString("\n\n")
case strings.HasPrefix(leading, "TODO"): // Ignore one line TODOs
case strings.HasPrefix(leading, "+"): // Ignore instructions to go2idl
default:
if strings.HasPrefix(line, " ") || strings.HasPrefix(line, "\t") {
delPrevChar()
line = "\n" + line + "\n" // Replace it with newline. This is useful when we have a line with: "Example:\n\tJSON-someting..."
} else {
line += " "
}
buffer.WriteString(line)
}
}
postDoc := strings.TrimRight(buffer.String(), "\n")
postDoc = strings.Replace(postDoc, "\\\"", "\"", -1) // replace user's \" to "
postDoc = strings.Replace(postDoc, "\"", "\\\"", -1) // Escape "
postDoc = strings.Replace(postDoc, "\n", "\\n", -1)
postDoc = strings.Replace(postDoc, "\t", "\\t", -1)
return postDoc
}
// fieldName returns the name of the field as it should appear in JSON format
// "-" indicates that this field is not part of the JSON representation
func fieldName(field *ast.Field) string {
jsonTag := ""
if field.Tag != nil {
jsonTag = reflect.StructTag(field.Tag.Value[1 : len(field.Tag.Value)-1]).Get("json") // Delete first and last quotation
if strings.Contains(jsonTag, "inline") {
return "-"
}
}
jsonTag = strings.Split(jsonTag, ",")[0] // This can return "-"
if jsonTag == "" {
if field.Names != nil {
return field.Names[0].Name
}
return field.Type.(*ast.Ident).Name
}
return jsonTag
}
// fieldRequired returns whether a field is a required field.
func fieldRequired(field *ast.Field) bool {
jsonTag := ""
if field.Tag != nil {
jsonTag = reflect.StructTag(field.Tag.Value[1 : len(field.Tag.Value)-1]).Get("json") // Delete first and last quotation
return !strings.Contains(jsonTag, "omitempty")
}
return false
}
func fieldType(typ ast.Expr) string {
switch typ.(type) {
case *ast.Ident:
return typ.(*ast.Ident).Name
case *ast.StarExpr:
return "*" + fieldType(typ.(*ast.StarExpr).X)
case *ast.SelectorExpr:
e := typ.(*ast.SelectorExpr)
pkg := e.X.(*ast.Ident)
t := e.Sel
return pkg.Name + "." + t.Name
case *ast.ArrayType:
return "[]" + fieldType(typ.(*ast.ArrayType).Elt)
case *ast.MapType:
mapType := typ.(*ast.MapType)
return "map[" + fieldType(mapType.Key) + "]" + fieldType(mapType.Value)
default:
return ""
}
}

80
pkg/client/monitoring/v1alpha1/types.go
View file

@ -22,21 +22,32 @@ import (
// Prometheus defines a Prometheus deployment.
type Prometheus struct {
metav1.TypeMeta `json:",inline"`
metav1.TypeMeta `json:",inline"`
// Standard object’s metadata. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec PrometheusSpec `json:"spec"`
Status *PrometheusStatus `json:"status,omitempty"`
// Specification of the desired behavior of the Prometheus cluster. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
Spec PrometheusSpec `json:"spec"`
// 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:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
Status *PrometheusStatus `json:"status,omitempty"`
}
// PrometheusList is a list of Prometheuses.
type PrometheusList struct {
metav1.TypeMeta `json:",inline"`
// Standard list metadata
// More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
metav1.ListMeta `json:"metadata,omitempty"`
// List of Prometheuses
Items []*Prometheus `json:"items"`
}
// PrometheusSpec holds specification parameters of a Prometheus deployment.
// Specification of the desired behavior of the Prometheus cluster. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
type PrometheusSpec struct {
// ServiceMonitors to be selected for target discovery.
ServiceMonitorSelector *metav1.LabelSelector `json:"serviceMonitorSelector,omitempty"`
@ -76,6 +87,10 @@ type PrometheusSpec struct {
// Sharding...
}
// 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:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
type PrometheusStatus struct {
// Represents whether any actions on the underlaying managed objects are
// being performed. Only delete actions will be performed.
@ -126,9 +141,13 @@ type AlertmanagerEndpoints struct {
// ServiceMonitor defines monitoring for a set of services.
type ServiceMonitor struct {
metav1.TypeMeta `json:",inline"`
metav1.TypeMeta `json:",inline"`
// Standard object’s metadata. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec ServiceMonitorSpec `json:"spec"`
// Specification of desired Service selection for target discrovery by
// Prometheus.
Spec ServiceMonitorSpec `json:"spec"`
}
// ServiceMonitorSpec contains specification parameters for a ServiceMonitor.
@ -164,32 +183,45 @@ type Endpoint struct {
// TLSConfig specifies TLS configuration parameters.
type TLSConfig struct {
// The CA cert to use for the targets.
CAFile string `yaml:"caFile,omitempty"`
CAFile string `json:"caFile,omitempty"`
// The client cert file for the targets.
CertFile string `yaml:"certFile,omitempty"`
CertFile string `json:"certFile,omitempty"`
// The client key file for the targets.
KeyFile string `yaml:"keyFile,omitempty"`
KeyFile string `json:"keyFile,omitempty"`
// Used to verify the hostname for the targets.
ServerName string `yaml:"serverName,omitempty"`
ServerName string `json:"serverName,omitempty"`
// Disable target certificate validation.
InsecureSkipVerify bool `yaml:"insecureSkipVerify,omitempty"`
InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`
}
// ServiceMonitorList is a list of ServiceMonitors.
// A list of ServiceMonitors.
type ServiceMonitorList struct {
metav1.TypeMeta `json:",inline"`
// Standard list metadata
// More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
metav1.ListMeta `json:"metadata,omitempty"`
// List of ServiceMonitors
Items []*ServiceMonitor `json:"items"`
}
// Describes an Alertmanager cluster.
type Alertmanager struct {
metav1.TypeMeta `json:",inline"`
metav1.TypeMeta `json:",inline"`
// Standard object’s metadata. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec AlertmanagerSpec `json:"spec"`
Status *AlertmanagerStatus `json:"status,omitempty"`
// Specification of the desired behavior of the Alertmanager cluster. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
Spec AlertmanagerSpec `json:"spec"`
// 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:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
Status *AlertmanagerStatus `json:"status,omitempty"`
}
// Specification of the desired behavior of the Alertmanager cluster. More info:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
type AlertmanagerSpec struct {
// Version the cluster should be on.
Version string `json:"version,omitempty"`
@ -214,15 +246,20 @@ type AlertmanagerSpec struct {
Paused bool `json:"paused,omitempty"`
}
// A list of Alertmanagers.
type AlertmanagerList struct {
metav1.TypeMeta `json:",inline"`
// Standard list metadata
// More info: http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata
metav1.ListMeta `json:"metadata,omitempty"`
// Items is a list of third party objects
// List of Alertmanagers
Items []Alertmanager `json:"items"`
}
// 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:
// http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status
type AlertmanagerStatus struct {
// Represents whether any actions on the underlaying managed objects are
// being performed. Only delete actions will be performed.
@ -240,8 +277,13 @@ type AlertmanagerStatus struct {
UnavailableReplicas int32 `json:"unavailableReplicas"`
}
// A selector for selecting namespaces either selecting all namespaces or a
// list of namespaces.
type NamespaceSelector struct {
Any bool `json:"any,omitempty"`
// Boolean describing whether all namespaces are selected in contrast to a
// list restricting them.
Any bool `json:"any,omitempty"`
// List of namespace names.
MatchNames []string `json:"matchNames,omitempty"`
// TODO(fabxc): this should embed metav1.LabelSelector eventually.