Configuring Static Shovels
Overview
This guide focuses on statically configured shovels. It assumes familiarity with the key concepts behind the Shovel plugin.
Unlike with dynamic shovels, static shovels are configured using the advanced configuration file. They are started on node boot and are primarily useful for permanently running workloads. Any changes to static shovel configuration would require a node restart, which makes them highly inflexible.
Most users should prefer dynamic shovels to static ones for their flexibility and ease of automation. Generating a dynamic shovel definition (a JSON document) is usually easier compared to a static shovel definition (which uses Erlang terms).
Configuration
The configuration for the Shovel plugin must be defined in the advanced configuration file.
It consists of a single shovels
clause that lists the shovels that should
be started on node boot:
{rabbit, [
%% ...
]},
{rabbitmq_shovel, [
{shovels, [
{shovel_one, [
%% shovel_one properties ...
]},
%% ...
]}
]}
A (deliberately verbose) example configuration can be found below.
Each element of the shovels
clause is a named static shovel.
The names in the list must be distinct.
A shovel definition looks like this at the top level:
{<em>shovel_name</em>, [
{source, [ <em>...protocol specific config...</em> ]},
{destination, [ <em>...protocol specific config...</em> ]},
{ack_mode, <em>a_mode</em>},
{reconnect_delay, <em>reconn_delay</em>}
]}
where shovel_name
is the name of the
shovel (an Erlang atom). The name should be enclosed in single quotes ('
) if they do
not begin with a lower-case letter or if they contain
other characters than alphanumeric characters, underscore
(_
), or @
.
The Source and The Destination
A shovel transfers messages from a source to a destination.
The source
and destination
keys are mandatory and contain nested protocol-specific keys. Currently AMQP 0.9.1 and AMQP 1.0 are two supported protocols.
Source and destination do not have to use the same protocol.
All the other properties are optional.
source
is a mandatory key and has different keys properties
for different protocols. Two properties are common across all
protocols: protocol
and uris
.
protocol
supports two values: amqp091
and amqp10
,
for AMQP 0-9-1 and AMQP 1.0, respectively:
%% for AMQP 0-9-1
{protocol, amqp091}
uris
is a list of AMQP connection URIs:
{uris, [
"amqp://fred:secret@host1.domain/my_vhost",
"amqp://john:secret@host2.domain/my_vhost"
]}
The URI syntax is extended to include a query part to permit the configuration of additional connection parameters. See the query parameter reference which are available to static shovels, such as TLS certificate and private key.