Documented blocks storage index cache backends

Signed-off-by: Marco Pracucci <[email protected]>

docs/operations/blocks-storage.md

@@ -72,6 +72,37 @@ Whenever the pool of compactors increase or decrease (ie. following up a scale u
 - `GET /compactor_ring`<br />
   Displays the status of the compactors ring, including the tokens owned by each compactor and an option to remove (forget) instances from the ring.
 
+## Index cache
+
+The querier supports a cache to speed up postings and series lookups from TSDB blocks indexes. Two types of caches are supported:
+
+- `inmemory`
+- `memcached`
+
+### In-memory index cache
+
+The `inmemory` index cache is **enabled by default** and its max size can be configured through the flag `-experimental.tsdb.bucket-store.index-cache.inmemory.max-size-bytes` (or config file). The trade-off of using the in-memory index cache is:
+
+- Pros: zero latency
+- Cons: increases querier memory usage, not shared across multiple querier replicas
+
+### Memcached index cache
+
+The `memcached` index cache allows to use [Memcached](https://memcached.org/) as cache backend. This cache type is configured using `-experimental.tsdb.bucket-store.index-cache.backend=memcached` and requires the Memcached server(s) addresses via `-experimental.tsdb.bucket-store.index-cache.memcached.addresses` (or config file). The addresses are resolved using the [DNS service provider](dns-service-discovery.md).
+
+The trade-off of using the Memcached index cache is:
+
+- Pros: can scale beyond a single node memory (Memcached cluster), shared across multiple querier instances
+- Cons: higher latency in the cache round trip compared to the in-memory one
+
+The Memcached client uses a jump hash algorithm to shard cached entries across a cluster of Memcached servers. For this reason, you should make sure memcached servers are **not** behind any kind of load balancer and their address is configured so that servers are added/removed to the end of the list whenever a scale up/down occurs.
+
+For example, if you're running Memcached in Kubernetes, you may:
+
+1. Deploy your Memcached cluster using a [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)
+2. Create an [headless service](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services) for Memcached StatefulSet
+3. Configure the Cortex's Memcached client address using the `dnssrvnoa+` [service discovery](dns-service-discovery.md)
+
 ## Configuration
 
 The general [configuration documentation](../configuration/_index.md) also applied to a Cortex cluster running the blocks storage, with few differences:

docs/operations/dns-service-discovery.md

@@ -0,0 +1,21 @@
+---
+title: "DNS service discovery"
+linkTitle: "DNS service discovery"
+weight: 2
+slug: dns-service-discovery
+---
+
+Cortex supports a DNS service discovery to discover addresses of backend servers to connect to (ie. caching servers). This service discovery is not widely supported in Cortex yet. The clients supporting it are:
+
+- [Blocks storage's memcached index cache](blocks-storage.md#memcached-index-cache)
+
+## Supported discovery modes
+
+The DNS service discovery supports different discovery modes. A discovery mode is selected adding a specific prefix to the address. The supported prefixes are:
+
+- **`dns+`**<br />
+  The domain name after the prefix is looked up as an A/AAAA query. For example: `dns+memcached.local:11211`
+- **`dnssrv+`**<br />
+  The domain name after the prefix is looked up as a SRV query, and then each SRV record is resolved as an A/AAAA record. For example: `dnssrv+memcached.namespace.svc.cluster.local`
+- **`dnssrvnoa+`**<br />
+  The domain name after the prefix is looked up as a SRV query, with no A/AAAA lookup made after that. For example: `dnssrvnoa+memcached.namespace.svc.cluster.local`

docs/operations/query-auditor.md

@@ -1,7 +1,7 @@
 ---
 title: "Query Auditor (tool)"
 linkTitle: "Query Auditor (tool)"
-weight: 2
+weight: 3
 slug: query-auditor
 ---
 

docs/operations/query-tee.md

@@ -1,7 +1,7 @@
 ---
 title: "Query Tee (service)"
 linkTitle: "Query Tee (service)"
-weight: 3
+weight: 4
 slug: query-tee
 ---