From a24fbfe6bd9466321662637e447bc7f52cd2274f Mon Sep 17 00:00:00 2001 From: Goutham Veeramachaneni Date: Mon, 30 Mar 2020 17:34:28 +0100 Subject: [PATCH] Document the v1.x guarantees Signed-off-by: Goutham Veeramachaneni --- docs/configuration/schema-config-reference.md | 2 +- docs/configuration/single-process-config.md | 2 +- docs/configuration/v1-guarantees.md | 47 +++++++++++++++++++ 3 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 docs/configuration/v1-guarantees.md diff --git a/docs/configuration/schema-config-reference.md b/docs/configuration/schema-config-reference.md index e690e948448..54c2b6edca3 100644 --- a/docs/configuration/schema-config-reference.md +++ b/docs/configuration/schema-config-reference.md @@ -1,7 +1,7 @@ --- title: "Schema Configuration" linkTitle: "Schema Configuration" -weight: 1 +weight: 4 slug: schema-configuration --- diff --git a/docs/configuration/single-process-config.md b/docs/configuration/single-process-config.md index 53a7231cccd..4e565711c5b 100644 --- a/docs/configuration/single-process-config.md +++ b/docs/configuration/single-process-config.md @@ -1,7 +1,7 @@ --- title: "Single-process" linkTitle: "Single-process" -weight: 4 +weight: 5 slug: single-process-config --- diff --git a/docs/configuration/v1-guarantees.md b/docs/configuration/v1-guarantees.md new file mode 100644 index 00000000000..22ee924fdf8 --- /dev/null +++ b/docs/configuration/v1-guarantees.md @@ -0,0 +1,47 @@ +--- +title: "v1.x Guarantees" +linkTitle: "v1.x Guarantees" +weight: 6 +slug: v1guarantees +--- + +For the v1.0 release, we want to provide the following guarantees: + +# Flags, Config and minor version upgrades + +Upgrading cortex from one minor version to the next should "just work"; that being said, we don't want to bump the major version every time we remove a flag, so we will will keep deprecated flags around for 2 minor release. There is a metric (`cortex_deprecated_flags_inuse_total`) you can alert on to find out if you're using a deprecated flag. + +Similarly to flags, minor version upgrades using config files should "just work". If we do need to change config, we will keep the old way working for two minor version. There will be a metric you can alert on for this too. + +These guarantees don't apply for [experimental features](#experimental-features). + +# Reading old data + +The Cortex maintainers commit to ensuring future version of Cortex can read data written by versions up to two years old. In practice we expect to be able to read more, but this is our guarantee. + +# API Compatibility + +Cortex strives to be 100% API compatible with Prometheus (under `/api/prom/*`); any deviation from this is considered a bug, except: + +- Requiring the `__name__` label on queries. +- Additional API endpoints for creating, removing and modifying alerts and recording rules. +- Additional API around pushing metrics (under `/api/push`). +- Additional API endpoints for management of Cortex itself, such as the ring. These APIs are not part of the any compatibility guarantees. + +# Experimental features + +Cortex is an actively developed project and we want to encourage the introduction of new features and capability. As such, not everything in each release of Cortex is considered "production-ready". We don't provide any backwards compatibility guarantees on these and the config and flags might break. + +Currently experimental features are: + +- TSDB block storage. +- Ingester chunk WAL. +- Cassandra storage engine. +- Azure blob storage. +- Zone awareness based replication. +- Gossip based ring. +- User subrings. +- Ruler API (to PUT rules). +- Memcached client DNS-based service discovery. +- Delete series APIs. +- In-memory (FIFO) and Redis cache.