Skip to content

Commit

Permalink
Merge pull request #13037 from rabbitmq/mk-x509-certificate-expiratio…
Browse files Browse the repository at this point in the history 
…n-health-check-docs

Improve documentation of certain health checks
  • Loading branch information
@michaelklishin
michaelklishin authored Jan 8, 2025
2 parents c674544 + 48aa250 commit 382ed14
Show file tree
Hide file tree
Showing 2 changed files with 110 additions and 44 deletions.
10 changes: 6 additions & 4 deletions ...abbitmq_cli/lib/rabbitmq/cli/diagnostics/commands/check_certificate_expiration_command.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,11 @@
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.Listeners

@behaviour RabbitMQ.CLI.CommandBehaviour

def switches(), do: [unit: :string, within: :integer]

def merge_defaults(args, opts) do
Expand Down Expand Up @@ -102,9 +103,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
144 changes: 104 additions & 40 deletions deps/rabbitmq_management/priv/www/api/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -492,11 +492,20 @@ <h2>Reference</h2>
<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>
Expand All @@ -505,7 +514,14 @@ <h2>Reference</h2>
<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>
Expand All @@ -514,7 +530,15 @@ <h2>Reference</h2>
<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>
Expand All @@ -524,7 +548,7 @@ <h2>Reference</h2>
<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
Expand Down Expand Up @@ -990,28 +1014,21 @@ <h2>Reference</h2>
<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>
<td></td>
<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>
Expand All @@ -1021,8 +1038,13 @@ <h2>Reference</h2>
<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>
Expand All @@ -1033,15 +1055,32 @@ <h2>Reference</h2>
<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>
Expand All @@ -1051,7 +1090,7 @@ <h2>Reference</h2>
<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>
Expand Down Expand Up @@ -1084,10 +1123,15 @@ <h2>Reference</h2>
<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>
Expand Down Expand Up @@ -1117,11 +1161,15 @@ <h2>Reference</h2>
<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>
Expand All @@ -1142,7 +1190,7 @@ <h2>Reference</h2>
<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>
Expand Down Expand Up @@ -1306,9 +1354,10 @@ <h2>Reference</h2>
<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>
Expand All @@ -1318,7 +1367,12 @@ <h2>Reference</h2>
<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>
Expand All @@ -1328,7 +1382,12 @@ <h2>Reference</h2>
<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">Deprecated Features</a>
</p>
</td>
</tr>
<tr>
Expand All @@ -1338,7 +1397,12 @@ <h2>Reference</h2>
<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">Deprecated Features</a>
</p>
</td>
</tr>
</table>
Expand Down

0 comments on commit 382ed14

Please sign in to comment.