From c9cd58d4af6088748aa84c929b3a925e81369e05 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Fri, 17 May 2024 15:25:01 -0500 Subject: [PATCH 1/5] DOC-3669 RS: Add REST API reference for /services --- .../rest-api/requests/services/_index.md | 210 ++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 content/operate/rs/references/rest-api/requests/services/_index.md diff --git a/content/operate/rs/references/rest-api/requests/services/_index.md b/content/operate/rs/references/rest-api/requests/services/_index.md new file mode 100644 index 0000000000..9aec8b23fb --- /dev/null +++ b/content/operate/rs/references/rest-api/requests/services/_index.md @@ -0,0 +1,210 @@ +--- +Title: Services requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests to list or modify Redis Enterprise services. +headerRange: '[1-2]' +hideListLinks: true +linkTitle: services +weight: $weight +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-local-services) | `/v1/local/services` | List Redis Enterprise services on the local node | +| [POST](#post-local-services) | `/v1/local/services` | Modify or perform operations on local processes | +| [POST](#post-services) | `/v1/services` | Apply cluster-wide changes to services | + +## Get local services {#get-local-services} + +```sh +GET /v1/local/services +``` + +Lists all Redis Enterprise services currently running on the local node and relevant metadata. + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /local/services +``` + + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +### Response {#get-response} + +Returns a JSON object that describes all Redis Enterprise services currently running on the local node and relevant metadata. + +Possible `status` values: +- RESTARTING +- RUNNING +- STARTING +- STOPPED + +#### Example JSON response body + +```json +{ + "alert_mgr": { + "start_time": "2024-05-13T18:38:00Z", + "status": "RUNNING", + "uptime": "3 days, 0:58:59" + }, + "ccs": { + "start_time": "2024-05-13T18:38:59Z", + "status": "RUNNING", + "uptime": "3 days, 0:58:00" + }, + ... +} +``` + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Modify local services {#post-local-services} + +```sh +POST /v1/local/services +``` + +Modify Redis Enterprise services or perform operations that directly interact with processes. + +Supported `operation_type` values: +- start +- stop +- restart +- kill +- change_watchdog_profile: deprecated, use [`PUT /v1/cluster/policy`]({{}}) to set `failure_detection_sensitivity` to `high` or `low` instead instead. + +For cluster-wide changes that are not node-specific, use [`POST /v1/services`](#post-services) instead. + + +### Request {#post-local-request} + +#### Example HTTP request + +```sh +POST /local/services +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### Example JSON request body + +```json +{ + "operation_type": "restart", + "services": [ + "alert_mgr", + "metrics_exporter" + ] +} +``` + +### Response {#post-local-response} + +Returns a JSON object that shows whether the operation ran successfully or failed for each requested service. + +#### Example JSON response body + +```json +{ + "alert_mgr": true, + "metrics_exporter": true +} +``` + + +#### Status codes {#post-local-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error. | + +## Apply cluster-wide service changes {#post-services} + +```sh +POST /v1/services +``` + +Makes cluster-wide changes that are not node-specific on Redis Enterprise services. The master node handles these changes. + +Supported `operation_type` values: +- start +- stop +- restart +- kill +- change_watchdog_profile: deprecated, use [`PUT /v1/cluster/policy`]({{}}) to set `failure_detection_sensitivity` to `high` or `low` instead instead. + +For operations that directly interact with processes, use [`POST /v1/local/services`](#post-local-services) instead. + + +### Request {#post-request} + +#### Example HTTP request + +```sh +POST /services +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### Example JSON request body + +```json +{ + "operation_type": "restart", + "services": [ + "alert_mgr", + "metrics_exporter" + ] +} +``` + +### Response {#post-response} + +Returns a JSON object that shows whether the operation ran successfully or failed for each requested service. + +#### Example JSON response body + +```json +{ + "alert_mgr": true, + "metrics_exporter": true +} +``` + + +#### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error. | \ No newline at end of file From 8cbb5caa03ab064dd463cca86f650262770e205f Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Wed, 12 Feb 2025 09:49:01 -0600 Subject: [PATCH 2/5] DOC-3669 Feedback update - only list start, stop, restart operations for services API --- .../rs/references/rest-api/requests/services/_index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/operate/rs/references/rest-api/requests/services/_index.md b/content/operate/rs/references/rest-api/requests/services/_index.md index 9aec8b23fb..2aaab4f21e 100644 --- a/content/operate/rs/references/rest-api/requests/services/_index.md +++ b/content/operate/rs/references/rest-api/requests/services/_index.md @@ -89,8 +89,6 @@ Supported `operation_type` values: - start - stop - restart -- kill -- change_watchdog_profile: deprecated, use [`PUT /v1/cluster/policy`]({{}}) to set `failure_detection_sensitivity` to `high` or `low` instead instead. For cluster-wide changes that are not node-specific, use [`POST /v1/services`](#post-services) instead. @@ -155,8 +153,6 @@ Supported `operation_type` values: - start - stop - restart -- kill -- change_watchdog_profile: deprecated, use [`PUT /v1/cluster/policy`]({{}}) to set `failure_detection_sensitivity` to `high` or `low` instead instead. For operations that directly interact with processes, use [`POST /v1/local/services`](#post-local-services) instead. From cb6656eb1589a3d26e0d0be1ef178ba82edf3c95 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Wed, 12 Feb 2025 14:20:30 -0600 Subject: [PATCH 3/5] DOC-3669 Feedback update to note the POST services request should be used for optional services only --- .../rest-api/requests/services/_index.md | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/content/operate/rs/references/rest-api/requests/services/_index.md b/content/operate/rs/references/rest-api/requests/services/_index.md index 2aaab4f21e..9d86a72912 100644 --- a/content/operate/rs/references/rest-api/requests/services/_index.md +++ b/content/operate/rs/references/rest-api/requests/services/_index.md @@ -83,15 +83,19 @@ Possible `status` values: POST /v1/local/services ``` -Modify Redis Enterprise services or perform operations that directly interact with processes. +Modify Redis Enterprise services or perform operations that directly interact with processes. For cluster-wide changes that are not node-specific, use [`POST /v1/services`](#post-services) instead. + +Supported `operation_type` values: -Supported `operation_type` values: -- start - stop +- start - restart -For cluster-wide changes that are not node-specific, use [`POST /v1/services`](#post-services) instead. +{{}} +Stop, start, or restart optional services only. Changing the status of required services can affect cluster behavior. +For a list of optional services, see the [services configuration object reference]({{}}) or use a [`GET /v1/cluster/services_configuration`]({{}}) request. +{{}} ### Request {#post-local-request} @@ -115,8 +119,7 @@ POST /local/services { "operation_type": "restart", "services": [ - "alert_mgr", - "metrics_exporter" + "alert_mgr" ] } ``` @@ -147,15 +150,19 @@ Returns a JSON object that shows whether the operation ran successfully or faile POST /v1/services ``` -Makes cluster-wide changes that are not node-specific on Redis Enterprise services. The master node handles these changes. +Makes cluster-wide changes that are not node-specific on Redis Enterprise services. The master node handles these changes. For operations that directly interact with processes, use [`POST /v1/local/services`](#post-local-services) instead. + +Supported `operation_type` values: -Supported `operation_type` values: -- start - stop +- start - restart -For operations that directly interact with processes, use [`POST /v1/local/services`](#post-local-services) instead. +{{}} +Stop, start, or restart optional services only. Changing the status of required services can affect cluster behavior. +For a list of optional services, see the [services configuration object reference]({{}}) or use a [`GET /v1/cluster/services_configuration`]({{}}) request. +{{}} ### Request {#post-request} @@ -179,8 +186,7 @@ POST /services { "operation_type": "restart", "services": [ - "alert_mgr", - "metrics_exporter" + "alert_mgr" ] } ``` From c98ffbd69af51f3d90a03d8d3e98064b3afaa3dc Mon Sep 17 00:00:00 2001 From: Rachel Elledge <86307637+rrelledge@users.noreply.github.com> Date: Fri, 14 Feb 2025 10:45:17 -0600 Subject: [PATCH 4/5] Fix 200 OK links --- .../rs/references/rest-api/requests/services/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/operate/rs/references/rest-api/requests/services/_index.md b/content/operate/rs/references/rest-api/requests/services/_index.md index 9d86a72912..fc77b7391d 100644 --- a/content/operate/rs/references/rest-api/requests/services/_index.md +++ b/content/operate/rs/references/rest-api/requests/services/_index.md @@ -75,7 +75,7 @@ Possible `status` values: | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error | ## Modify local services {#post-local-services} @@ -142,7 +142,7 @@ Returns a JSON object that shows whether the operation ran successfully or faile | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error. | +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | ## Apply cluster-wide service changes {#post-services} @@ -209,4 +209,4 @@ Returns a JSON object that shows whether the operation ran successfully or faile | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error. | \ No newline at end of file +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | From 47fbff12d6a0353b2788ccad36f844bba1e678cb Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Mon, 24 Feb 2025 11:37:34 -0600 Subject: [PATCH 5/5] DOC-3669 Feedback update to emphasize the warning that this API is dangerous --- .../rest-api/requests/services/_index.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/content/operate/rs/references/rest-api/requests/services/_index.md b/content/operate/rs/references/rest-api/requests/services/_index.md index fc77b7391d..90dffe650c 100644 --- a/content/operate/rs/references/rest-api/requests/services/_index.md +++ b/content/operate/rs/references/rest-api/requests/services/_index.md @@ -18,6 +18,14 @@ weight: $weight | [POST](#post-local-services) | `/v1/local/services` | Modify or perform operations on local processes | | [POST](#post-services) | `/v1/services` | Apply cluster-wide changes to services | +{{}} +This API is dangerous and should only be run with guidance from [Redis support](https://redis.io/support/). + +Stop, start, or restart optional services only. Changing the status of required services can negatively affect cluster behavior and cause a complete loss of the cluster and its data. + +For a list of optional services, see the [services configuration object reference]({{}}) or use a [`GET /v1/cluster/services_configuration`]({{}}) request. +{{}} + ## Get local services {#get-local-services} ```sh @@ -92,7 +100,9 @@ Supported `operation_type` values: - restart {{}} -Stop, start, or restart optional services only. Changing the status of required services can affect cluster behavior. +This API is dangerous and should only be run with guidance from [Redis support](https://redis.io/support/). + +Stop, start, or restart optional services only. Changing the status of required services can negatively affect cluster behavior and cause a complete loss of the cluster and its data. For a list of optional services, see the [services configuration object reference]({{}}) or use a [`GET /v1/cluster/services_configuration`]({{}}) request. {{}} @@ -159,7 +169,9 @@ Supported `operation_type` values: - restart {{}} -Stop, start, or restart optional services only. Changing the status of required services can affect cluster behavior. +This API is dangerous and should only be run with guidance from [Redis support](https://redis.io/support/). + +Stop, start, or restart optional services only. Changing the status of required services can negatively affect cluster behavior and cause a complete loss of the cluster and its data. For a list of optional services, see the [services configuration object reference]({{}}) or use a [`GET /v1/cluster/services_configuration`]({{}}) request. {{}}