diff --git a/reference/configuration/operations.md b/reference/configuration/operations.md index 109bb8c5..43f94271 100644 --- a/reference/configuration/operations.md +++ b/reference/configuration/operations.md @@ -20,8 +20,14 @@ Modifies one or more Harper configuration parameters. **Requires a [restart](../ `operation` _(required)_ — must be `set_configuration` +`replicated` _(optional)_ — set to `true` to apply the same configuration change to all cluster nodes in a single call. The origin node applies the change first; if its local write fails, nothing is sent to peers. Requires replication to be configured. + Additional properties correspond to configuration keys in underscore-separated format (e.g. `logging_level` for `logging.level`, `clustering_enabled` for `clustering.enabled`). +:::warning Replicate cluster-appropriate parameters only +A replicated call sends the exact same values to every node. Do not include node-local parameters — ports, `node.hostname`, `rootPath`, storage/log file paths, TLS certificate or key paths, or `replication.hostname`/`url`/`routes` — as they would overwrite each peer's local values. +::: + ### Body ```json @@ -40,6 +46,42 @@ Additional properties correspond to configuration keys in underscore-separated f } ``` +### Replicated body + +```json +{ + "operation": "set_configuration", + "http_corsAccessList": ["app.example.com"], + "replicated": true +} +``` + +### Response: 200 (replicated) + +The `replicated` array reports per-node outcomes. A failed peer appears as `{ "status": "failed", "reason": "...", "node": "..." }` while `message` still reports overall success — always check the array when replicating. + +```json +{ + "message": "Configuration successfully set. You must restart Harper for new config settings to take effect.", + "replicated": [ + { + "message": "Configuration successfully set. You must restart Harper for new config settings to take effect.", + "node": "node-2" + } + ] +} +``` + +To restart the whole cluster afterward, follow with [restart_service](../operations-api/operations.md#restart_service) using `"replicated": true` — it restarts nodes one at a time, so the cluster stays available: + +```json +{ + "operation": "restart_service", + "service": "http", + "replicated": true +} +``` + --- ## Get Configuration diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index d755a047..59235f55 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -795,11 +795,13 @@ Detailed documentation: [Configuration Overview](../configuration/overview.md) Updates configuration parameters in `harper-config.yaml`. A restart (`restart` or `restart_service`) is required for changes to take effect. +Supports `"replicated": true` to apply the same change to all cluster nodes in one call; per-node outcomes are returned in the response's `replicated` array. Only send cluster-appropriate parameters when replicating — node-local parameters (ports, `node.hostname`, file paths, TLS material, `replication.hostname`/`url`/`routes`) would overwrite every peer's local values. To apply the change cluster-wide, follow with `restart_service` using `"replicated": true` (which restarts nodes one at a time). See [Configuration Operations](../configuration/operations.md#set-configuration) for details. + ```json { "operation": "set_configuration", "logging_level": "trace", - "clustering_enabled": true + "replicated": true } ``` @@ -836,7 +838,7 @@ Restarts all Harper processes. May take up to 60 seconds. ### `restart_service` -Restarts a specific service. `service` must be one of: `http_workers`, `clustering_config`, `clustering`. Supports `"replicated": true` for a rolling cluster restart. +Restarts a specific service. `service` must be one of: `http`, `http_workers`, `custom_functions`, `harperdb` (all currently restart the HTTP workers). Supports `"replicated": true` for a rolling cluster restart. ```json { "operation": "restart_service", "service": "http_workers" } diff --git a/release-notes/v5-lincoln/5.1.md b/release-notes/v5-lincoln/5.1.md index cfc7aa9d..1a07ed65 100644 --- a/release-notes/v5-lincoln/5.1.md +++ b/release-notes/v5-lincoln/5.1.md @@ -203,6 +203,10 @@ This is useful for node-local state — per-node counters, cache metadata, or an ## Configuration +### Replicated `set_configuration` + +The `set_configuration` operation now accepts `"replicated": true` to apply a configuration change to all cluster nodes in a single Operations API call, with per-node outcomes reported in the response's `replicated` array. Only cluster-appropriate parameters should be replicated — see [Configuration Operations](/reference/v5/configuration/operations#set-configuration). + ### `HARPER_CONFIG` environment variable `HARPER_CONFIG` is now the recommended way to specify the configuration file location: