Improve documentation of certain health checks
in the HTTP API documentation reference as well as one CLI command that apparently needed a clarification.
This commit is contained in:
Michael Klishin
parent
21c242288a
commit
bcb080179c
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -492,11 +492,20 @@ vary: accept, accept-encoding, origin</pre>
|
|||
<td></td>
|
||||
<td></td>
|
||||
<td class="path">/api/queues</td>
|
||||
<td>A list of all queues returning a reduced set of fields. Use <a href="#pagination">pagination parameters</a> to filter queues.
|
||||
The parameter <code>enable_queue_totals=true</code> can be used in combination with the
|
||||
<code>disable_stats=true</code> 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.
|
||||
<td>
|
||||
<p>
|
||||
A list of all queues across all virtual hosts returning a reduced set of fields.
|
||||
</p>
|
||||
<p>
|
||||
Use <a href="#pagination">pagination parameters</a> to filter queues,
|
||||
otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources.
|
||||
</p>
|
||||
<p>
|
||||
The parameter <code>enable_queue_totals=true</code> can be used in combination with the
|
||||
<code>disable_stats=true</code> 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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -505,7 +514,14 @@ vary: accept, accept-encoding, origin</pre>
|
|||
<td></td>
|
||||
<td></td>
|
||||
<td class="path">/api/queues/detailed</td>
|
||||
<td>A list of all queues containing all available information about the queues. Use <a href="#pagination">pagination parameters</a> to filter queues.
|
||||
<td>
|
||||
<p>
|
||||
A list of all queues containing all available information about the queues (over 50 fields per queue).
|
||||
</p>
|
||||
<p>
|
||||
Use <a href="#pagination">pagination parameters</a> to filter queues,
|
||||
otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -514,7 +530,15 @@ vary: accept, accept-encoding, origin</pre>
|
|||
<td></td>
|
||||
<td></td>
|
||||
<td class="path">/api/queues/<i>vhost</i></td>
|
||||
<td>A list of all queues in a given virtual host. Use <a href="#pagination">pagination parameters</a> to filter queues.</td>
|
||||
<td>
|
||||
<p>
|
||||
A list of all queues in the given virtual host containing all available information about the queues (over 50 fields per queue)..
|
||||
</p>
|
||||
<p>
|
||||
Use <a href="#pagination">pagination parameters</a> to filter queues,
|
||||
otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X</td>
|
||||
|
|
@ -524,7 +548,7 @@ vary: accept, accept-encoding, origin</pre>
|
|||
<td class="path">/api/queues/<i>vhost</i>/<i>name</i></td>
|
||||
<td>
|
||||
An individual queue. To PUT a queue, you will need a body looking something like this:
|
||||
<pre>{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@smacmullen"}</pre>
|
||||
<pre>{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@node.hostname"}</pre>
|
||||
All keys are optional.
|
||||
<p>
|
||||
When DELETEing a queue you can add the query string
|
||||
|
|
@ -990,19 +1014,6 @@ or:
|
|||
<code>pattern</code> and <code>definition</code> are mandatory, <code>priority</code> and <code>apply-to</code> are optional.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td class="path">/api/aliveness-test/<i>vhost</i></td>
|
||||
<td>
|
||||
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.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X</td>
|
||||
<td></td>
|
||||
|
|
@ -1010,8 +1021,14 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/health/checks/alarms</td>
|
||||
<td>
|
||||
Responds a 200 OK if there are no alarms in effect in the cluster,
|
||||
otherwise responds with a 503 Service Unavailable.
|
||||
<p>
|
||||
Responds a 200 OK if there are no alarms in effect in the cluster,
|
||||
otherwise responds with a 503 Service Unavailable.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/alarms">Resource Alarms</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1021,8 +1038,13 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/health/checks/local-alarms</td>
|
||||
<td>
|
||||
Responds a 200 OK if there are no local alarms in effect on the target node,
|
||||
otherwise responds with a 503 Service Unavailable.
|
||||
<p>
|
||||
Responds a 200 OK if there are no local alarms in effect on the target node,
|
||||
otherwise responds with a 503 Service Unavailable.
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/alarms">Resource Alarms</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1033,15 +1055,32 @@ or:
|
|||
<td class="path">/api/health/checks/certificate-expiration/<i>within</i>/<i>unit</i></td>
|
||||
<td>
|
||||
<p>
|
||||
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).
|
||||
</p>
|
||||
<p>
|
||||
Responds a 200 OK if all certificates are valid (have not expired),
|
||||
otherwise responds with a 503 Service Unavailable.
|
||||
</p>
|
||||
<p>
|
||||
This health assumes that
|
||||
|
||||
<ul>
|
||||
<li>All certificates included in the PEM bundles on the nodes are relevant to RabbitMQ clients</li>
|
||||
<li>Expired certificates is not a normal operating condition and any expired certificate found must be reported with a check failure</li>
|
||||
</ul>
|
||||
|
||||
Do not use this health check if some of these assumptions are not true.
|
||||
</p>
|
||||
<p>
|
||||
Valid units: days, weeks, months, years. The value of the <i>within</i> argument is the number of
|
||||
units. So, when <i>within</i> is 2 and <i>unit</i> is "months", the expiration period used by the check
|
||||
will be the next two months.
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/tls">TLS</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1051,7 +1090,7 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/health/checks/port-listener/<i>port</i></td>
|
||||
<td>
|
||||
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.
|
||||
</td>
|
||||
</tr>
|
||||
|
|
@ -1084,10 +1123,15 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/health/checks/node-is-quorum-critical</td>
|
||||
<td>
|
||||
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.
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/quorum-queues">Quorum Queues</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1117,11 +1161,15 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/vhost-limits/<i>vhost</i>/<i>name</i></td>
|
||||
<td>
|
||||
Set or delete per-vhost limit for <code>vhost</code>. The <code>name</code> URL path element
|
||||
refers to the name of the limit (<code>max-connections</code>, <code>max-queues</code>).
|
||||
Limits are set using a JSON document in the body: <pre>{"value": 100}</pre>. Example
|
||||
request:</br>
|
||||
<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>
|
||||
<p>
|
||||
Set or delete per-vhost limit for <code>vhost</code>. The <code>name</code> URL path element
|
||||
refers to the name of the limit (<code>max-connections</code>, <code>max-queues</code>).
|
||||
Limits are set using a JSON document in the body: <pre>{"value": 100}</pre>. Example request:</br>
|
||||
<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>
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/vhosts">Virtual Hosts</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1142,7 +1190,7 @@ or:
|
|||
<td>X</td>
|
||||
<td class="path">/api/rebalance/queues</td>
|
||||
<td>
|
||||
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.
|
||||
<pre>curl -4u 'guest:guest' -XPOST localhost:15672/api/rebalance/queues/</pre>
|
||||
</td>
|
||||
|
|
@ -1306,9 +1354,10 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/stream/consumers/<i>vhost</i></td>
|
||||
<td>
|
||||
The list of stream consumers in a specific virtual host.
|
||||
<br />
|
||||
<p>The list of stream consumers in a specific virtual host.</p>
|
||||
<p>
|
||||
Requires the <code>rabbitmq_stream_management</code> plugin to be enabled.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1318,7 +1367,12 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/feature-flags</td>
|
||||
<td>
|
||||
The list of feature flags.
|
||||
<p>
|
||||
The list of feature flags.
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/feature-flags">Feature Flags</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1328,7 +1382,12 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/deprecated-features</td>
|
||||
<td>
|
||||
<p>
|
||||
The list of deprecated features.
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/deprecated-features">Feature Flags</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -1338,7 +1397,12 @@ or:
|
|||
<td></td>
|
||||
<td class="path">/api/deprecated-features/used</td>
|
||||
<td>
|
||||
<p>
|
||||
The list of deprecated features currently being used.
|
||||
</p>
|
||||
<p>
|
||||
Relevant documentation guide: <a href="https://www.rabbitmq.com/docs/deprecated-features">Feature Flags</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
|
|
|||
Loading…
Reference in New Issue