MQ

Introduction

MQ is a managed message broker service offered by Amazon Web Services (AWS). It facilitates the exchange of messages between various components of distributed applications, enabling reliable and scalable communication. AWS MQ supports popular messaging protocols like MQTT, AMQP, and STOMP, making it suitable for a wide range of messaging use cases.

LocalStack supports MQ via the Pro/Team offering, allowing you to use the MQ APIs to implement pub/sub messaging, request/response patterns, or distributed event-driven architectures in your local environment. The supported APIs are available on our API Coverage Page, which provides information on the extent of MQ integration with LocalStack.

Getting started

This guide is designed for users new to MQ and assumes basic knowledge of the AWS CLI and our awslocal wrapper script.

Start your LocalStack container using your preferred method. We will demonstrate how to create an MQ broker and send a message to a sample queue.

Create a broker

You can create a broker using the CreateBroker API. Run the following command to create a broker named test-broker with the following configuration:

$ awslocal mq create-broker \
    --broker-name test-broker \
    --deployment-mode SINGLE_INSTANCE \
    --engine-type ACTIVEMQ \
    --engine-version='5.16.6' \
    --host-instance-type 'mq.t2.micro' \
    --auto-minor-version-upgrade \
    --publicly-accessible \
    --users='{"ConsoleAccess": true, "Groups": ["testgroup"],"Password": "QXwV*$iUM9USHnVv&!^7s3c@", "Username": "admin"}'

{
    "BrokerArn": "arn:aws:mq:us-east-1:000000000000:broker:test-broker:b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545",
    "BrokerId": "b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545"
}

Describe the broker

You can use the DescribeBroker API to get more detailed information about the broker. Run the following command to get information about the broker we created above:

$ awslocal mq describe-broker --broker-id
 
b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545
{
    "BrokerArn": "arn:aws:mq:us-east-1:000000000000:broker:test-broker:b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545",
    "BrokerId": "b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545",
    "BrokerInstances": [
        {
            "ConsoleURL": "http://localhost:4513",
            "Endpoints": [
                "stomp://localhost:4515",
                "tcp://localhost:4514"
            ]
        }
    ],
    "BrokerName": "test-broker",
    "BrokerState": "RUNNING",
    "Created": "2022-10-17T07:14:21.065527Z",
    "DeploymentMode": "SINGLE_INSTANCE",
    "EngineType": "ACTIVEMQ",
    "HostInstanceType": "mq.t2.micro",
    "Tags": {}
}

Send a message

Now that the broker is actively listening, we can use curl to send a message to a sample queue. Run the following command to send a message to the orders.input queue:

$ curl -XPOST -d "body=message" http://admin:admin@localhost:4513/api/message\?destination\=queue://orders.input

Examples

The following code snippets and sample applications provide practical examples of how to use MQ in LocalStack for various use cases:

• Demo application illustrating the use of MQ with LocalStack

Limitations

Currently, our MQ emulation offers only fundamental capabilities, and it comes with certain limitations:

• ActiveMQ Version Limitation: Presently, only ActiveMQ version 5.16.6 is supported.
• IAM User Management: IAM Users are not actively enforced, although they are necessary for making correct calls within the system.
• Configuration Enforcement: While it is feasible to create configurations, they are not actively enforced within the broker.
• Persistence and Cloud Pods: LocalStack does not provide support for Persistence and Cloud Pods at this time.
• API Coverage: Please note that there is limited API coverage available as part of the current emulation capabilities.