Wez Furlong
7f4a929ca2
This commit implements a kumomta-specific message transfer protocol that is intended to be used to migrate messages from one kumomta node to another. The transfer is carried out using an HTTP POST request to the destination node's http listener. The request includes the full message metadata and body, in a compressed form. An xfer request can be made via `kcli xfer` (and thus also via an HTTP API endpoint). It works similarly to a rebind operation; you specify the criteria to be used to match scheduled queues, along with the target node for the xfer, and kumomta will find matching queues, drain out the messages, make an adjustment to the metadata to capture current scheduling information, and then place the messages into an xfer queue. The xfer queue has hard-coded scheduling queue configuration of its own, with the base retry interval set to 10 seconds, which should be suitably aggressive for the intended use case. You may apply shaping to affect the number of concurrent requests in a similar way to how TSA shaping is configured. On the receiving side, the incoming xfer sanity check to prohibit trying to xfer to itself. The spool id of the Message is not suitable to be reused verbatim on another node (spool ids include the local mac address and creation timestamp information, as well as a random component), so the receiving side will derive an id that should be suitable for use on that node. The originating node id and spool id will be preserved in metadata to aid in tracing. It is possible for an xfer request to target an existing xfer queue, so that you can correct/update the target in various circumstances. In that situation the messages will be "simply" moved from the source queue to the destination queue. It is possible to cancel an xfer request via `kcli xfer-cancel` (and thus also via an HTTP API endpoint). You specify the target queue, which must be an xfer queue, and it will have its messages drained and the metadata changes that were applied when the xfer was initiated will be reversed, allowing the messages to then be reinserted into their originating queue. refs: https://github.com/KumoCorp/kumomta/issues/311
2.9 KiB
kcli xfer
Transfer messages from matching queues to an alternative kumomta node.
The intended purpose of this command is to facilitate manual migration of queues to alternative nodes as part of planned maintenance or part of an orchestrated down-scaling operation.
Xfering works first by selecting the set of scheduled queues based on matching criteria that you specify via the --domain, --routing-domain, --campaign, --tenant, --queue, and/or --everything options.
Each matching queue has its messages drained and the xfer logic will amend the message metadata to capture scheduling and due time information and then place the message into a special .xfer.kumomta.internal message transfer queue where it will be immediately eligible to be moved to the destination node.
Upon successful reception on the destination node, the saved scheduling information will be restored to the message and it will be inserted into an appropriate queue on that destination node for delivery at the appropriate time.
Since the number of messages may be very large, and because processing messages may result in a large amount of I/O to load in every matching message's metadata, the total amount of time taken for an xfer request may be too large to feasibly wait for in the context of a simple request/response.
With that in mind, the xfer action runs asynchronously: aside from any immediate syntax/request formatting issues, this command will immediately return with no further status indication.
Errors will be reported in the diagnostic log.
Examples
Move messages from the "example.com" queue to the kumomta node running an http listener on http://10.0.0.1:8000:
kcli xfer --domain example.com --target http://10.0.0.1:8000
Usage: kcli xfer --reason <REASON> --target <TARGET> <--domain <DOMAIN>|--routing-domain <ROUTING_DOMAIN>|--campaign <CAMPAIGN>|--tenant <TENANT>|--everything|--queue <QUEUE>>
Options
-
--domain <DOMAIN>— The domain name to match. If omitted, any domains will match! -
--routing-domain <ROUTING_DOMAIN>— The routing_domain name to match. If omitted, any routing domain will match! -
--campaign <CAMPAIGN>— The campaign name to match. If omitted, any campaigns will match! -
--tenant <TENANT>— The tenant name to match. If omitted, any tenant will match! -
--queue <QUEUE>— The precise name of a scheduled queue which should match. Can be specified multiple times -
--reason <REASON>— Each matching message will be rebound into an appropriate xfer queue, and an AdminRebind log will be generated to trace that the rebind happened. The reason you specify here will be included in that log record -
--everything— Match all queues -
--target <TARGET>— Which node to transfer the messages to. This should be an HTTP URL prefix that will reach the HTTP listener on the target node, such ashttp://hostname:8000