diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 75b19322f9..cc24b3bb92 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -82,11 +82,11 @@ alerting: alertmanagers: [ - ... ] -# Settings related to the experimental remote write feature. +# Settings related to the remote write feature. remote_write: [ - ... ] -# Settings related to the experimental remote read feature. +# Settings related to the remote read feature. remote_read: [ - ... ] ``` @@ -253,9 +253,6 @@ A `tls_config` allows configuring TLS connections. ### `` -CAUTION: Azure SD is in beta: breaking changes to configuration are still -likely in future releases. - Azure SD configurations allow retrieving scrape targets from Azure VMs. The following meta labels are available on targets during relabeling: @@ -412,18 +409,8 @@ region: ### `` -CAUTION: OpenStack SD is in beta: breaking changes to configuration are still -likely in future releases. - -OpenStack SD configurations allow retrieving scrape targets from the OpenStack -Nova API. - -One of the following `role` types can be configured to discover targets: - -#### `hypervisor` - -The `hypervisor` role discovers one target per Nova hypervisor node. The target -address defaults to the `host_ip` attribute of the hypervisor. +OpenStack SD configurations allow retrieving scrape targets from OpenStack Nova +instances. The following meta labels are available on targets during [relabeling](#relabel_config): @@ -546,9 +533,6 @@ may contain a single `*` that matches any character sequence, e.g. `my/path/tg_* ### `` -CAUTION: GCE SD is in beta: breaking changes to configuration are still -likely in future releases. - [GCE](https://cloud.google.com/compute/) SD configurations allow retrieving scrape targets from GCP GCE instances. The private IP address is used by default, but may be changed to the public IP address with relabeling. @@ -607,9 +591,6 @@ service account and place the credential file in one of the expected locations. ### `` -CAUTION: Kubernetes SD is in beta: breaking changes to configuration are still -likely in future releases. - Kubernetes SD configurations allow retrieving scrape targets from [Kubernetes'](http://kubernetes.io/) REST API and always staying synchronized with the cluster state. @@ -755,9 +736,6 @@ which automates the Prometheus setup on top of Kubernetes. ### `` -CAUTION: Marathon SD is in beta: breaking changes to configuration are still -likely in future releases. - Marathon SD configurations allow retrieving scrape targets using the [Marathon](https://mesosphere.github.io/marathon/) REST API. Prometheus will periodically check the REST endpoint for currently running tasks and @@ -854,9 +832,6 @@ Serverset data must be in the JSON format, the Thrift format is not currently su ### `` -CAUTION: Triton SD is in beta: breaking changes to configuration are still -likely in future releases. - [Triton](https://github.com/joyent/triton) SD configurations allow retrieving scrape targets from [Container Monitor](https://github.com/joyent/rfd/blob/master/rfd/0027/README.md) discovery endpoints. @@ -1103,9 +1078,6 @@ relabel_configs: ### `` -CAUTION: Remote write is experimental: breaking changes to configuration are -likely in future releases. - `write_relabel_configs` is relabeling applied to samples before sending them to the remote endpoint. Write relabeling is applied after external labels. This could be used to limit which samples are sent. @@ -1152,9 +1124,6 @@ with this feature. ### `` -CAUTION: Remote read is experimental: breaking changes to configuration are -likely in future releases. - ```yaml # The URL of the endpoint to query from. url: diff --git a/docs/stability.md b/docs/stability.md new file mode 100644 index 0000000000..6753e90d70 --- /dev/null +++ b/docs/stability.md @@ -0,0 +1,38 @@ +--- +title: API Stability +sort_rank: 8 +--- + +# API Stability Guarantees + +Prometheus promises API stability within a major version, and strives to avoid +breaking changes for key features. Some features, which are cosmetic, still +under development, or depend on 3rd party services, are not covered by this. + +Things considered stable for 2.x: + +* The query language and data model +* Alerting and recording rules +* The ingestion exposition format +* v1 HTTP API (used by dashboards and UIs) +* Configuration file format (minus the service discovery remote read/write, see below) +* Rule/alert file format +* Console template syntax and semantics + +Things considered unstable for 2.x: + +* Any feature listed as experimental or subject to change, including: + * The [`holt_winters` PromQL function](https://github.com/prometheus/prometheus/issues/2458) + * Remote read, remote write and the remote read endpoint + * v2 HTTP and GRPC APIs +* Service discovery integrations, with the exception of `static_configs` and `file_sd_configs` +* Go APIs of packages that are part of the server +* HTML generated by the web UI +* The metrics in the /metrics endpoint of Prometheus itself +* Exact on-disk format. Potential changes however, will be forward compatible and transparently handled by Prometheus + +As long as you are not using any features marked as experimental/unstable, an +upgrade within a major version can usually be performed without any operational +adjustments and very little risk that anything will break. Any breaking changes +will be marked as `CHANGE` in release notes. + diff --git a/docs/storage.md b/docs/storage.md index 5226e9bcc5..21e46db4f3 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -75,7 +75,7 @@ Prometheus integrates with remote storage systems in two ways: ![Remote read and write architecture](images/remote_integrations.png) -The read and write protocols both use a snappy-compressed protocol buffer encoding over HTTP. The protocols are still marked experimental and may change to use gRPC over HTTP/2 in the future, when all hops between Prometheus and the long-term storage can safely be assumed to support HTTP/2. +The read and write protocols both use a snappy-compressed protocol buffer encoding over HTTP. The protocols are not considered as stable APIs yet and may change to use gRPC over HTTP/2 in the future, when all hops between Prometheus and the long-term storage can safely be assumed to support HTTP/2. For details on configuring remote storage integrations in Prometheus, see the [remote write](configuration/configuration.md#remote_write) and [remote read](configuration/configuration.md#remote_read) sections of the Prometheus configuration documentation.