Skip to content

Commit bcb0801

Browse files
michaelklishinmichaelklishin
committed
Improve documentation of certain health checks
in the HTTP API documentation reference as well as one CLI command that apparently needed a clarification.
1 parent 21c2422 commit bcb0801

File tree

2 files changed

+111
-44
lines changed

2 files changed

+111
-44
lines changed

‎deps/rabbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex

+7-4
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,12 @@
77
defmodule RabbitMQ.CLI.Diagnostics.Commands.CheckCertificateExpirationCommand do
88
alias RabbitMQ.CLI.Core.DocGuide
99
alias RabbitMQ.CLI.TimeUnit, as: TU
10-
@behaviour RabbitMQ.CLI.CommandBehaviour
1110

11+
import RabbitMQ.CLI.Core.Platform, only: [line_separator: 0]
1212
import RabbitMQ.CLI.Core.Listeners
1313

14+
@behaviour RabbitMQ.CLI.CommandBehaviour
15+
1416
def switches(), do: [unit: :string, within: :integer]
1517

1618
def merge_defaults(args, opts) do
@@ -102,9 +104,10 @@ defmodule RabbitMQ.CLI.Diagnostics.Commands.CheckCertificateExpirationCommand do
102104

103105
def help_section(), do: :observability_and_health_checks
104106

105-
def description(),
106-
do: "Checks the expiration date on the certificates for every listener configured to use TLS"
107+
def description() do
108+
"Checks the expiration date of every certificate (leaf, intermediary or any CA) in every certificate bundle file used by the node"
109+
end
107110

108111
def banner(_, %{node: node_name}),
109-
do: "Checking certificate expiration on node #{node_name} ..."
112+
do: "Checking certificate expiration for all certificates on node #{node_name} ..."
110113
end

‎deps/rabbitmq_management/priv/www/api/index.html

