From bcb080179c941c090499f6b16f5561b10c410cd5 Mon Sep 17 00:00:00 2001 From: Michael Klishin Date: Tue, 7 Jan 2025 18:48:39 -0500 Subject: [PATCH 1/3] Improve documentation of certain health checks in the HTTP API documentation reference as well as one CLI command that apparently needed a clarification. --- .../check_certificate_expiration_command.ex | 11 +- .../priv/www/api/index.html | 144 +++++++++++++----- 2 files changed, 111 insertions(+), 44 deletions(-) diff --git a/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex b/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex index 0b70ef4ccf5..a38200639e2 100644 --- a/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex +++ b/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex @@ -7,10 +7,12 @@ defmodule RabbitMQ.CLI.Diagnostics.Commands.CheckCertificateExpirationCommand do alias RabbitMQ.CLI.Core.DocGuide alias RabbitMQ.CLI.TimeUnit, as: TU - @behaviour RabbitMQ.CLI.CommandBehaviour + import RabbitMQ.CLI.Core.Platform, only: [line_separator: 0] import RabbitMQ.CLI.Core.Listeners + @behaviour RabbitMQ.CLI.CommandBehaviour + def switches(), do: [unit: :string, within: :integer] def merge_defaults(args, opts) do @@ -102,9 +104,10 @@ defmodule RabbitMQ.CLI.Diagnostics.Commands.CheckCertificateExpirationCommand do def help_section(), do: :observability_and_health_checks - def description(), - do: "Checks the expiration date on the certificates for every listener configured to use TLS" + def description() do + "Checks the expiration date of every certificate (leaf, intermediary or any CA) in every certificate bundle file used by the node" + end def banner(_, %{node: node_name}), - do: "Checking certificate expiration on node #{node_name} ..." + do: "Checking certificate expiration for all certificates on node #{node_name} ..." end diff --git a/deps/rabbitmq_management/priv/www/api/index.html b/deps/rabbitmq_management/priv/www/api/index.html index d7e4a4a5214..302d7b656ef 100644 --- a/deps/rabbitmq_management/priv/www/api/index.html +++ b/deps/rabbitmq_management/priv/www/api/index.html @@ -492,11 +492,20 @@

Reference

/api/queues - A list of all queues returning a reduced set of fields. Use pagination parameters to filter queues. - The parameter enable_queue_totals=true can be used in combination with the - disable_stats=true parameter to return a reduced set of fields and significantly - reduce the amount of data returned by this endpoint. That in turn can significantly reduce - CPU and bandwidth footprint of such requests. + +

+ A list of all queues across all virtual hosts returning a reduced set of fields. +

+

+ Use pagination parameters to filter queues, + otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. +

+

+ The parameter enable_queue_totals=true can be used in combination with the + disable_stats=true parameter to return a reduced set of fields and significantly + reduce the amount of data returned by this endpoint. That in turn can significantly reduce + CPU and bandwidth footprint of such requests. +

@@ -505,7 +514,14 @@

Reference

/api/queues/detailed - A list of all queues containing all available information about the queues. Use pagination parameters to filter queues. + +

+ A list of all queues containing all available information about the queues (over 50 fields per queue). +

+

+ Use pagination parameters to filter queues, + otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. +

@@ -514,7 +530,15 @@

Reference

/api/queues/vhost - A list of all queues in a given virtual host. Use pagination parameters to filter queues. + +

+ A list of all queues in the given virtual host containing all available information about the queues (over 50 fields per queue).. +

+

+ Use pagination parameters to filter queues, + otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. +

+ X @@ -524,7 +548,7 @@

Reference

