docs: Explain stateless addressing in Cube Store cluster

cube-js · Jul 12, 2024 · f2806da · f2806da
1 parent f439a18
commit f2806da
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 17 deletions.
diff --git a/docs/pages/product/caching/running-in-production.mdx b/docs/pages/product/caching/running-in-production.mdx
@@ -132,11 +132,11 @@ reference][ref-config-env].
 
 | Environment Variable    | Specify on Router? | Specify on Worker? |
 | ----------------------- | ------------------ | ------------------ |
-| `CUBESTORE_SERVER_NAME` | Yes                | Yes                |
-| `CUBESTORE_META_PORT`   | Yes                | -                  |
-| `CUBESTORE_WORKERS`     | Yes                | Yes                |
-| `CUBESTORE_WORKER_PORT` | -                  | Yes                |
-| `CUBESTORE_META_ADDR`   | -                  | Yes                |
+| `CUBESTORE_SERVER_NAME` | ✅ Yes              | ✅ Yes              |
+| `CUBESTORE_META_PORT`   | ✅ Yes              | —                  |
+| `CUBESTORE_WORKERS`     | ✅ Yes              | ✅ Yes              |
+| `CUBESTORE_WORKER_PORT` | —                  | ✅ Yes              |
+| `CUBESTORE_META_ADDR`   | —                  | ✅ Yes              |
 
 `CUBESTORE_WORKERS` and `CUBESTORE_META_ADDR` variables should be set with
 stable addresses, which should not change. You can use stable DNS names and put

diff --git a/docs/pages/product/deployment.mdx b/docs/pages/product/deployment.mdx
@@ -107,11 +107,11 @@ following environment variables should be used to manage the roles:
 
 | Environment Variable    | Specify on Router? | Specify on Worker? |
 | ----------------------- | ------------------ | ------------------ |
-| `CUBESTORE_SERVER_NAME` | Yes                | Yes                |
-| `CUBESTORE_META_PORT`   | Yes                | -                  |
-| `CUBESTORE_WORKERS`     | Yes                | Yes                |
-| `CUBESTORE_WORKER_PORT` | -                  | Yes                |
-| `CUBESTORE_META_ADDR`   | -                  | Yes                |
+| `CUBESTORE_SERVER_NAME` | ✅ Yes              | ✅ Yes              |
+| `CUBESTORE_META_PORT`   | ✅ Yes              | —                  |
+| `CUBESTORE_WORKERS`     | ✅ Yes              | ✅ Yes              |
+| `CUBESTORE_WORKER_PORT` | —                  | ✅ Yes              |
+| `CUBESTORE_META_ADDR`   | —                  | ✅ Yes              |
 
 <InfoBox>
 

diff --git a/docs/pages/reference/configuration/environment-variables.mdx b/docs/pages/reference/configuration/environment-variables.mdx
@@ -1282,16 +1282,16 @@ The logging level for Cube Store.
 
 ## `CUBESTORE_META_ADDR`
 
-The address/port pair for the **router** node in the cluster.
+The address/port pair for the Cube Store **router** node in the cluster.
 
 | Possible Values           | Default in Development | Default in Production |
 | ------------------------- | ---------------------- | --------------------- |
 | A valid address/port pair | N/A                    | N/A                   |
 
 ## `CUBESTORE_META_PORT`
 
-The port for the **router** node to listen for connections on. Ignored when
-`CUBESTORE_META_ADDR` is set.
+The port for the Cube Store **router** node to listen for connections on.
+Ignored when `CUBESTORE_META_ADDR` is set.
 
 | Possible Values     | Default in Development | Default in Production |
 | ------------------- | ---------------------- | --------------------- |
@@ -1418,8 +1418,10 @@ The number of Cube Store sub-processes that handle `SELECT` queries.
 
 ## `CUBESTORE_SERVER_NAME`
 
-The full name and port number of the Cube Store server. Must be unique for each
-instance in cluster mode.
+The full name and port number of the Cube Store node (either the router
+or a worker). Must be unique for each instance in the Cube Store cluster.
+
+Should be passed to the Cube Store router and to each Cube Store worker.
 
 | Possible Values           | Default in Development | Default in Production |
 | ------------------------- | ---------------------- | --------------------- |
@@ -1445,15 +1447,17 @@ insertion.
 ## `CUBESTORE_WORKER_PORT`
 
 The port for Cube Store workers to listen to connections on. When set, the node
-will start as a **worker** in the cluster
+will start as a Cube Store **worker** in the cluster
 
 | Possible Values     | Default in Development | Default in Production |
 | ------------------- | ---------------------- | --------------------- |
 | A valid port number | N/A                    | N/A                   |
 
 ## `CUBESTORE_WORKERS`
 
-A comma-separated list of address/port pairs for Cube Store workers.
+A comma-separated list of address/port pairs of Cube Store workers.
+
+Should be passed to the Cube Store router and to each Cube Store worker.
 
 | Possible Values                              | Default in Development | Default in Production |
 | -------------------------------------------- | ---------------------- | --------------------- |
@@ -1463,6 +1467,12 @@ A comma-separated list of address/port pairs for Cube Store workers.
 CUBESTORE_WORKERS=worker-1:3123,localhost:3124,123.124.125.128:3123
 ```
 
+Used to implement stateless addressing within a Cube Store cluster.
+By analyzing `CUBESTORE_WORKERS` and `CUBESTORE_SERVER_NAME`, each node
+is able to determine its position within a Cube Store cluster.
+This allows each worker to know which pre-aggregation partitions it owns
+and how the load is distributed across all workers.
+
 ## `DEBUG_LOG`
 
 If `true`, enables debug logging.