+104-40
Original file line numberDiff line numberDiff line change
@@ -492,11 +492,20 @@ <h2>Reference</h2>
492492
<td></td>
493493
<td></td>
494494
<td class="path">/api/queues</td>
495-
<td>A list of all queues returning a reduced set of fields. Use <a href="#pagination">pagination parameters</a> to filter queues.
496-
The parameter <code>enable_queue_totals=true</code> can be used in combination with the
497-
<code>disable_stats=true</code> parameter to return a reduced set of fields and significantly
498-
reduce the amount of data returned by this endpoint. That in turn can significantly reduce
499-
CPU and bandwidth footprint of such requests.
495+
<td>
496+
<p>
497+
A list of all queues across all virtual hosts returning a reduced set of fields.
498+
</p>
499+
<p>
500+
Use <a href="#pagination">pagination parameters</a> to filter queues,
501+
otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources.
502+
</p>
503+
<p>
504+
The parameter <code>enable_queue_totals=true</code> can be used in combination with the
505+
<code>disable_stats=true</code> parameter to return a reduced set of fields and significantly
506+
reduce the amount of data returned by this endpoint. That in turn can significantly reduce
507+
CPU and bandwidth footprint of such requests.
508+
</p>
500509
</td>
501510
</tr>
502511
<tr>
@@ -505,7 +514,14 @@ <h2>Reference</h2>
505514
<td></td>
506515
<td></td>
507516
<td class="path">/api/queues/detailed</td>
508-
<td>A list of all queues containing all available information about the queues. Use <a href="#pagination">pagination parameters</a> to filter queues.
517+
<td>
518+
<p>
519+
A list of all queues containing all available information about the queues (over 50 fields per queue).
520+
</p>
521+
<p>
522+
Use <a href="#pagination">pagination parameters</a> to filter queues,
523+
otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources.
524+
</p>
509525
</td>
510526
</tr>
511527
<tr>
@@ -514,7 +530,15 @@ <h2>Reference</h2>
514530
<td></td>
515531
<td></td>
516532
<td class="path">/api/queues/<i>vhost</i></td>
517-
<td>A list of all queues in a given virtual host. Use <a href="#pagination">pagination parameters</a> to filter queues.</td>
533+
<td>
534+
<p>
535+
A list of all queues in the given virtual host containing all available information about the queues (over 50 fields per queue)..
536+
</p>
537+
<p>
538+
Use <a href="#pagination">pagination parameters</a> to filter queues,
539+
otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources.
540+
</p>
541+
</td>
518542
</tr>
519543
<tr>
520544
<td>X</td>
@@ -524,7 +548,7 @@ <h2>Reference</h2>
524548
<td class="path">/api/queues/<i>vhost</i>/<i>name</i></td>
525549
<td>
526550
An individual queue. To PUT a queue, you will need a body looking something like this:
527-
<pre>{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@smacmullen"}</pre>
551+
<pre>{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@node.hostname"}</pre>
528552
All keys are optional.
529553
<p>
530554
When DELETEing a queue you can add the query string
@@ -990,28 +1014,21 @@ <h2>Reference</h2>
9901014
<code>pattern</code> and <code>definition</code> are mandatory, <code>priority</code> and <code>apply-to</code> are optional.
9911015
</td>
9921016
</tr>
993-
<tr>
994-
<td>X</td>
995-
<td></td>
996-
<td></td>
997-
<td></td>
998-
<td class="path">/api/aliveness-test/<i>vhost</i></td>
999-
<td>
1000-
Declares a test queue on the target node, then publishes and consumes a
1001-
message. Intended to be used as a very basic health check.
1002-
Responds a 200 OK if the check succeeded,
1003-
otherwise responds with a 503 Service Unavailable.
1004-
</td>
1005-
</tr>
10061017
<tr>
10071018
<td>X</td>
10081019
<td></td>
10091020
<td></td>
10101021
<td></td>
10111022
<td class="path">/api/health/checks/alarms</td>
10121023
<td>
1013-
Responds a 200 OK if there are no alarms in effect in the cluster,
1014-
otherwise responds with a 503 Service Unavailable.
1024+
<p>
1025+
Responds a 200 OK if there are no alarms in effect in the cluster,
1026+
otherwise responds with a 503 Service Unavailable.
1027+
</p>
1028+
1029+
<p>
1030+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/alarms">Resource Alarms</a>
1031+
</p>
10151032
</td>
10161033
</tr>
10171034
<tr>
@@ -1021,8 +1038,13 @@ <h2>Reference</h2>
10211038
<td></td>
10221039
<td class="path">/api/health/checks/local-alarms</td>
10231040
<td>
1024-
Responds a 200 OK if there are no local alarms in effect on the target node,
1025-
otherwise responds with a 503 Service Unavailable.
1041+
<p>
1042+
Responds a 200 OK if there are no local alarms in effect on the target node,
1043+
otherwise responds with a 503 Service Unavailable.
1044+
</p>
1045+
<p>
1046+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/alarms">Resource Alarms</a>
1047+
</p>
10261048
</td>
10271049
</tr>
10281050
<tr>
@@ -1033,15 +1055,32 @@ <h2>Reference</h2>
10331055
<td class="path">/api/health/checks/certificate-expiration/<i>within</i>/<i>unit</i></td>
10341056
<td>
10351057
<p>
1036-
Checks the expiration date on the certificates for every listener configured to use TLS.
1058+
Checks the expiration date of every certificate found in the PEM certificate bundles used by
1059+
all TLS-enabled listeners on the node, regardless of the "type" of the certificate (leaf/server identity,
1060+
intermediary or any CA).
1061+
</p>
1062+
<p>
10371063
Responds a 200 OK if all certificates are valid (have not expired),
10381064
otherwise responds with a 503 Service Unavailable.
10391065
</p>
1066+
<p>
1067+
This health assumes that
1068+
1069+
<ul>
1070+
<li>All certificates included in the PEM bundles on the nodes are relevant to RabbitMQ clients</li>
1071+
<li>Expired certificates is not a normal operating condition and any expired certificate found must be reported with a check failure</li>
1072+
</ul>
1073+
1074+
Do not use this health check if some of these assumptions are not true.
1075+
</p>
10401076
<p>
10411077
Valid units: days, weeks, months, years. The value of the <i>within</i> argument is the number of
10421078
units. So, when <i>within</i> is 2 and <i>unit</i> is "months", the expiration period used by the check
10431079
will be the next two months.
10441080
</p>
1081+
<p>
1082+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/tls">TLS</a>
1083+
</p>
10451084
</td>
10461085
</tr>
10471086
<tr>
@@ -1051,7 +1090,7 @@ <h2>Reference</h2>
10511090
<td></td>
10521091
<td class="path">/api/health/checks/port-listener/<i>port</i></td>
10531092
<td>
1054-
Responds a 200 OK if there is an active listener on the give port,
1093+
Responds a 200 OK if there is an active listener on the given port,
10551094
otherwise responds with a 503 Service Unavailable.
10561095
</td>
10571096
</tr>
@@ -1084,10 +1123,15 @@ <h2>Reference</h2>
10841123
<td></td>
10851124
<td class="path">/api/health/checks/node-is-quorum-critical</td>
10861125
<td>
1087-
Checks if there are quorum queues with minimum online quorum (queues that
1088-
would lose their quorum and availability if the target node is shut down).
1089-
Responds a 200 OK if there are no such quorum queues,
1090-
otherwise responds with a 503 Service Unavailable.
1126+
<p>
1127+
Checks if there are quorum queues with minimum online quorum (queues that
1128+
would lose their quorum and availability if the target node is shut down).
1129+
Responds a 200 OK if there are no such quorum queues,
1130+
otherwise responds with a 503 Service Unavailable.
1131+
</p>
1132+
<p>
1133+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/quorum-queues">Quorum Queues</a>
1134+
</p>
10911135
</td>
10921136
</tr>
10931137
<tr>
@@ -1117,11 +1161,15 @@ <h2>Reference</h2>
11171161
<td></td>
11181162
<td class="path">/api/vhost-limits/<i>vhost</i>/<i>name</i></td>
11191163
<td>
1120-
Set or delete per-vhost limit for <code>vhost</code>. The <code>name</code> URL path element
1121-
refers to the name of the limit (<code>max-connections</code>, <code>max-queues</code>).
1122-
Limits are set using a JSON document in the body: <pre>{"value": 100}</pre>. Example
1123-
request:</br>
1124-
<pre>curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/vhost-limits/my-vhost/max-connections -d '{"value": 50}'</pre>
1164+
<p>
1165+
Set or delete per-vhost limit for <code>vhost</code>. The <code>name</code> URL path element
1166+
refers to the name of the limit (<code>max-connections</code>, <code>max-queues</code>).
1167+
Limits are set using a JSON document in the body: <pre>{"value": 100}</pre>. Example request:</br>
1168+
<pre>curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/vhost-limits/my-vhost/max-connections -d '{"value": 50}'</pre>
1169+
</p>
1170+
<p>
1171+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/vhosts">Virtual Hosts</a>
1172+
</p>
11251173
</td>
11261174
</tr>
11271175
<tr>
@@ -1142,7 +1190,7 @@ <h2>Reference</h2>
11421190
<td>X</td>
11431191
<td class="path">/api/rebalance/queues</td>
11441192
<td>
1145-
Rebalances all queues in all vhosts. This operation is asynchronous therefore please check
1193+
Rebalances all queues in all vhosts. This operation is asynchronous therefore please check
11461194
the RabbitMQ log file for messages regarding the success or failure of the operation.
11471195
<pre>curl -4u 'guest:guest' -XPOST localhost:15672/api/rebalance/queues/</pre>
11481196
</td>
@@ -1306,9 +1354,10 @@ <h2>Reference</h2>
13061354
<td></td>
13071355
<td class="path">/api/stream/consumers/<i>vhost</i></td>
13081356
<td>
1309-
The list of stream consumers in a specific virtual host.
1310-
<br />
1357+
<p>The list of stream consumers in a specific virtual host.</p>
1358+
<p>
13111359
Requires the <code>rabbitmq_stream_management</code> plugin to be enabled.
1360+
</p>
13121361
</td>
13131362
</tr>
13141363
<tr>
@@ -1318,7 +1367,12 @@ <h2>Reference</h2>
13181367
<td></td>
13191368
<td class="path">/api/feature-flags</td>
13201369
<td>
1321-
The list of feature flags.
1370+
<p>
1371+
The list of feature flags.
1372+
</p>
1373+
<p>
1374+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/feature-flags">Feature Flags</a>
1375+
</p>
13221376
</td>
13231377
</tr>
13241378
<tr>
@@ -1328,7 +1382,12 @@ <h2>Reference</h2>
13281382
<td></td>
13291383
<td class="path">/api/deprecated-features</td>
13301384
<td>
1385+
<p>
13311386
The list of deprecated features.
1387+
</p>
1388+
<p>
1389+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/deprecated-features">Feature Flags</a>
1390+
</p>
13321391
</td>
13331392
</tr>
13341393
<tr>
@@ -1338,7 +1397,12 @@ <h2>Reference</h2>
13381397
<td></td>
13391398
<td class="path">/api/deprecated-features/used</td>
13401399
<td>
1400+
<p>
13411401
The list of deprecated features currently being used.
1402+
</p>
1403+
<p>
1404+
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/deprecated-features">Feature Flags</a>
1405+
</p>
13421406
</td>
13431407
</tr>
13441408
</table>

0 commit comments

Comments
 (0)