/api/queues/vhost/name An individual queue. To PUT a queue, you will need a body looking something like this: - 
{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@smacmullen"}
+ 
{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@node.hostname"}
All keys are optional.

When DELETEing a queue you can add the query string @@ -990,19 +1014,6 @@

Reference

pattern and definition are mandatory, priority and apply-to are optional. - - X - - - - /api/aliveness-test/vhost - - Declares a test queue on the target node, then publishes and consumes a - message. Intended to be used as a very basic health check. - Responds a 200 OK if the check succeeded, - otherwise responds with a 503 Service Unavailable. - - X @@ -1010,8 +1021,14 @@

Reference

/api/health/checks/alarms - Responds a 200 OK if there are no alarms in effect in the cluster, - otherwise responds with a 503 Service Unavailable. +

+ Responds a 200 OK if there are no alarms in effect in the cluster, + otherwise responds with a 503 Service Unavailable. +

+ +

+ Relevant documentation guide: Resource Alarms +

@@ -1021,8 +1038,13 @@

Reference

/api/health/checks/local-alarms - Responds a 200 OK if there are no local alarms in effect on the target node, - otherwise responds with a 503 Service Unavailable. +

+ Responds a 200 OK if there are no local alarms in effect on the target node, + otherwise responds with a 503 Service Unavailable. +

+

+ Relevant documentation guide: Resource Alarms +

@@ -1033,15 +1055,32 @@

Reference

/api/health/checks/certificate-expiration/within/unit

- Checks the expiration date on the certificates for every listener configured to use TLS. + Checks the expiration date of every certificate found in the PEM certificate bundles used by + all TLS-enabled listeners on the node, regardless of the "type" of the certificate (leaf/server identity, + intermediary or any CA). +

+

Responds a 200 OK if all certificates are valid (have not expired), otherwise responds with a 503 Service Unavailable.

+

+ This health assumes that + +

+ + Do not use this health check if some of these assumptions are not true. +

Valid units: days, weeks, months, years. The value of the within argument is the number of units. So, when within is 2 and unit is "months", the expiration period used by the check will be the next two months.

+

+ Relevant documentation guide: TLS +

@@ -1051,7 +1090,7 @@

Reference

/api/health/checks/port-listener/port - Responds a 200 OK if there is an active listener on the give port, + Responds a 200 OK if there is an active listener on the given port, otherwise responds with a 503 Service Unavailable. @@ -1084,10 +1123,15 @@

Reference

/api/health/checks/node-is-quorum-critical - Checks if there are quorum queues with minimum online quorum (queues that - would lose their quorum and availability if the target node is shut down). - Responds a 200 OK if there are no such quorum queues, - otherwise responds with a 503 Service Unavailable. +

+ Checks if there are quorum queues with minimum online quorum (queues that + would lose their quorum and availability if the target node is shut down). + Responds a 200 OK if there are no such quorum queues, + otherwise responds with a 503 Service Unavailable. +

+

+ Relevant documentation guide: Quorum Queues +

@@ -1117,11 +1161,15 @@

Reference

/api/vhost-limits/vhost/name - Set or delete per-vhost limit for vhost. The name URL path element - refers to the name of the limit (max-connections, max-queues). - Limits are set using a JSON document in the body: 
{"value": 100}
. Example - request:
- 
curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/vhost-limits/my-vhost/max-connections -d '{"value": 50}'
+

+ Set or delete per-vhost limit for vhost. The name URL path element + refers to the name of the limit (max-connections, max-queues). + Limits are set using a JSON document in the body: 

{"value": 100}
. Example request:
+ 
curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/vhost-limits/my-vhost/max-connections -d '{"value": 50}'
+

+

+ Relevant documentation guide: Virtual Hosts +

@@ -1142,7 +1190,7 @@

Reference

X /api/rebalance/queues - Rebalances all queues in all vhosts. This operation is asynchronous therefore please check + Rebalances all queues in all vhosts. This operation is asynchronous therefore please check the RabbitMQ log file for messages regarding the success or failure of the operation. 
curl -4u 'guest:guest' -XPOST localhost:15672/api/rebalance/queues/
@@ -1306,9 +1354,10 @@

Reference

/api/stream/consumers/vhost - The list of stream consumers in a specific virtual host. -
+

The list of stream consumers in a specific virtual host.

+

Requires the rabbitmq_stream_management plugin to be enabled. +

@@ -1318,7 +1367,12 @@

Reference

/api/feature-flags - The list of feature flags. +

+ The list of feature flags. +

+

+ Relevant documentation guide: Feature Flags +

@@ -1328,7 +1382,12 @@

Reference

/api/deprecated-features +

The list of deprecated features. +

+

+ Relevant documentation guide: Feature Flags +

@@ -1338,7 +1397,12 @@

Reference

/api/deprecated-features/used +

The list of deprecated features currently being used. +

+

+ Relevant documentation guide: Feature Flags +

From 5c7d643ab341e5f8f5be4a14b82aa4a7aaf3991d Mon Sep 17 00:00:00 2001 From: Michael Klishin Date: Tue, 7 Jan 2025 18:50:02 -0500 Subject: [PATCH 2/3] CLI: drop an unused import --- .../diagnostics/commands/check_certificate_expiration_command.ex | 1 - 1 file changed, 1 deletion(-) diff --git a/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex b/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex index a38200639e2..a47ff0bd776 100644 --- a/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex +++ b/deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex @@ -8,7 +8,6 @@ defmodule RabbitMQ.CLI.Diagnostics.Commands.CheckCertificateExpirationCommand do alias RabbitMQ.CLI.Core.DocGuide alias RabbitMQ.CLI.TimeUnit, as: TU - import RabbitMQ.CLI.Core.Platform, only: [line_separator: 0] import RabbitMQ.CLI.Core.Listeners @behaviour RabbitMQ.CLI.CommandBehaviour From 48aa250006a169d5676cb51f546f8ebc329a0044 Mon Sep 17 00:00:00 2001 From: Michael Klishin Date: Tue, 7 Jan 2025 19:27:27 -0500 Subject: [PATCH 3/3] HTTP API reference: fix a typo --- deps/rabbitmq_management/priv/www/api/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deps/rabbitmq_management/priv/www/api/index.html b/deps/rabbitmq_management/priv/www/api/index.html index 302d7b656ef..5088bfe88e8 100644 --- a/deps/rabbitmq_management/priv/www/api/index.html +++ b/deps/rabbitmq_management/priv/www/api/index.html @@ -1386,7 +1386,7 @@

Reference

The list of deprecated features.

- Relevant documentation guide: Feature Flags + Relevant documentation guide: Deprecated Features

@@ -1401,7 +1401,7 @@

Reference

The list of deprecated features currently being used.

- Relevant documentation guide: Feature Flags + Relevant documentation guide: Deprecated Features