Update documentation to include runtime configuration #5153

CHANGELOG.md

@@ -16,6 +16,8 @@
 * [BUGFIX] Store Gateway: Fix the Parquet bucket store ignoring query sharding, which made every shard return all series. #7892
 * [BUGFIX] Querier: Fix the querier crashing instead of reporting the error when a blocks store set subservice fails. `blocksStoreReplicationSet` never initialised its `FailureWatcher`, so the failure callback dereferenced a nil pointer on the goroutine the service manager runs listeners on, and the resulting panic's stack trace buried the error logged for the actual cause. #7896
 * [BUGFIX] Compactor: Delete block deletion markers left in the global `markers/` location of a tenant after the block they refer to was removed. They were skipped at every bucket index update and kept the tenant location in the bucket forever. #7890
+* [ENHANCEMENT] Improve documentation around Runtime Overrides configuration. #5153
+* [ENHANCEMENT] Updated Contributor guide to run documentation web server locally.
 
 ## 1.22.0 in progress
 * [CHANGE] Ruler: Remove the deprecated `-ruler.evaluation-delay-duration` flag and its `ruler_evaluation_delay_duration` per-tenant limit. Use `-ruler.query-offset` / `ruler_query_offset`, which no longer takes the higher of the two values. Cortex decodes the runtime config strictly, so a leftover `ruler_evaluation_delay_duration` override makes the runtime config fail to load: Cortex **exits at startup** (`module failed`, `module=runtime-config`), and on an already-running process every reload fails, pinning the last good overrides and dropping `cortex_runtime_config_last_reload_successful` to 0. Run `grep -r ruler_evaluation_delay_duration` over your runtime configs before upgrading. #7792

Makefile

@@ -281,7 +281,7 @@ check-white-noise: clean-white-noise
 	@git diff --exit-code --quiet -- '*.md' || (echo "Please remove trailing whitespaces running 'make clean-white-noise'" && false)
 
 web-serve:
-	cd website && hugo --config config.toml --minify -v server
+	cd website && hugo --config config.toml --minify --logLevel debug server
 
 # Generate binaries for a Cortex release
 dist: dist/$(UPTODATE)

docs/configuration/config-file-reference.md

@@ -7117,6 +7117,66 @@ filesystem:
   [dir: <string> | default = ""]
 ```
 
+### `runtime_config_file`
+
+File with the configuration that can be updated in runtime.
+
+```yaml
+# Optionally Configurable limits by user through Overrides HTTP API Call
+# Full list in (https://cortexmetrics.io/docs/api/#supported-limits)
+[api_allowed_limits: <list of limits> | default = []]
+
+# Optionally configure global overrides for multiple components.
+# The limits_config configures default and per-tenant limits imposed by Cortex
+# services (ie. distributor, ingester, ...).
+[hard_overrides: <limits_config> | default = []]
+
+# Optionally configure ingester limits overrides.
+ingester_limits:
+  # Max ingestion rate (samples/sec) that this distributor will accept. This
+  # limit is per-distributor, not per-tenant. Additional push requests will be
+  # rejected. Current ingestion rate is computed as exponentially weighted
+  # moving average, updated every second. 0 = unlimited.
+  [max_ingestion_rate: <float> | default = ""]
+
+  # Max users that this ingester can hold. Requests from additional users will
+  # be rejected. This limit only works when using blocks engine. 0 = unlimited.
+  [max_tenants: <int> | default = ""]
+
+  # Max series that this ingester can hold (across all tenants). Requests to
+  # create additional series will be rejected. This limit only works when using
+  # blocks engine. 0 = unlimited.
+  [max_series: <int> | default = ""]
+
+  # Max inflight push requests that this ingester can handle (across all
+  # tenants). Additional requests will be rejected. 0 = unlimited.
+  [max_inflight_push_requests: <int> | default = ""]
+
+  # Max inflight query requests that this ingester can handle (across all
+  # tenants). Additional requests will be rejected. 0 = unlimited.
+  [max_inflight_query_requests: <int> | default = ""]
+
+# Optionally configure stream entire chunks to querier instead of individual samples to the querier.
+# This configuration options are temporary and will be removed when feature is stable #3889
+[ingester_stream_chunks_when_using_blocks: <boolean> | default = null]
+
+# Optionally configure overrides configuration to switch to a different kvstore during runtime (e.g., consule to etcd).
+# Useful during kvstore migration.
+multi_kv_config:
+  # Overrides primary backend storage used by multi-client.
+  [primary: <string> | default = ""]
+
+  # Overrides mirror writes to secondary store.
+  [mirror_enabled: <boolean> | default = false]
+
+# Optionally configure Per-tenant overrides, keyed by tenant ID.
+# The limits_config configures default and per-tenant limits imposed by Cortex
+# services (ie. distributor, ingester, ...).
+overrides:
+  [<tenant name>: <limits_config> | default = []]
+
+```
+
 ### `s3_sse_config`
 
 The `s3_sse_config` configures the S3 server-side encryption. The supported CLI flags `<prefix>` used to reference this config block are:

docs/contributing/how-to-run-website-locally.md

@@ -13,18 +13,26 @@ The Cortex documentation is compiled into a website published at [cortexmetrics.
 The following initial setup is required only once:
 
 1. Install [Hugo](https://gohugo.io/) (**extended** version)
-   * Look for value of `HUGO_VERSION` in `build-image/Dockerfile`.
-1. Install [Node.js](https://nodejs.org/en/) `v14` or above (alternatively via [`nvm`](https://github.com/nvm-sh/nvm))
+   * Look for value of `HUGO_VERSION` in `.github/workflows/web.yml`.
+1. Install [Node.js](https://nodejs.org/en/) `v26` or above (alternatively via [`nvm`](https://github.com/nvm-sh/nvm))
 1. Install required Node modules with:
+
+   ```bash
+   cd website && npm ci && cd -
    ```
-   cd website && npm install && cd -
-   ```
+
 1. Install [embedmd](https://github.com/campoy/embedmd) `v1.0.0`:
-   ```
+
+   ```bash
    go install github.com/campoy/embedmd@v1.0.0
    ```
-1. Run `make BUILD_IN_CONTAINER=false web-build`
 
+1. Run `web-pre.sh` script
+
+   ```bash
+   # must run from project root folder
+   ./tools/website/web-pre.sh
+   ```
 
 ## Run it
 
@@ -38,11 +46,12 @@ make web-serve
 Whenever you change the content of `docs/` or markdown files in the repository root `/` you should run:
 
 ```bash
-make BUILD_IN_CONTAINER=false web-pre
+# must run from project root folder
+./tools/website/web-pre.sh
 ```
 
 Whenever you change the config file or CLI flags in the Cortex code, you should rebuild the config file reference documentation:
 
 ```bash
-make BUILD_IN_CONTAINER=false doc web-pre
+make BUILD_IN_CONTAINER=false doc && ./tools/website/web-pre.sh
 ```