github.com/muhammadn/cortex@v1.9.1-0.20220510110439-46bb7000d03d/docs/configuration/v1-guarantees.md (about)

     1  ---
     2  title: "v1.x Guarantees"
     3  linkTitle: "v1.x Guarantees"
     4  weight: 6
     5  slug: v1guarantees
     6  ---
     7  
     8  For the v1.0 release, we want to provide the following guarantees:
     9  
    10  ## Flags, Config and minor version upgrades
    11  
    12  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.
    13  
    14  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.
    15  
    16  These guarantees don't apply for [experimental features](#experimental-features).
    17  
    18  ## Reading old data
    19  
    20  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.
    21  
    22  ## API Compatibility
    23  
    24  Cortex strives to be 100% API compatible with Prometheus (under `/prometheus/*` and `/api/prom/*`); any deviation from this is considered a bug, except:
    25  
    26  - Requiring the `__name__` label on queries when querying the [chunks storage](../chunks-storage/_index.md) (queries to ingesters or clusters running the blocks storage are not affected).
    27  - For queries to the `/api/v1/series`, `/api/v1/labels` and `/api/v1/label/{name}/values` endpoints, query's time range is ignored and the data is always fetched from ingesters. There is experimental support to query the long-term store with the *blocks* storage engine when `-querier.query-store-for-labels-enabled` is set.
    28  - Additional API endpoints for creating, removing and modifying alerts and recording rules.
    29  - Additional API around pushing metrics (under `/api/push`).
    30  - Additional API endpoints for management of Cortex itself, such as the ring.  These APIs are not part of the any compatibility guarantees.
    31  
    32  _For more information, please refer to the [limitations](../guides/limitations.md) doc._
    33  
    34  ## Experimental features
    35  
    36  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.
    37  
    38  Currently experimental features are:
    39  
    40  - S3 Server Side Encryption (SSE) using KMS (including per-tenant KMS config overrides).
    41  - Azure blob storage.
    42  - Zone awareness based replication.
    43  - Ruler API (to PUT rules).
    44  - Alertmanager:
    45    - API (enabled via `-experimental.alertmanager.enable-api`)
    46    - Sharding of tenants across multiple instances (enabled via `-alertmanager.sharding-enabled`)
    47    - Receiver integrations firewall (configured via `-alertmanager.receivers-firewall.*`)
    48  - Memcached client DNS-based service discovery.
    49  - Delete series APIs.
    50  - In-memory (FIFO) and Redis cache.
    51  - gRPC Store.
    52  - TLS configuration in gRPC and HTTP clients.
    53  - TLS configuration in Etcd client.
    54  - Blocksconvert tools
    55  - OpenStack Swift storage support (both in blocks and chunks storage).
    56  - Metric relabeling in the distributor.
    57  - Scalable query-frontend (when using query-scheduler)
    58  - Querying store for series, labels APIs (`-querier.query-store-for-labels-enabled`)
    59  - Ingester: do not unregister from ring on shutdown (`-ingester.unregister-on-shutdown=false`)
    60  - Distributor: do not extend writes on unhealthy ingesters (`-distributor.extend-writes=false`)
    61  - Tenant Deletion in Purger, for blocks storage.
    62  - Query-frontend: query stats tracking (`-frontend.query-stats-enabled`)
    63  - Blocks storage bucket index
    64    - The bucket index support in the querier and store-gateway (enabled via `-blocks-storage.bucket-store.bucket-index.enabled=true`) is experimental
    65    - The block deletion marks migration support in the compactor (`-compactor.block-deletion-marks-migration-enabled`) is temporarily and will be removed in future versions
    66  - Querier: tenant federation
    67  - The thanosconvert tool for converting Thanos block metadata to Cortex
    68  - HA Tracker: cleanup of old replicas from KV Store.
    69  - Flags for configuring whether blocks-ingester streams samples or chunks are temporary, and will be removed when feature is tested:
    70    - `-ingester.stream-chunks-when-using-blocks` CLI flag
    71    - `-ingester_stream_chunks_when_using_blocks` (boolean) field in runtime config file
    72  - Instance limits in ingester and distributor
    73  - Exemplar storage, currently in-memory only within the Ingester based on Prometheus exemplar storage (`-blocks-storage.tsdb.max-exemplars`)
    74  - Querier limits:
    75    - `-querier.max-fetched-chunks-per-query`
    76    - `-querier.max-fetched-chunk-bytes-per-query`
    77    - `-querier.max-fetched-series-per-query`
    78  - Alertmanager limits
    79    - notification rate (`-alertmanager.notification-rate-limit` and `-alertmanager.notification-rate-limit-per-integration`)
    80    - dispatcher groups (`-alertmanager.max-dispatcher-aggregation-groups`)
    81    - user config size (`-alertmanager.max-config-size-bytes`)
    82    - templates count in user config (`-alertmanager.max-templates-count`)
    83    - max template size (`-alertmanager.max-template-size-bytes`)
    84  - Disabling ring heartbeat timeouts
    85    - `-distributor.ring.heartbeat-timeout=0`
    86    - `-ring.heartbeat-timeout=0`
    87    - `-ruler.ring.heartbeat-timeout=0`
    88    - `-alertmanager.sharding-ring.heartbeat-timeout=0`
    89    - `-compactor.ring.heartbeat-timeout=0`
    90    - `-store-gateway.sharding-ring.heartbeat-timeout=0`
    91  - Disabling ring heartbeats
    92    - `-distributor.ring.heartbeat-period=0`
    93    - `-ingester.heartbeat-period=0`
    94    - `-ruler.ring.heartbeat-period=0`
    95    - `-alertmanager.sharding-ring.heartbeat-period=0`
    96    - `-compactor.ring.heartbeat-period=0`
    97    - `-store-gateway.sharding-ring.heartbeat-period=0`