[Why]
Mnesia is a very powerful and convenient tool for Erlang applications:
it is a persistent disc-based database, it handles replication accross
multiple Erlang nodes and it is available out-of-the-box from the
Erlang/OTP distribution. RabbitMQ relies on Mnesia to manage all its
metadata:
* virtual hosts' properties
* intenal users
* queue, exchange and binding declarations (not queues data)
* runtime parameters and policies
* ...
Unfortunately Mnesia makes it difficult to handle network partition and,
as a consequence, the merge conflicts between Erlang nodes once the
network partition is resolved. RabbitMQ provides several partition
handling strategies but they are not bullet-proof. Users still hit
situations where it is a pain to repair a cluster following a network
partition.
[How]
@kjnilsson created Ra [1], a Raft consensus library that RabbitMQ
already uses successfully to implement quorum queues and streams for
instance. Those queues do not suffer from network partitions.
We created Khepri [2], a new persistent and replicated database engine
based on Ra and we want to use it in place of Mnesia in RabbitMQ to
solve the problems with network partitions.
This patch integrates Khepri as an experimental feature. When enabled,
RabbitMQ will store all its metadata in Khepri instead of Mnesia.
This change comes with behavior changes. While Khepri remains disabled,
you should see no changes to the behavior of RabbitMQ. If there are
changes, it is a bug. After Khepri is enabled, there are significant
changes of behavior that you should be aware of.
Because it is based on the Raft consensus algorithm, when there is a
network partition, only the cluster members that are in the partition
with at least `(Number of nodes in the cluster ÷ 2) + 1` number of nodes
can "make progress". In other words, only those nodes may write to the
Khepri database and read from the database and expect a consistent
result.
For instance in a cluster of 5 RabbitMQ nodes:
* If there are two partitions, one with 3 nodes, one with 2 nodes, only
the group of 3 nodes will be able to write to the database.
* If there are three partitions, two with 2 nodes, one with 1 node, none
of the group can write to the database.
Because the Khepri database will be used for all kind of metadata, it
means that RabbitMQ nodes that can't write to the database will be
unable to perform some operations. A list of operations and what to
expect is documented in the associated pull request and the RabbitMQ
website.
This requirement from Raft also affects the startup of RabbitMQ nodes in
a cluster. Indeed, at least a quorum number of nodes must be started at
once to allow nodes to become ready.
To enable Khepri, you need to enable the `khepri_db` feature flag:
rabbitmqctl enable_feature_flag khepri_db
When the `khepri_db` feature flag is enabled, the migration code
performs the following two tasks:
1. It synchronizes the Khepri cluster membership from the Mnesia
cluster. It uses `mnesia_to_khepri:sync_cluster_membership/1` from
the `khepri_mnesia_migration` application [3].
2. It copies data from relevant Mnesia tables to Khepri, doing some
conversion if necessary on the way. Again, it uses
`mnesia_to_khepri:copy_tables/4` from `khepri_mnesia_migration` to do
it.
This can be performed on a running standalone RabbitMQ node or cluster.
Data will be migrated from Mnesia to Khepri without any service
interruption. Note that during the migration, the performance may
decrease and the memory footprint may go up.
Because this feature flag is considered experimental, it is not enabled
by default even on a brand new RabbitMQ deployment.
More about the implementation details below:
In the past months, all accesses to Mnesia were isolated in a collection
of `rabbit_db*` modules. This is where the integration of Khepri mostly
takes place: we use a function called `rabbit_khepri:handle_fallback/1`
which selects the database and perform the query or the transaction.
Here is an example from `rabbit_db_vhost`:
* Up until RabbitMQ 3.12.x:
get(VHostName) when is_binary(VHostName) ->
get_in_mnesia(VHostName).
* Starting with RabbitMQ 3.13.0:
get(VHostName) when is_binary(VHostName) ->
rabbit_khepri:handle_fallback(
#{mnesia => fun() -> get_in_mnesia(VHostName) end,
khepri => fun() -> get_in_khepri(VHostName) end}).
This `rabbit_khepri:handle_fallback/1` function relies on two things:
1. the fact that the `khepri_db` feature flag is enabled, in which case
it always executes the Khepri-based variant.
4. the ability or not to read and write to Mnesia tables otherwise.
Before the feature flag is enabled, or during the migration, the
function will try to execute the Mnesia-based variant. If it succeeds,
then it returns the result. If it fails because one or more Mnesia
tables can't be used, it restarts from scratch: it means the feature
flag is being enabled and depending on the outcome, either the
Mnesia-based variant will succeed (the feature flag couldn't be enabled)
or the feature flag will be marked as enabled and it will call the
Khepri-based variant. The meat of this function really lives in the
`khepri_mnesia_migration` application [3] and
`rabbit_khepri:handle_fallback/1` is a wrapper on top of it that knows
about the feature flag.
However, some calls to the database do not depend on the existence of
Mnesia tables, such as functions where we need to learn about the
members of a cluster. For those, we can't rely on exceptions from
Mnesia. Therefore, we just look at the state of the feature flag to
determine which database to use. There are two situations though:
* Sometimes, we need the feature flag state query to block because the
function interested in it can't return a valid answer during the
migration. Here is an example:
case rabbit_khepri:is_enabled(RemoteNode) of
true -> can_join_using_khepri(RemoteNode);
false -> can_join_using_mnesia(RemoteNode)
end
* Sometimes, we need the feature flag state query to NOT block (for
instance because it would cause a deadlock). Here is an example:
case rabbit_khepri:get_feature_state() of
enabled -> members_using_khepri();
_ -> members_using_mnesia()
end
Direct accesses to Mnesia still exists. They are limited to code that is
specific to Mnesia such as classic queue mirroring or network partitions
handling strategies.
Now, to discover the Mnesia tables to migrate and how to migrate them,
we use an Erlang module attribute called
`rabbit_mnesia_tables_to_khepri_db` which indicates a list of Mnesia
tables and an associated converter module. Here is an example in the
`rabbitmq_recent_history_exchange` plugin:
-rabbit_mnesia_tables_to_khepri_db(
[{?RH_TABLE, rabbit_db_rh_exchange_m2k_converter}]).
The converter module — `rabbit_db_rh_exchange_m2k_converter` in this
example — is is fact a "sub" converter module called but
`rabbit_db_m2k_converter`. See the documentation of a `mnesia_to_khepri`
converter module to learn more about these modules.
[1] https://github.com/rabbitmq/ra
[2] https://github.com/rabbitmq/khepri
[3] https://github.com/rabbitmq/khepri_mnesia_migration
See #7206.
Co-authored-by: Jean-Sébastien Pédron <jean-sebastien@rabbitmq.com>
Co-authored-by: Diana Parra Corbacho <dparracorbac@vmware.com>
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
Allow list of preferred_username_claims in cuttlefish
config style.
Use new config style on two selenium test suites
Test oauth2 backend's config schema and oauth2 management
config schema
Default queue type logic didn't apply when import was done for a
single vhost. Exported definitions for a single vhost don't contain
`vhost` key, and anyway it's better to use the actual vhost name that
will be used for queue declaration.
And just in case, `vhost` is now stripped from all exported items for
a single vhost (it was still present in `parameters` and `policies`) -
on import it was ignored, but it could have been a source of the bug
similar to the one with the default queue type.
Back in 2016, JSON encoding and
much of the Erlang ecosystem used
proplists, which can lead to duplicate
keys in JSON documents.
In 2022 some JSON libraries only
decode JSON to maps, and maps
have unique keys, so these tests
are not worth adjusting or reproducing
with maps.
Per discussion with the team.
This commit adds the "consumers" metrics to stream queues (consumer count).
It is computed by counting the element of the consumer_created ETS table
for the given stream queue and for each member of the Osiris cluster.
Fixes#4622
Unlike with gnu make, mixed version testing with bazel uses a package-generic-unix for the secondary umbrella rather than the source. This brings the benefit of being able to mixed version test releases built with older erlang versions (even though all nodes will run under the single version given to bazel)
This introduces new test labels, adding a `-mixed` suffix for every existing test. They can be skipped if necessary with `--test_tag_filters` (see the github actions workflow for an example)
As part of the change, it is now possible to run an old release of rabbit with rabbitmq_run rule, such as:
`bazel run @rabbitmq-server-generic-unix-3.8.17//:rabbitmq-run run-broker`
GET /api/health/checks/certificate-expiration
GET /api/health/checks/port-listener
GET /api/health/checks/protocol-listener
GET /api/health/checks/virtual-hosts
GET /api/health/checks/node-is-mirror-sync-critical
GET /api/health/checks/node-is-quorum-critical
Some tests are timing-sensitive in nature. Given enough cores,
the assumptions in some of them are no longer true.
In addition, some sample test assertions only make sense when
stats collection is disabled; removed them from the "regular" HTTP
API suite per discussion with @dcorbacho.
While at it, remove some overly opinionated assertions
and a test for the deprecated One True Health Check™.
So that they are easy to skip in mixed-version clusters where
this feature flag can't be guaranteed to be available.
References #rabbitmq/rabbitmq-server#2380.
It polluted the common_test node and caused inter-node communication
failures: a new `.erlang.cookie` file was re-generated in the overriden
$HOME directory, and this new cookie was used by RabbitMQ nodes started
after this testsuite.
With most CLI tools, command line arguments
take precedence over values in the configuration file.
This was not the case in rabbitmqadmin, and very likely
unintentionally so, at least I could not find
any evidence of the contrary.
There was a test case that implicitly depended
on this behavior. Again, no indication of this
being an intentional design choice.
While this can be a breaking change, most
users either use CLI flags or the config file;
this is why this behavior has gone unnoticed
for at least 8 years. We therefore treat
this change as low risk and worth
shipping e.g. in a patch release.
rabbitmqadmin is installed manually and
therefore won't be replaced during a node
upgrade anyway. Operators would
have to opt-in.
Closes#804.
When basic auth is disabled, we don't want to display the basic auth
prompt just to return the same 401 that we would because basic auth is
disabled.
rabbitmq/rabbitmq-management#724
[#158496849]
See #723 for background.
Currently there are three main ways to declare a binding:
* Use an AMQP 0-9-1 client
* Use an HTTP API client
* Definition import
For the sake of this change we will fold the latter two options into
one as they are effectively identical as far as data formats go.
An HTTP API client can do things that an AMQP 0-9-1 would not be able
to because of framing/parser/generator restrictions, and vice versa.
With HTTP API and definition import the following importance
* When a binding is added, routing key can be omitted or set to `null`
(or `undefined`)
* When a binding is deleted, a blank routing key can only be specified
using a convention since an empty URI path arguments are not
supported
by Cowboy REST and would make no sense to the developer.
Omitted or `null` `routing_key` values are parsed to their respective
atoms.
Those atoms are then stored in binding records. When a binding is
retrieved
or deleted (the case in #723), the conventionally encoded routing key
that
contained "null" for name was parsed to "null" (a string). This
discrepancy
led to false 404 responses from the API.
Note that this solution is merely a band aid over a fundamental
difference
in two APIs. Rejecting `null` or undefined values might be a better
option
but we cannot adopt it in 3.7.x. It remains to be discussed whether that
would improve user experience.
Another problematic scenario is routing keys with the value of "null"
(a string) used at binding time. This change would break deletion for
those. We'll assume that no developer would intentionally use such
routing key as the confusion and risk are more or less obvious.
When definitions import fails it returns {error, Reason}, which is ignored
when importing multiple definitions and fails silently.
Fix that by checking result of every import.
Slimmed down version of the API without metrics.
Stats can be disabled from app config or in the HTTP request.
rabbitmq_management.disable_management_stats = true
Disabling the collectors in the agent now allows the management
application to start, but strictly in management-only mode.
[#166445368]
Diana Parra Corbacho
Simon Unge
Michael Klishin
Loïc Hoguin
Michael Klishin
Marcial Rosales
David Ansari
Alex Valiushko
Alexey Lebedeff
Luke Bakken
Karl Nilsson
Jean-Sébastien Pédron
Arnaud Cogoluègnes
Philip Kuryloski
Iliia Khaprov
dcorbacho
Luke Bakken
kjnilsson
Ayanda-D
Philip Kuryloski
Michael Klishin
Diana Corbacho
Gerhard Lazu
Daniil Fedotov
Spring Operator
Josh Soref