Amazon MQ - Developer Guide - AWS Documentation

Amazon MQ
Developer Guide
Amazon MQ Developer Guide
Amazon MQ: Developer Guide
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
Amazon MQ Developer Guide
Table of Contents
What is Amazon MQ? ......................................................................................................................... 1
What Are the Main Benefits of Amazon MQ? ................................................................................. 1
How Is Amazon MQ Different from Amazon SQS or Amazon SNS? .................................................... 1
How Can I Get Started with Amazon MQ? ..................................................................................... 1
We Want to Hear from You ......................................................................................................... 2
New and Frequently Viewed Topics ...................................................................................................... 3
Amazon MQ Developer Guide ...................................................................................................... 3
Amazon MQ REST API Reference ................................................................................................... 3
Setting Up ........................................................................................................................................ 4
Step 1: Create an AWS Account and an IAM Administrator User ........................................................ 4
Step 2: Create an IAM User and Get Your AWS Credentials .............................................................. 4
Step 3: Get Ready to Use the Example Code ................................................................................. 5
Next Steps ................................................................................................................................ 5
Getting Started .................................................................................................................................. 6
Prerequisites .............................................................................................................................. 6
Step 1: Create an ActiveMQ Broker .............................................................................................. 6
Step 2: Connect a Java Application to Your Broker ......................................................................... 7
Prerequisites ...................................................................................................................... 7
Create a Message Producer and Send a Message .................................................................... 7
Create a Message Consumer and Receive the Message ............................................................ 9
Step 3: Delete Your Broker ........................................................................................................ 10
Next Steps ............................................................................................................................... 10
Tutorials .......................................................................................................................................... 11
Creating and Configuring a Broker .............................................................................................. 11
Step 1: Configure basic broker settings ............................................................................... 11
Step 2: (Optional) Configure advanced broker settings .......................................................... 12
Step 3: Finish creating the broker ....................................................................................... 13
Creating and Applying Configurations ......................................................................................... 13
Step 1: Create a configuration from scratch ......................................................................... 14
Step 2: Create a new configuration revision ......................................................................... 14
Step 3: Apply a configuration revision to your broker ............................................................ 15
Editing Configurations and Managing Configuration Revisions ........................................................ 16
To view a previous configuration revision ............................................................................ 16
To edit the current configuration revision ............................................................................ 17
To apply a configuration revision to your broker ................................................................... 18
To roll back your broker to the last configuration revision ...................................................... 18
Connecting a Java Application to Your Broker .............................................................................. 19
Prerequisites .................................................................................................................... 19
To create a message producer and send a message ............................................................... 20
To create a message consumer and receive the message ....................................................... 21
Listing Brokers and Viewing Broker Details .................................................................................. 22
To list brokers and view broker details ................................................................................ 22
Creating and Managing Broker Users .......................................................................................... 23
To create a new user ........................................................................................................ 24
To edit an existing user ..................................................................................................... 24
To delete a existing user ................................................................................................... 25
Rebooting a Broker ................................................................................................................... 25
To reboot an Amazon MQ broker ....................................................................................... 25
Deleting a Broker ..................................................................................................................... 26
To delete an Amazon MQ broker ........................................................................................ 26
Accessing CloudWatch Metrics .................................................................................................... 26
AWS Management Console ................................................................................................ 26
AWS Command Line Interface ............................................................................................ 28
Amazon CloudWatch API ................................................................................................... 28
iii
Amazon MQ Developer Guide
How Amazon MQ Works ...................................................................................................................
Basic Elements .........................................................................................................................
Broker .............................................................................................................................
Configuration ...................................................................................................................
Engine ............................................................................................................................
User ................................................................................................................................
Broker Architecture ...................................................................................................................
Single-Instance Broker ......................................................................................................
Active/Standby Broker for High Availability .........................................................................
Concurrent Store and Dispatch for Queues ..........................................................................
Broker Configuration Lifecycle ...................................................................................................
Broker Configuration Parameters ................................................................................................
Working with Spring XML Configuration Files .......................................................................
Permitted Elements ..........................................................................................................
Permitted Attributes .........................................................................................................
Permitted Collections ........................................................................................................
Working Java Example ..............................................................................................................
Prerequisites ....................................................................................................................
AmazonMQExample.java ...................................................................................................
Migrating to Amazon MQ ..................................................................................................................
Without Service Interruption ......................................................................................................
To migrate to Amazon MQ without service interruption ........................................................
With Service Interruption ..........................................................................................................
To migrate to Amazon MQ with service interruption .............................................................
Best Practices ..................................................................................................................................
Using Amazon MQ Securely .......................................................................................................
Prefer Brokers without Public Accessibility ...........................................................................
Always Use Client-Side Encryption as a Complement to TLS ..................................................
Always Configure an Authorization Map ..............................................................................
Always Configure a System Group ......................................................................................
Communicating with Amazon MQ ..............................................................................................
Never Modify or Delete the Amazon MQ Elastic Network Interface ..........................................
Always Use Connection Pooling .........................................................................................
Always Use the Failover Transport to Connect to Multiple Broker Endpoints .............................
Avoid Using Message Selectors ..........................................................................................
Prefer Virtual Destinations to Durable Subscriptions .............................................................
Ensuring Effective Amazon MQ Performance ...............................................................................
Disable Concurrent Store and Dispatch for Queues with Slow Consumers .................................
Limits .............................................................................................................................................
Brokers ....................................................................................................................................
Configurations .........................................................................................................................
Users ......................................................................................................................................
Data Storage ...........................................................................................................................
API Throttling ..........................................................................................................................
Monitoring Amazon MQ using CloudWatch ..........................................................................................
Broker Metrics ..........................................................................................................................
Dimension for Broker Metrics .............................................................................................
Destination (Queue and Topic) Metrics ........................................................................................
Dimensions for Destination (Queue and Topic) Metrics ..........................................................
Security ...........................................................................................................................................
API Authentication and Authorization .........................................................................................
Messaging Authentication and Authorization ...............................................................................
Related Resources ............................................................................................................................
Amazon MQ Resources ..............................................................................................................
Apache ActiveMQ Resources ......................................................................................................
Release Notes ..................................................................................................................................
Document History ....................................................................................................................
iv
29
29
29
31
32
32
33
33
34
35
36
37
37
37
39
46
50
50
51
54
54
54
55
56
57
57
57
57
57
58
58
58
59
59
60
60
60
60
61
61
61
62
62
62
64
64
64
65
66
67
67
68
69
69
69
70
71
Amazon MQ Developer Guide
AWS Glossary .................................................................................................................................. 75
v
Amazon MQ Developer Guide
What Are the Main Benefits of Amazon MQ?
What Is Amazon MQ?
Amazon MQ is a managed message broker service for Apache ActiveMQ that makes it easy to set up and
operate message brokers in the cloud. A message broker allows software applications and components
to communicate using various programming languages, operating systems, and formal messaging
protocols.
Amazon MQ works with your existing applications and services without the need to manage, operate, or
maintain your own messaging system.
Topics
• What Are the Main Benefits of Amazon MQ? (p. 1)
• How Is Amazon MQ Different from Amazon SQS or Amazon SNS? (p. 1)
• How Can I Get Started with Amazon MQ? (p. 1)
• We Want to Hear from You (p. 2)
What Are the Main Benefits of Amazon MQ?
• Accelerated migration – Amazon MQ supports industry-standard APIs and protocols so you can
migrate from your existing message broker without rewriting application code.
• Reduced cost – Amazon MQ provides cost-efficient and flexible messaging capacity—you pay for
broker instance and storage usage as you go.
• Operation offloading – Amazon MQ manages the administration and maintenance of ActiveMQ
brokers and automatically provisions infrastructure for high availability.
How Is Amazon MQ Different from Amazon SQS or
Amazon SNS?
Amazon MQ is a managed message broker service that provides compatibility with many popular
message brokers. We recommend Amazon MQ for migrating applications from existing message brokers
that rely on compatibility with APIs such as JMS or protocols such as AMQP, MQTT, OpenWire, and
STOMP.
Amazon SQS and Amazon SNS are queue and topic services that are highly scalable, simple to use, and
don't require you to set up message brokers. We recommend these services for new applications that can
benefit from nearly unlimited scalability and simple APIs.
How Can I Get Started with Amazon MQ?
• To create your first broker with Amazon MQ, see Getting Started with Amazon MQ (p. 6).
• To discover the functionality and architecture of Amazon MQ, see How Amazon MQ Works (p. 29).
• To find out the guidelines and caveats that will help you make the most of Amazon MQ, see Best
Practices for Amazon MQ (p. 57).
• To learn about Amazon MQ REST APIs, see the Amazon MQ REST API Reference.
1
Amazon MQ Developer Guide
We Want to Hear from You
• To learn about Amazon MQ AWS CLI commands, see Amazon MQ in the AWS CLI Command Reference.
We Want to Hear from You
We welcome your feedback. To contact us, visit the Amazon MQ Discussion Forum.
2
Amazon MQ Developer Guide
Amazon MQ Developer Guide
New and Frequently Viewed Amazon
MQ Topics
Latest update: March 7, 2018
Amazon MQ Developer Guide
Most Frequently Viewed Topics
1. Working Java Example (p. 50)
2. Connecting a Java Application to Your Broker (p. 19)
3. Amazon MQ Basic Elements (p. 29)
4. Getting Started with Amazon MQ (p. 6)
5. Creating and Configuring a Broker (p. 11)
6. Amazon MQ Broker Architecture (p. 33)
7. Amazon MQ Broker Configuration Parameters (p. 37)
8. Limits in Amazon MQ (p. 61)
9. How Amazon MQ Works (p. 29)
10.Best Practices for Amazon MQ (p. 57)
Amazon MQ REST API Reference
Most Frequently Viewed Topics
1. Broker
2. Brokers
3. Resources
4. User
5. Configuration
6.
7.
8.
9.
Users
Broker Reboot
Configurations
Configuration Revision
10.Configuration Revisions
3
Amazon MQ Developer Guide
Step 1: Create an AWS Account
and an IAM Administrator User
Setting Up Amazon MQ
Before you can use Amazon MQ, you must complete the following steps.
Topics
• Step 1: Create an AWS Account and an IAM Administrator User (p. 4)
• Step 2: Create an IAM User and Get Your AWS Credentials (p. 4)
• Step 3: Get Ready to Use the Example Code (p. 5)
• Next Steps (p. 5)
Step 1: Create an AWS Account and an IAM
Administrator User
To access any AWS service, you must first create an AWS account. This is an Amazon account that can
use AWS products. You can use your AWS account to view your activity and usage reports and to manage
authentication and access.
1.
Navigate to the AWS home page, and then choose Create an AWS Account.
2.
Follow the instructions.
Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone
keypad.
3.
When you finish creating your AWS account, follow the instructions in the IAM User Guide to create
your first IAM administrator user and group.
Step 2: Create an IAM User and Get Your AWS
Credentials
To avoid using your IAM administrator user for Amazon MQ operations, it is a best practice to create an
IAM user for each person who needs administrative access to Amazon MQ.
To work with Amazon MQ, you need the AmazonMQFullAccess policy and AWS credentials that are
associated with your IAM user. These credentials are comprised of an access key ID and a secret access
key. For more information, see What Is IAM? in the IAM User Guide and AWS Security Credentials in the
AWS General Reference.
1.
Sign in to the AWS Identity and Access Management console.
2.
Choose Users, Add user.
3.
Type a User name, such as AmazonMQAdmin.
4.
Select Programmatic access and AWS Management Console access.
5.
Set a Console password and then choose Next: Permissions.
6.
On the Set permissions for AmazonMQAdmin page, choose Attach existing policies directly.
7.
Type AmazonMQ into the filter, choose AmazonMQFullAccess, and then choose Next: Review.
8.
On the Review page, choose Create user.
4
Amazon MQ Developer Guide
Step 3: Get Ready to Use the Example Code
The IAM user is created and the Access key ID is displayed, for example:
AKIAIOSFODNN7EXAMPLE
9.
To display your Secret access key, choose Show, for example:
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Important
You can view or download your secret access key only when you create your credentials
(however, you can create new credentials at any time).
10. To download your credentials, choose Download .csv. Keep this file in a secure location.
Step 3: Get Ready to Use the Example Code
The following tutorials show how you can work with Amazon MQ and ActiveMQ using the AWS
Management Console and Java. To use the example code, you must install the Java Standard Edition
Development Kit and make some changes to the code.
You can also create and manage brokers programmatically using Amazon MQ REST API and AWS SDKs.
Next Steps
Now that you're prepared to work with Amazon MQ, get started by creating a broker (p. 6) and then
connecting a Java application (p. 19) to your broker.
5
Amazon MQ Developer Guide
Prerequisites
Getting Started with Amazon MQ
This section will help you become more familiar with Amazon MQ by showing you how to create a broker
and how to connect your application to it.
Topics
• Prerequisites (p. 6)
• Step 1: Create an ActiveMQ Broker (p. 6)
• Step 2: Connect a Java Application to Your Broker (p. 7)
• Step 3: Delete Your Broker (p. 10)
• Next Steps (p. 10)
Prerequisites
Before you begin, complete the steps in Setting Up Amazon MQ (p. 4).
Step 1: Create an ActiveMQ Broker
A broker is a message broker environment running on Amazon MQ. It is the basic building block of
Amazon MQ. The combined description of the broker instance class (m4, t2) and size (large, micro) is a
broker instance type (for example, mq.m4.large). For more information, see Broker (p. 29).
The first and most common Amazon MQ task is creating a broker. The following example shows how you
can use the AWS Management Console to create a basic broker.
1.
Sign in to the Amazon MQ console.
2.
Do one of the following:
• If this is your first time using Amazon MQ, in the Create a broker section, type MyBroker for
Broker name and then choose Next step.
• If you have created a broker before, on the Create a broker page, in the Broker details section,
type MyBroker for Broker name.
3.
Choose a Broker instance type (for example, mq.m4.large). For more information, see Broker
Instance Types (p. 31).
4.
For Deployment mode, ensure that Single-instance broker is selected.
Note
Currently, Amazon MQ supports only the ActiveMQ broker engine, version 5.15.0.
5.
In the ActiveMQ Web Console access section, type a Username and Password.
6.
Choose Create broker.
While Amazon MQ creates your broker, it displays the Creation in progress status.
Creating the broker takes about 15 minutes.
When your broker is created successfully, Amazon MQ displays the Running status.
6
Amazon MQ Developer Guide
Step 2: Connect a Java Application to Your Broker
7.
Choose MyBroker.
On the MyBroker page, in the Connect section, note your broker's ActiveMQ Web Console URL, for
example:
https://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:8162
Also, note your broker's wire-level protocol Endpoints. The following is an example of an OpenWire
endpoint:
ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617
Step 2: Connect a Java Application to Your Broker
After you create an Amazon MQ broker, you can connect your application to it. The following examples
show how you can use the Java Message Service (JMS) to create a connection to the broker, create a
queue, and send a message. For a complete, working Java example, see Working Java Example (p. 50).
You can connect to ActiveMQ brokers using various ActiveMQ clients. We recommend using the
ActiveMQ Client.
Important
To ensure that your broker is accessible within your VPC, you must enable the
enableDnsHostnames and enableDnsSupport VPC attributes. For more information, see
DNS Support in your VPC in the Amazon VPC User Guide.
Prerequisites
Add the activemq-client.jar and activemq-pool.jar packages to your Java build class path. The
following example shows these dependencies in a Maven project pom.xml file.
<dependencies>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-client</artifactId>
<version>5.15.0</version>
</dependency>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-pool</artifactId>
<version>5.15.0</version>
</dependency>
</dependencies>
For more information about activemq-client.jar, see Initial Configuration in the Apache ActiveMQ
documentation.
Create a Message Producer and Send a Message
1.
Create a JMS pooled connection factory for the message producer using your broker's endpoint and
then call the createConnection method against the factory.
7
Amazon MQ Developer Guide
Create a Message Producer and Send a Message
Note
For an active/standby broker for high availability, Amazon MQ provides two ActiveMQ Web
Console URLs, but only one URL is active at a time. Likewise, Amazon MQ provides two
endpoints for each wire-level protocol, but only one endpoint is active in each pair at a
time. The -1 and -2 suffixes denote a redundant pair. For more information, see Amazon
MQ Broker Architecture (p. 33)).
For wire-level protocol endpoints, you can allow your application to connect to either
endpoint by using the Failover Transport.
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory for the producer.
final PooledConnectionFactory pooledConnectionFactoryProducer = new
PooledConnectionFactory();
pooledConnectionFactoryProducer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryProducer.setMaxConnections(10);
// Establish a connection for the producer.
final Connection producerConnection =
pooledConnectionFactoryProducer.createConnection();
producerConnection.start();
Note
Always use the PooledConnectionFactory class. For more information, see Always Use
Connection Pooling (p. 59).
2.
Create a session, a queue named MyQueue, and a message producer.
// Create a session.
final Session producerSession = producerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".
final Destination producerDestination = producerSession.createQueue("MyQueue");
// Create a producer from the session to the queue.
final MessageProducer producer = producerSession.createProducer(producerDestination);
producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
3.
Create the message string "Hello from Amazon MQ!" and then send the message.
// Create a message.
final String text = "Hello from Amazon MQ!";
final TextMessage producerMessage = producerSession.createTextMessage(text);
// Send the message.
producer.send(producerMessage);
System.out.println("Message sent.");
4.
Clean up the producer.
producer.close();
producerSession.close();
producerConnection.close();
8
Amazon MQ Developer Guide
Create a Message Consumer and Receive the Message
Create a Message Consumer and Receive the Message
1.
Create a JMS pooled connection factory for the message consumer using your broker's endpoint and
then call the createConnection method against the factory.
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory for the consumer.
final PooledConnectionFactory pooledConnectionFactoryConsumer = new
PooledConnectionFactory();
pooledConnectionFactoryConsumer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryConsumer.setMaxConnections(10);
// Establish a connection for the consumer.
final Connection consumerConnection =
pooledConnectionFactoryProducer.createConnection();
consumerConnection.start();
Note
Always use the PooledConnectionFactory class. For more information, see Always Use
Connection Pooling (p. 59).
2.
Create a session, a queue named MyQueue, and a message consumer.
// Create a session.
final Session consumerSession = consumerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".
final Destination consumerDestination = consumerSession.createQueue("MyQueue");
// Create a message consumer from the session to the queue.
final MessageConsumer consumer = consumerSession.createConsumer(consumerDestination);
3.
Begin to wait for messages and receive the message when it arrives.
// Begin to wait for messages.
final Message consumerMessage = consumer.receive(1000);
// Receive the message when it arrives.
final TextMessage consumerTextMessage = (TextMessage) consumerMessage;
System.out.println("Message received: " + consumerTextMessage.getText());
Note
Unlike AWS messaging services (such as Amazon SQS), the consumer is constantly
connected to the broker.
4.
Close the consumer, session, and connection.
consumer.close();
consumerSession.close();
consumerConnection.close();
pooledConnectionFactoryConsumer.stop();
9
Amazon MQ Developer Guide
Step 3: Delete Your Broker
Step 3: Delete Your Broker
If you don't use an Amazon MQ broker (and don't foresee using it in the near future), it is a best practice
to delete it from Amazon MQ to reduce your AWS costs.
The following example shows how you can delete a broker using the AWS Management Console.
1.
Sign in to the Amazon MQ console.
2.
3.
From the broker list, select your broker (for example, MyBroker) and then choose Delete.
In the Delete MyBroker? dialog box, type delete and then choose Delete.
Deleting a broker takes about 5 minutes.
Next Steps
Now that you have created a broker, connected an application to it, and sent and received a message,
you might want to try the following:
• Creating and Configuring a Broker (p. 11) (Advanced Settings)
• Creating and Applying Broker Configurations (p. 13)
• Editing and Managing Broker Configurations (p. 16)
• Listing Brokers and Viewing Broker Details (p. 22)
• Creating and Managing Amazon MQ Broker Users (p. 23)
• Rebooting a Broker (p. 25)
• Accessing CloudWatch Metrics for Amazon MQ (p. 26)
You can also begin to dive deep into Amazon MQ best practices (p. 57) and Amazon MQ REST APIs,
and then plan to migrate to Amazon MQ (p. 54).
10
Amazon MQ Developer Guide
Creating and Configuring a Broker
Amazon MQ Tutorials
The following tutorials show how you can work with Amazon MQ and ActiveMQ using the AWS
Management Console and Java. To use the example code, you must install the Java Standard Edition
Development Kit and make some changes to the code.
Topics
• Tutorial: Creating and Configuring an Amazon MQ Broker (p. 11)
• Tutorial: Creating and Applying Amazon MQ Broker Configurations (p. 13)
• Tutorial: Editing Amazon MQ Broker Configurations and Managing Configuration Revisions (p. 16)
• Tutorial: Connecting a Java Application to Your Amazon MQ Broker (p. 19)
• Tutorial: Listing Amazon MQ Brokers and Viewing Broker Details (p. 22)
• Tutorial: Creating and Managing Amazon MQ Broker Users (p. 23)
• Tutorial: Rebooting an Amazon MQ Broker (p. 25)
• Tutorial: Deleting an Amazon MQ Broker (p. 26)
• Tutorial: Accessing CloudWatch Metrics for Amazon MQ (p. 26)
Tutorial: Creating and Configuring an Amazon MQ
Broker
A broker is a message broker environment running on Amazon MQ. It is the basic building block of
Amazon MQ. The combined description of the broker instance class (m4, t2) and size (large, micro) is a
broker instance type (for example, mq.m4.large). For more information, see Broker (p. 29).
The first and most common Amazon MQ task is creating a broker. The following example shows how you
can use the AWS Management Console to create and configure a broker using the AWS Management
Console.
Topics
• Step 1: Configure basic broker settings (p. 11)
• Step 2: (Optional) Configure advanced broker settings (p. 12)
• Step 3: Finish creating the broker (p. 13)
Step 1: Configure basic broker settings
1.
Sign in to the Amazon MQ console.
2.
Do one of the following:
• If this is your first time using Amazon MQ, in the Create a broker section, type MyBroker for
Broker name and then choose Next step.
• If you have created a broker before, on the Create a broker page, in the Broker details section,
type MyBroker for Broker name.
3.
Choose a Broker instance type (for example, mq.m4.large). For more information, see Broker
Instance Types (p. 31).
11
Amazon MQ Developer Guide
Step 2: (Optional) Configure advanced broker settings
4.
Choose a Deployment mode:
• A Single-instance broker is comprised of one broker in one Availability Zone. The broker
communicates with your application and with an AWS storage location. For more information, see
Single-Instance Broker (p. 33).
• An Active/standby broker for high availability is comprised of two brokers in two different
Availability Zones, configured in a redundant pair. These brokers communicate synchronously with
your application, and with a shared storage location. For more information, see Active/Standby
Broker for High Availability (p. 34).
Note
Currently, Amazon MQ supports only the ActiveMQ broker engine, version 5.15.0.
5.
In the ActiveMQ Web Console access section, type a Username and Password.
Step 2: (Optional) Configure advanced broker
settings
Important
• Subnet(s) – A single-instance broker requires one subnet (for example, the default subnet). An
active/standby broker for high availability requires two subnets.
• Security group(s) – Both single-instance brokers and active/standby brokers for high
availability require at least one security group (for example, the default security group).
• VPC – A broker's subnet(s) and security group(s) must be in the same VPC. EC2-Classic
resources aren't supported.
• Public accessibility – Disabling public accessibility makes the broker accessible only within
your VPC. For more information, see Prefer Brokers without Public Accessibility (p. 57).
1.
Expand the Advanced settings section.
2.
In the Configuration section, choose Create a new configuration with default values or Select an
existing configuration. For more information, see Configuration (p. 31) and Amazon MQ Broker
Configuration Parameters (p. 37).
3.
In the Network and security section, configure your broker's connectivity:
4.
a.
Select the default Virtual Private Cloud (VPC) or create a new one on the Amazon VPC console.
For more information, see What is Amazon VPC? in the Amazon VPC User Guide.
b.
Select the default Subnets or create new ones on the Amazon VPC console. For more
information, see VPCs and Subnets in the Amazon VPC User Guide.
c.
Select your Security group(s).
d.
Choose the Public accessibility of your broker.
In the Maintenance section, configure your broker's maintenance schedule:
a.
To upgrade the broker to new versions as Apache releases them, choose Enable automatic
minor version upgrades. Automatic upgrades occur during the maintenance window, defined by
the day of the week, the time of day (in 24-hour format), and the time zone (UTC by default).
b.
Do one of the following:
• To allow Amazon MQ to select the maintenance window automatically, choose No
preference.
• To set a custom maintenance window, choose Select maintenance window and then specify
the Start day and Start time of the upgrades.
12
Amazon MQ Developer Guide
Step 3: Finish creating the broker
Step 3: Finish creating the broker
1.
Choose Create broker.
While Amazon MQ creates your broker, it displays the Creation in progress status.
Creating the broker takes about 15 minutes.
When your broker is created successfully, Amazon MQ displays the Running status.
2.
Choose MyBroker.
On the MyBroker page, in the Connect section, note your broker's ActiveMQ Web Console URL, for
example:
https://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:8162
Also, note your broker's wire-level protocol Endpoints. The following is an example of an OpenWire
endpoint:
ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617
Note
For an active/standby broker for high availability, Amazon MQ provides two ActiveMQ Web
Console URLs, but only one URL is active at a time. Likewise, Amazon MQ provides two
endpoints for each wire-level protocol, but only one endpoint is active in each pair at a time.
The -1 and -2 suffixes denote a redundant pair. For more information, see Amazon MQ Broker
Architecture (p. 33)).
For wire-level protocol endpoints, you can allow your application to connect to either endpoint
by using the Failover Transport.
Tutorial: Creating and Applying Amazon MQ
Broker Configurations
A configuration contains all of the settings for your ActiveMQ broker, in XML format (similar to
ActiveMQ's activemq.xml file). You can create a configuration before creating any brokers. You can
then apply the configuration to one or more brokers. You can apply a configuration immediately or
during a maintenance window. For more information, see the following:
• Configuration (p. 31)
• Amazon MQ Broker Configuration Lifecycle (p. 36)
• Amazon MQ Broker Configuration Parameters (p. 37)
• Editing and Managing Broker Configurations (p. 16)
The following example shows how you can create and apply an Amazon MQ broker configuration using
the AWS Management Console.
13
Amazon MQ Developer Guide
Step 1: Create a configuration from scratch
Topics
• Step 1: Create a configuration from scratch (p. 14)
• Step 2: Create a new configuration revision (p. 14)
• Step 3: Apply a configuration revision to your broker (p. 15)
Step 1: Create a configuration from scratch
1.
Sign in to the Amazon MQ console.
2.
On the left, expand the navigation panel and choose Configurations.
3.
On the Configurations page, choose Create configuration.
4.
On the Create configuration page, in the Details section, type the Configuration name (for
example, MyConfiguration).
Note
Currently, Amazon MQ supports only the ActiveMQ broker engine, version 5.15.0.
5.
Choose Create configuration.
Step 2: Create a new configuration revision
1.
From the configuration list, choose MyConfiguration.
Note
The first configuration revision is always created for you when Amazon MQ creates the
configuration.
On the MyConfiguration page, the broker engine type and version that your new configuration
revision uses (for example, Apache ActiveMQ 5.15.0) are displayed.
2.
On the Configuration details tab, the configuration revision number, description, and broker
configuration in XML format are displayed.
Note
Editing the current configuration creates a new configuration revision.
3.
Choose Edit configuration and make changes to the XML configuration.
14
Amazon MQ Developer Guide
Step 3: Apply a configuration revision to your broker
4.
Choose Save.
The Save revisions dialog box is displayed.
5.
(Optional) Type A description of the changes in this revision.
6.
Choose Save.
The new revision of the configuration is saved.
Important
The Amazon MQ console automatically sanitizes invalid and prohibited configuration
parameters according to a schema. For more information and a full list of permitted XML
parameters, see Amazon MQ Broker Configuration Parameters (p. 37).
Making changes to a configuration does not apply the changes to the broker immediately.
To apply your changes, you must wait for the next maintenance window (p. 18) or
reboot the broker (p. 25). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 36).
Currently, it isn't possible to delete a configuration.
Step 3: Apply a configuration revision to your broker
1.
On the left, expand the navigation panel and choose Brokers.
2.
From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3.
On the Edit MyBroker page, in the Configuration section, select a Configuration
and then choose Schedule Modifications .
4.
In the Schedule broker modifications section, choose whether to apply modifications During the
next scheduled maintenance window or Immediately.
Important
Your broker will be offline while it is being rebooted.
5.
Choose Apply.
Your configuration revision is applied to your broker at the specified time.
15
and a Revision
Amazon MQ Developer Guide
Editing Configurations and
Managing Configuration Revisions
Tutorial: Editing Amazon MQ Broker
Configurations and Managing Configuration
Revisions
A configuration contains all of the settings for your ActiveMQ broker, in XML format (similar to
ActiveMQ's activemq.xml file). You can apply a configuration immediately or during a maintenance
window. To keep track of the changes you make to your configuration, you can create configuration
revisions. For more information, see the following:
• Configuration (p. 31)
• Amazon MQ Broker Configuration Lifecycle (p. 36)
• Amazon MQ Broker Configuration Parameters (p. 37)
• Creating and Applying Broker Configurations (p. 13)
The following examples show how you can edit Amazon MQ broker configurations and manage broker
configuration revisions using the AWS Management Console.
Topics
• To view a previous configuration revision (p. 16)
• To edit the current configuration revision (p. 17)
• To apply a configuration revision to your broker (p. 18)
• To roll back your broker to the last configuration revision (p. 18)
To view a previous configuration revision
1.
Sign in to the Amazon MQ console.
2.
From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3.
On the Edit MyBroker page, in the Configuration section, select a Configuration
and then choose View .
and a Revision
Note
Unless you select a configuration when you create a broker, the first configuration revision
is always created for you when Amazon MQ creates the broker.
On the MyBroker page, the broker engine type and version that the configuration uses (for
example, Apache ActiveMQ 5.15.0) are displayed.
4.
Choose Revision history.
5.
The configuration Revision number, Revision date, and Description are displayed for each revision.
6.
Select a revision and choose View details.
The broker configuration in XML format is displayed.
16
Amazon MQ Developer Guide
To edit the current configuration revision
To edit the current configuration revision
1.
Sign in to the Amazon MQ console.
2.
From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3.
On the MyBroker page, choose Edit.
4.
On the Edit MyBroker page, in the Configuration section, select a Configuration
and then choose View .
and a Revision
Note
Unless you select a configuration when you create a broker, the first configuration revision
is always created for you when Amazon MQ creates the broker.
On the MyBroker page, the broker engine type and version that the configuration uses (for
example, Apache ActiveMQ 5.15.0) are displayed.
5.
On the Configuration details tab, the configuration revision number, description, and broker
configuration in XML format are displayed.
Note
Editing the current configuration creates a new configuration revision.
6.
Choose Edit configuration and make changes to the XML configuration.
7.
Choose Save.
The Save revisions dialog box is displayed.
8.
(Optional) Type A description of the changes in this revision.
9.
Choose Save.
The new revision of the configuration is saved.
Important
The Amazon MQ console automatically sanitizes invalid and prohibited configuration
parameters according to a schema. For more information and a full list of permitted XML
parameters, see Amazon MQ Broker Configuration Parameters (p. 37).
Making changes to a configuration does not apply the changes to the broker immediately.
To apply your changes, you must wait for the next maintenance window (p. 18) or
17
Amazon MQ Developer Guide
To apply a configuration revision to your broker
reboot the broker (p. 25). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 36).
Currently, it isn't possible to delete a configuration.
To apply a configuration revision to your broker
1.
Sign in to the Amazon MQ console.
2.
From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3.
On the Edit MyBroker page, in the Configuration section, select a Configuration
and then choose Schedule Modifications .
4.
In the Schedule broker modifications section, choose whether to apply modifications During the
next scheduled maintenance window or Immediately.
and a Revision
Important
Your broker will be offline while it is being rebooted.
5.
Choose Apply.
Your configuration revision is applied to your broker at the specified time.
To roll back your broker to the last configuration
revision
1.
Sign in to the Amazon MQ console.
2.
From the broker list, choose the name of your broker (for example, MyBroker).
3.
On the MyBroker page, choose Actions, Roll back to last configuration.
4.
(Optional) To review the Current configuration or the Last configuration, on the Roll back to the
last configuration page, in the Summary section, choose View for either configuration.
5.
In the Schedule broker modifications section, choose whether to apply modifications During the
next scheduled maintenance window or Immediately.
Important
Your broker will be offline while it is being rebooted.
6.
Choose Apply.
Your configuration revision is applied to your broker at the specified time.
18
Amazon MQ Developer Guide
Connecting a Java Application to Your Broker
Tutorial: Connecting a Java Application to Your
Amazon MQ Broker
After you create an Amazon MQ broker, you can connect your application to it. The following examples
show how you can use the Java Message Service (JMS) to create a connection to the broker, create a
queue, and send a message. For a complete, working Java example, see Working Java Example (p. 50).
You can connect to ActiveMQ brokers using various ActiveMQ clients. We recommend using the
ActiveMQ Client.
Important
To ensure that your broker is accessible within your VPC, you must enable the
enableDnsHostnames and enableDnsSupport VPC attributes. For more information, see
DNS Support in your VPC in the Amazon VPC User Guide.
Topics
• Prerequisites (p. 19)
• To create a message producer and send a message (p. 20)
• To create a message consumer and receive the message (p. 21)
Prerequisites
Enable Inbound Connections
1.
2.
Sign in to the Amazon MQ console.
From the broker list, choose the name of your broker (for example, MyBroker).
3.
On the MyBroker page, in the Connections section, note the addresses and ports of the broker's
ActiveMQ Web Console URL and wire-level protocols.
4.
In the Details section, under Security and network, choose the name of your security group or
5.
6.
The Security Groups page of the EC2 Dashboard is displayed.
From the security group list, choose your security group.
At the bottom of the page, choose Inbound, and then choose Edit.
7.
.
In the Edit inbound rules dialog box, add a rule for every URL or endpoint that you want to be
publicly accessible (the following example shows how to do this for an ActiveMQ Web Console).
a.
b.
Choose Add Rule.
For Type, select Custom TCP.
c.
d.
For Port Range, type the ActiveMQ Web Console port (8162).
For Source, leave Custom selected and then type the IP address of the system that you want to
be able to access the ActiveMQ Web Console (for example, 192.0.2.1).
e.
Choose Save.
Your broker can now accept inbound connections.
Add Java Dependencies
To allow your application to work with ActiveMQ, add the activemq-client.jar and activemqpool.jar packages to your Java build class path. The following example shows these dependencies in
your Maven project's pom.xml file.
19
Amazon MQ Developer Guide
To create a message producer and send a message
<dependencies>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-client</artifactId>
<version>5.15.0</version>
</dependency>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-pool</artifactId>
<version>5.15.0</version>
</dependency>
</dependencies>
For more information about activemq-client.jar, see Initial Configuration in the Apache ActiveMQ
documentation.
To create a message producer and send a message
1.
Create a JMS pooled connection factory for the message producer using your broker's endpoint and
then call the createConnection method against the factory.
Note
For an active/standby broker for high availability, Amazon MQ provides two ActiveMQ Web
Console URLs, but only one URL is active at a time. Likewise, Amazon MQ provides two
endpoints for each wire-level protocol, but only one endpoint is active in each pair at a
time. The -1 and -2 suffixes denote a redundant pair. For more information, see Amazon
MQ Broker Architecture (p. 33)).
For wire-level protocol endpoints, you can allow your application to connect to either
endpoint by using the Failover Transport.
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory for the producer.
final PooledConnectionFactory pooledConnectionFactoryProducer = new
PooledConnectionFactory();
pooledConnectionFactoryProducer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryProducer.setMaxConnections(10);
// Establish a connection for the producer.
final Connection producerConnection =
pooledConnectionFactoryProducer.createConnection();
producerConnection.start();
Note
Always use the PooledConnectionFactory class. For more information, see Always Use
Connection Pooling (p. 59).
2.
Create a session, a queue named MyQueue, and a message producer.
// Create a session.
final Session producerSession = producerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".
final Destination producerDestination = producerSession.createQueue("MyQueue");
20
Amazon MQ Developer Guide
To create a message consumer and receive the message
// Create a producer from the session to the queue.
final MessageProducer producer = producerSession.createProducer(producerDestination);
producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
3.
Create the message string "Hello from Amazon MQ!" and then send the message.
// Create a message.
final String text = "Hello from Amazon MQ!";
final TextMessage producerMessage = producerSession.createTextMessage(text);
// Send the message.
producer.send(producerMessage);
System.out.println("Message sent.");
4.
Clean up the producer.
producer.close();
producerSession.close();
producerConnection.close();
To create a message consumer and receive the
message
1.
Create a JMS pooled connection factory for the message consumer using your broker's endpoint and
then call the createConnection method against the factory.
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory for the consumer.
final PooledConnectionFactory pooledConnectionFactoryConsumer = new
PooledConnectionFactory();
pooledConnectionFactoryConsumer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryConsumer.setMaxConnections(10);
// Establish a connection for the consumer.
final Connection consumerConnection =
pooledConnectionFactoryProducer.createConnection();
consumerConnection.start();
Note
Always use the PooledConnectionFactory class. For more information, see Always Use
Connection Pooling (p. 59).
2.
Create a session, a queue named MyQueue, and a message consumer.
// Create a session.
final Session consumerSession = consumerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".
final Destination consumerDestination = consumerSession.createQueue("MyQueue");
21
Amazon MQ Developer Guide
Listing Brokers and Viewing Broker Details
// Create a message consumer from the session to the queue.
final MessageConsumer consumer = consumerSession.createConsumer(consumerDestination);
3.
Begin to wait for messages and receive the message when it arrives.
// Begin to wait for messages.
final Message consumerMessage = consumer.receive(1000);
// Receive the message when it arrives.
final TextMessage consumerTextMessage = (TextMessage) consumerMessage;
System.out.println("Message received: " + consumerTextMessage.getText());
Note
Unlike AWS messaging services (such as Amazon SQS), the consumer is constantly
connected to the broker.
4.
Close the consumer, session, and connection.
consumer.close();
consumerSession.close();
consumerConnection.close();
pooledConnectionFactoryConsumer.stop();
Tutorial: Listing Amazon MQ Brokers and Viewing
Broker Details
When you request that Amazon MQ create a broker, the creation process can take about 15 minutes..
The following example shows how you can confirm your broker's existence by listing your brokers in the
current region using the AWS Management Console.
To list brokers and view broker details
1.
Sign in to the Amazon MQ console.
Your brokers in the current region are listed.
The following information is displayed for each broker:
•
•
•
•
2.
Name
Creation date
Status (p. 31)
Deployment mode (p. 33)
• Instance type (p. 31)
Choose your broker's name (for example, MyBroker).
On the MyBroker page, the configured (p. 31) Details are displayed for your broker:
22
Amazon MQ Developer Guide
Creating and Managing Broker Users
Below the Details section, the following information is displayed:
• In the Connections section, the ActiveMQ Web Console URL and the wire-level protocol endpoints
• In the Users section, the users (p. 32) associated with the broker
Tutorial: Creating and Managing Amazon MQ
Broker Users
An ActiveMQ user is a person or an application that can access the queues and topics of an ActiveMQ
broker. You can configure users to have specific permissions. For example, you can allow some users to
access the ActiveMQ Web Console.
A user can belong to a group. You can configure which users belong to which groups and which groups
have permission to send to, receive from, and administer specific queues and topics.
The following examples show how you can create, edit, and delete Amazon MQ broker users using the
AWS Management Console.
Topics
• To create a new user (p. 24)
• To edit an existing user (p. 24)
23
Amazon MQ Developer Guide
To create a new user
• To delete a existing user (p. 25)
To create a new user
1.
Sign in to the Amazon MQ console.
2.
From the broker list, choose the name of your broker (for example, MyBroker) and then choose Edit.
On the MyBroker page, in the Users section, all the users for this broker are listed.
3.
Choose Create user.
4.
In the Create user dialog box, type a Username and Password.
5.
(Optional) Type the names of groups to which the user belongs, separated by commas (for example:
Devs, Admins).
6.
(Optional) To enable the user to access the ActiveMQ Web Console, choose ActiveMQ Web Console.
7.
Choose Create user.
Important
Making changes to a user does not apply the changes to the user immediately. To apply
your changes, you must wait for the next maintenance window (p. 18) or reboot
the broker (p. 25). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 36).
To edit an existing user
1.
Sign in to the Amazon MQ console.
2.
From the broker list, choose the name of your broker (for example, MyBroker) and then choose Edit.
On the MyBroker page, in the Users section, all the users for this broker are listed.
3.
Select a username and choose Edit.
The Edit user dialog box is displayed.
4.
(Optional) Type a new Password.
5.
(Optional) Add or remove the names of groups to which the user belongs, separated by commas (for
example: Managers, Admins).
6.
(Optional) To enable the user to access the ActiveMQ Web Console, choose ActiveMQ Web Console.
7.
To save the changes to the user, choose Done.
Important
Making changes to a user does not apply the changes to the user immediately. To apply
your changes, you must wait for the next maintenance window (p. 18) or reboot
24
Amazon MQ Developer Guide
To delete a existing user
the broker (p. 25). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 36).
To delete a existing user
1.
Sign in to the Amazon MQ console.
2.
From the broker list, choose the name of your broker (for example, MyBroker) and then choose Edit.
On the MyBroker page, in the Users section, all the users for this broker are listed.
3.
Select a username (for example, MyUser) and then choose Delete.
4.
To confirm deleting the user, in the Delete MyUser? dialog box, choose Delete.
Important
Making changes to a user does not apply the changes to the user immediately. To apply
your changes, you must wait for the next maintenance window (p. 18) or reboot
the broker (p. 25). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 36).
Tutorial: Rebooting an Amazon MQ Broker
To apply a new configuration to a broker, you can reboot the broker. In addition, if your broker becomes
unresponsive, you can reboot it to recover from a faulty state.
The following example shows how you can reboot an Amazon MQ broker using the AWS Management
Console.
To reboot an Amazon MQ broker
1.
Sign in to the Amazon MQ console.
2.
From the broker list, choose the name of your broker (for example, MyBroker).
3.
On the MyBroker page, choose Actions, Reboot broker.
Important
Your broker will be offline while it is being rebooted.
4.
In the Reboot broker dialog box, choose Reboot.
Rebooting the broker takes about 5 minutes.
25
Amazon MQ Developer Guide
Deleting a Broker
Tutorial: Deleting an Amazon MQ Broker
If you don't use an Amazon MQ broker (and don't foresee using it in the near future), it is a best practice
to delete it from Amazon MQ to reduce your AWS costs.
The following example shows how you can delete a broker using the AWS Management Console.
To delete an Amazon MQ broker
1.
Sign in to the Amazon MQ console.
2.
From the broker list, select your broker (for example, MyBroker) and then choose Delete.
3.
In the Delete MyBroker? dialog box, type delete and then choose Delete.
Deleting a broker takes about 5 minutes.
Tutorial: Accessing CloudWatch Metrics for
Amazon MQ
Amazon MQ and Amazon CloudWatch are integrated so you can use CloudWatch to view and analyze
metrics for your ActiveMQ broker and the broker's destinations (queues and topics). You can view and
analyze your Amazon MQ metrics from the CloudWatch console, the AWS CLI, or the CloudWatch CLI.
CloudWatch metrics for Amazon MQ are automatically polled from the broker and then pushed to
CloudWatch every minute.
For a full list of Amazon MQ metrics, see Monitoring Amazon MQ using CloudWatch (p. 64).
For information about creating a CloudWatch alarm for a metrics, see Create or Edit a CloudWatch Alarm
in the Amazon CloudWatch User Guide.
Note
There is no charge for the Amazon MQ metrics reported in CloudWatch. These metrics are
provided as part of the Amazon MQ service.
CloudWatch monitors only the first 200 destinations.
Topics
• AWS Management Console (p. 26)
• AWS Command Line Interface (p. 28)
• Amazon CloudWatch API (p. 28)
AWS Management Console
The following example shows you how to access CloudWatch metrics for Amazon MQ using the AWS
Management Console.
Note
If you're already signed into the Amazon MQ console, on the broker Details page, choose
Actions, View CloudWatch metrics.
26
Amazon MQ Developer Guide
AWS Management Console
1.
Sign in to the CloudWatch console.
2.
On the navigation panel, choose Metrics.
3.
Select the AmazonMQ metric namespace.
4.
Select one of the following metric dimensions:
• Broker Metrics
• Queue Metrics by Broker
• Topic Metrics by Broker
In this example, Broker Metrics is selected.
5.
You can now examine your Amazon MQ metrics:
• To sort the metrics, use the column heading.
• To graph the metric, select the check box next to the metric.
• To filter by metric, choose the metric name and then choose Add to search.
27
Amazon MQ Developer Guide
AWS Command Line Interface
AWS Command Line Interface
To access Amazon MQ metrics using the AWS CLI, use the get-metric-statistics command.
For more information, see Get Statistics for a Metric in the Amazon CloudWatch User Guide.
Amazon CloudWatch API
To access Amazon MQ metrics using the CloudWatch API, use the GetMetricStatistics action.
For more information, see Get Statistics for a Metric in the Amazon CloudWatch User Guide.
28
Amazon MQ Developer Guide
Basic Elements
How Amazon MQ Works
Amazon MQ makes it easy to create a message broker with the computing and storage resources that fit
your needs. You can create, manage, and delete brokers using the AWS Management Console, Amazon
MQ REST API, or the AWS Command Line Interface.
This section describes the basic elements of a message broker, lists available Amazon MQ broker instance
types and their statuses, provides an overview of broker architecture, explains broker configuration
parameters and offers a working example of using Java Message Service (JMS) with an ActiveMQ broker.
To learn about Amazon MQ REST APIs, see the Amazon MQ REST API Reference.
Topics
• Amazon MQ Basic Elements (p. 29)
• Amazon MQ Broker Architecture (p. 33)
• Amazon MQ Broker Configuration Lifecycle (p. 36)
• Amazon MQ Broker Configuration Parameters (p. 37)
• Working Example of Using Java Message Service (JMS) with ActiveMQ (p. 50)
Amazon MQ Basic Elements
This section introduces key concepts essential to understanding Amazon MQ.
Topics
• Broker (p. 29)
• Configuration (p. 31)
• Engine (p. 32)
• User (p. 32)
Broker
A broker is a message broker environment running on Amazon MQ. It is the basic building block of
Amazon MQ. The combined description of the broker instance class (m4, t2) and size (large, micro)
is a broker instance type (for example, mq.m4.large). For more information, see Broker Instance
Types (p. 31).
• A single-instance broker is comprised of one broker in one Availability Zone. The broker communicates
with your application and with an AWS storage location.
• An active/standby broker for high availability is comprised of two brokers in two different Availability
Zones, configured in a redundant pair. These brokers communicate synchronously with your
application, and with a shared storage location.
For more information, see Amazon MQ Broker Architecture (p. 33).
29
Amazon MQ Developer Guide
Broker
You can enable automatic minor version upgrades to new minor versions of the broker engine, as Apache
releases new versions. Automatic upgrades occur during the maintenance window, defined by the day of
the week, the time of day (in 24-hour format), and the time zone (UTC by default).
For information about creating and managing brokers, see the following:
• Creating and Configuring a Broker (p. 11)
• Limits Related to Brokers (p. 61)
• Broker Statuses (p. 31)
Attributes
A broker has several attributes, for example:
• A name (MyBroker)
• An ID (b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9)
• An Amazon Resource Name (ARN) (arn:aws:mq:useast-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9)
• An ActiveMQ Web Console URL (https://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:8162)
For more information, see Web Console in the Apache ActiveMQ documentation.
Important
If you specify an authorization map which doesn't include the activemq-webconsole group,
you won't be able to use the ActiveMQ Web Console because the group isn't authorized to
send messages to, or receive messages from, the Amazon MQ broker.
• Wire-level protocol endpoints:
• amqp+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.useast-2.amazonaws.com:5671
• mqtt+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.useast-2.amazonaws.com:8883
• ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.useast-2.amazonaws.com:61617
Note
This is an OpenWire endpoint.
• stomp+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.useast-2.amazonaws.com:61614
• wss://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.useast-2.amazonaws.com:61619
For more information, see Configuring Transports in the Apache ActiveMQ documentation.
Note
For an active/standby broker for high availability, Amazon MQ provides two ActiveMQ Web
Console URLs, but only one URL is active at a time. Likewise, Amazon MQ provides two
endpoints for each wire-level protocol, but only one endpoint is active in each pair at a time.
The -1 and -2 suffixes denote a redundant pair.
For a full list of broker attributes, see the following in the Amazon MQ REST API Reference:
• REST Operation ID: Broker
• REST Operation ID: Brokers
30
Amazon MQ Developer Guide
Configuration
• REST Operation ID: Broker Reboot
Instance Types
The combined description of the broker instance class (m4, t2) and size (large, micro) is a broker
instance type (for example, mq.m4.large). The following table lists the available Amazon MQ broker
instance types.
Instance Type
vCPU
Memory (GiB)
Network Performance
2
8
Moderate
1
1
Low
Standard
mq.m4.large
Micro-Instance
mq.t2.micro
Note
The mq.t2.micro instance type (single-instance brokers only) qualifies for the AWS Free Tier.
Using the mq.t2.micro instance type is subject to CPU credits and baseline performance—
with the ability to burst above the baseline level. If your application requires fixed performance,
consider using an mq.m4.large instance type.
Statuses
A broker's current condition is indicated by a status. The following table lists the statuses of an Amazon
MQ broker.
Console
API
Description
Creation failed
CREATION_FAILED
The broker couldn't be created.
Creation in progress
CREATION_IN_PROGRESS
The broker is currently being
created.
Deletion in progress
DELETION_IN_PROGRESS
The broker is currently being
deleted.
Reboot in progress
REBOOT_IN_PROGRESS
The broker is currently being
rebooted.
Running
RUNNING
The broker is operational.
Configuration
A configuration contains all of the settings for your ActiveMQ broker, in XML format (similar to
ActiveMQ's activemq.xml file). You can create a configuration before creating any brokers. You can
then apply the configuration to one or more brokers.
Important
Making changes to a configuration does not apply the changes to the broker immediately. To
apply your changes, you must wait for the next maintenance window (p. 18) or reboot the
broker (p. 25). For more information, see Amazon MQ Broker Configuration Lifecycle (p. 36).
31
Amazon MQ Developer Guide
Engine
Currently, it isn't possible to delete a configuration.
For information about creating, editing, and managing configurations, see the following:
• Creating and Applying Broker Configurations (p. 13)
• Editing and Managing Broker Configurations (p. 16)
• Limits Related to Configurations (p. 61)
• Amazon MQ Broker Configuration Parameters (p. 37)
To keep track of the changes you make to your configuration, you can create configuration revisions. For
more information, see Creating and Applying Broker Configurations (p. 13) and Editing and Managing
Broker Configurations (p. 16).
Attributes
A broker configuration has several attributes, for example:
• A name (MyConfiguration)
• An ID (c-1234a5b6-78cd-901e-2fgh-3i45j6k178l9)
• An Amazon Resource Name (ARN) (arn:aws:mq:useast-2:123456789012:configuration:MyConfiguration:c-1234a5b6-78cd-901e-2fgh-3i45j6k178l9
For a full list of configuration attributes, see the following in the Amazon MQ REST API Reference:
• REST Operation ID: Configuration
• REST Operation ID: Configurations
For a full list of configuration revision attributes, see the following:
• REST Operation ID: Configuration Revision
• REST Operation ID: Configuration Revisions
Engine
A broker engine is a type of message broker that runs on Amazon MQ.
Note
Currently, Amazon MQ supports only the ActiveMQ broker engine, version 5.15.0.
User
An ActiveMQ user is a person or an application that can access the queues and topics of an ActiveMQ
broker. You can configure users to have specific permissions. For example, you can allow some users to
access the ActiveMQ Web Console.
A user can belong to a group. You can configure which users belong to which groups and which groups
have permission to send to, receive from, and administer specific queues and topics.
Important
Making changes to a user does not apply the changes to the user immediately. To apply your
changes, you must wait for the next maintenance window (p. 18) or reboot the broker (p. 25).
For more information, see Amazon MQ Broker Configuration Lifecycle (p. 36).
32
Amazon MQ Developer Guide
Broker Architecture
For information about users and groups, see the following in the Apache ActiveMQ documentation:
• Authorization
• Authorization Example
For information about creating, editing, and deleting ActiveMQ users, see the following:
• Creating and Managing Amazon MQ Broker Users (p. 23)
• Limits Related to Users (p. 62)
Attributes
For a full list of user attributes, see the following in the Amazon MQ REST API Reference:
• REST Operation ID: User
• REST Operation ID: Users
Amazon MQ Broker Architecture
Amazon MQ brokers can be created as single-instance brokers or active/standby brokers for high
availability. For both deployment modes, Amazon MQ provides high durability by storing its data
redundantly, across multiple Availability Zones (multi-AZs) within an AWS Region. Amazon MQ ensures
high availability by providing failover to a standby instance in a second Availability Zone.
Note
Amazon MQ uses Apache KahaDB as its data store. Other data stores, such as JDBC and LevelDB,
aren't supported.
Topics
• Single-Instance Broker (p. 33)
• Active/Standby Broker for High Availability (p. 34)
• Concurrent Store and Dispatch for Queues (p. 35)
Single-Instance Broker
A single-instance broker is comprised of one broker in one Availability Zone. The broker communicates
with your application and with an AWS storage location.
The following diagram illustrates a single-instance broker.
33
Amazon MQ Developer Guide
Active/Standby Broker for High Availability
Active/Standby Broker for High Availability
An active/standby broker for high availability is comprised of two brokers in two different Availability
Zones, configured in a redundant pair. These brokers communicate synchronously with your application,
and with a shared storage location.
Normally, only one of the broker instances is active at any time, while the other broker instance is on
standby. If one of the broker instances malfunctions, it takes Amazon MQ a short while to take the
malfunctioning instance out of service, allowing the healthy standby instance to become active and
to begin accepting incoming communications. When you reboot a broker, the failover takes only a few
seconds.
For an active/standby broker for high availability, Amazon MQ provides two ActiveMQ Web Console
URLs, but only one URL is active at a time. Likewise, Amazon MQ provides two endpoints for each wirelevel protocol, but only one endpoint is active in each pair at a time. The -1 and -2 suffixes denote a
redundant pair. For wire-level protocol endpoints, you can allow your application to connect to either
endpoint by using the Failover Transport.
The following diagram illustrates an active/standby broker for high availability.
34
Amazon MQ Developer Guide
Concurrent Store and Dispatch for Queues
Concurrent Store and Dispatch for Queues
By default, producers send messages to the Amazon MQ thread pool , and consumers receive
messages from the thread pool and then acknowledge the receipt. However, in cases when your
consumer are slower than your producers, or if the combined number of your consumers is insufficient,
messages are sent into storage .
By setting the concurrentStoreAndDispatchQueues attribute to false, you allow messages
directed to and retrieved from storage .
35
to be
Amazon MQ Developer Guide
Broker Configuration Lifecycle
For an example configuration, see concurrentStoreAndDispatchQueues (p. 50).
Amazon MQ Broker Configuration Lifecycle
Making changes to a configuration revision or an ActiveMQ user does not apply the changes immediately.
To apply your changes, you must wait for the next maintenance window (p. 18) or reboot the
broker (p. 25). For more information, see Amazon MQ Broker Configuration Lifecycle (p. 36).
The following diagram illustrates the configuration lifecycle.
Important
The next scheduled maintenance window triggers a reboot. If the broker is rebooted before the
next scheduled maintenance window, the changes are applied after the reboot.
For information about creating, editing, and managing configurations, see the following:
36
Amazon MQ Developer Guide
Broker Configuration Parameters
• Creating and Applying Broker Configurations (p. 13)
• Editing and Managing Broker Configurations (p. 16)
• Amazon MQ Broker Configuration Parameters (p. 37)
For information about creating, editing, and deleting ActiveMQ users, see the following:
• Creating and Managing Amazon MQ Broker Users (p. 23)
• Limits Related to Users (p. 62)
Amazon MQ Broker Configuration Parameters
A configuration contains all of the settings for your ActiveMQ broker, in XML format (similar to
ActiveMQ's activemq.xml file). You can create a configuration before creating any brokers. You can
then apply the configuration to one or more brokers. For more information, see the following:
• Configuration (p. 31)
• Creating and Applying Broker Configurations (p. 13)
• Editing and Managing Broker Configurations (p. 16)
• Limits Related to Configurations (p. 61)
Working with Spring XML Configuration Files
ActiveMQ brokers are configured using Spring XML files. You can configure many aspects of your
ActiveMQ broker, such as predefined destinations, destination policies, authorization policies, and
plugins. Amazon MQ controls some of these configuration elements, such as network transports and
storage. Other configuration options, such as creating networks of brokers, aren't currently supported.
The full set of supported configuration options is specified in the Amazon MQ XML schema. You can
use this schema to validate and sanitize your configuration files. Amazon MQ also lets you provide
configurations by uploading XML files. When you upload an XML file, Amazon MQ automatically sanitizes
and removes invalid and prohibited configuration parameters according to the schema.
Note
You can use only static values for attributes. Amazon MQ sanitizes elements and attributes that
contain Spring expressions, variables, and element references from your configuration.
Topics
• Permitted Elements (p. 37)
• Permitted Attributes (p. 39)
• Permitted Collections (p. 46)
Permitted Elements
The following is a detailed listing of the elements permitted in Amazon MQ configurations. For more
information, see XML Configuration in the Apache ActiveMQ documentation.
Element
abortSlowAckConsumerStrategy (attributes) (p. 39)
abortSlowConsumerStrategy (attributes) (p. 40)
37
Amazon MQ Developer Guide
Permitted Elements
Element
authorizationEntry (attributes) (p. 40)
authorizationMap (child collection elements) (p. 46)
authorizationPlugin (child collection elements) (p. 46)
broker (attributes (p. 40) | child collection elements) (p. 46)
cachedMessageGroupMapFactory (attributes) (p. 41)
compositeQueue (attributes (p. 41) | child collection elements) (p. 47)
compositeTopic (attributes (p. 41) | child collection elements) (p. 47)
constantPendingMessageLimitStrategy (attributes) (p. 41)
discarding (attributes) (p. 41)
discardingDLQBrokerPlugin (attributes) (p. 42)
fileCursor
fileDurableSubscriberCursor
fileQueueCursor
filteredDestination (attributes) (p. 42)
fixedCountSubscriptionRecoveryPolicy (attributes) (p. 42)
fixedSizedSubscriptionRecoveryPolicy (attributes) (p. 42)
forcePersistencyModeBrokerPlugin (attributes) (p. 42)
individualDeadLetterStrategy (attributes) (p. 42)
lastImageSubscriptionRecoveryPolicy
messageGroupHashBucketFactory (attributes) (p. 42)
mirroredQueue (attributes) (p. 42)
noSubscriptionRecoveryPolicy
oldestMessageEvictionStrategy (attributes) (p. 43)
oldestMessageWithLowestPriorityEvictionStrategy (attributes) (p. 43)
policyEntry (attributes (p. 43) | child collection elements) (p. 47)
policyMap (child collection elements) (p. 48)
prefetchRatePendingMessageLimitStrategy (attributes) (p. 44)
priorityDispatchPolicy
priorityNetworkDispatchPolicy
queryBasedSubscriptionRecoveryPolicy (attributes) (p. 44)
queue (attributes) (p. 44)
38
Amazon MQ Developer Guide
Permitted Attributes
Element
redeliveryPlugin (attributes (p. 44) | child collection elements) (p. 48)
redeliveryPolicy (attributes) (p. 44)
redeliveryPolicyMap (child collection elements) (p. 48)
retainedMessageSubscriptionRecoveryPolicy (child collection elements) (p. 49)
roundRobinDispatchPolicy
sharedDeadLetterStrategy (attributes (p. 45) | child collection elements) (p. 49)
simpleDispatchPolicy
simpleMessageGroupMapFactory
statisticsBrokerPlugin
storeCursor
storeDurableSubscriberCursor (attributes) (p. 45)
strictOrderDispatchPolicy
tempDestinationAuthorizationEntry (attributes) (p. 45)
tempQueue (attributes) (p. 45)
tempTopic (attributes) (p. 45)
timedSubscriptionRecoveryPolicy (attributes) (p. 45)
timeStampingBrokerPlugin (attributes) (p. 46)
topic (attributes) (p. 46)
uniquePropertyMessageEvictionStrategy (attributes) (p. 46)
virtualDestinationInterceptor (child collection elements) (p. 49)
virtualTopic (attributes) (p. 46)
vmCursor
vmDurableCursor
vmQueueCursor
Permitted Attributes
The following is a detailed listing of the elements and their attributes permitted in Amazon MQ
configurations. For more information, see XML Configuration in the Apache ActiveMQ documentation.
Element
Attribute
abortSlowAckConsumerStrategy
abortConnection
checkPeriod
39
Amazon MQ Developer Guide
Permitted Attributes
Element
Attribute
ignoreIdleConsumers
ignoreNetworkConsumers
maxSlowCount
maxSlowDuration
maxTimeSinceLastAck
name
abortSlowConsumerStrategy
abortConnection
checkPeriod
ignoreNetworkConsumers
maxSlowCount
maxSlowDuration
name
authorizationEntry
admin
queue
read
tempQueue
tempTopic
topic
write
broker
advisorySupport
allowTempAutoCreationOnSend
cacheTempDestinations
consumerSystemUsagePortion
dedicatedTaskRunner
deleteAllMessagesOnStartup
keepDurableSubsActive
maxPurgedDestinationsPerSweep
monitorConnectionSplits
offlineDurableSubscriberTaskSchedule
offlineDurableSubscriberTimeout
persistenceThreadPriority
40
Amazon MQ Developer Guide
Permitted Attributes
Element
Attribute
persistent
populateJMSXUserID
producerSystemUsagePortion
rejectDurableConsumers
rollbackOnlyOnAsyncException
schedulePeriodForDestinationPurge
schedulerSupport
splitSystemUsageForProducersConsumers
taskRunnerPriority
timeBeforePurgeTempDestinations
useAuthenticatedPrincipalForJMSXUserID
useMirroredQueues
useTempMirroredQueues
useVirtualDestSubs
useVirtualDestSubsOnCreation
useVirtualTopics
cachedMessageGroupMapFactory
cacheSize
compositeQueue
concurrentSend
copyMessage
forwardOnly
name
compositeTopic
concurrentSend
copyMessage
forwardOnly
name
constantPendingMessageLimitStrategy
limit
discarding
deadLetterQueue
enableAudit
expiration
maxAuditDepth
maxProducersToAudit
41
Amazon MQ Developer Guide
Permitted Attributes
Element
Attribute
processExpired
processNonPersistent
discardingDLQBrokerPlugin
dropAll
dropOnly
dropTemporaryQueues
dropTemporaryTopics
reportInterval
filteredDestination
queue
selector
topic
fixedCountSubscriptionRecoveryPolicy
maximumSize
fixedSizedSubscriptionRecoveryPolicy
maximumSize
useSharedBuffer
forcePersistencyModeBrokerPlugin
persistenceFlag
individualDeadLetterStrategy
destinationPerDurableSubscriber
enableAudit
expiration
maxAuditDepth
maxProducersToAudit
processExpired
processNonPersistent
queuePrefix
queueSuffix
topicPrefix
topicSuffix
useQueueForQueueMessages
useQueueForTopicMessages
messageGroupHashBucketFactory
bucketCount
cacheSize
mirroredQueue
copyMessage
postfix
42
Amazon MQ Developer Guide
Permitted Attributes
Element
Attribute
prefix
oldestMessageEvictionStrategy
evictExpiredMessagesHighWatermark
oldestMessageWithLowestPriorityEvictionStrategy
evictExpiredMessagesHighWatermark
policyEntry
advisoryForConsumed
advisoryForDelivery
advisoryForDiscardingMessages
advisoryForFastProducers
advisoryForSlowConsumers
advisoryWhenFull
allConsumersExclusiveByDefault
alwaysRetroactive
blockedProducerWarningInterval
consumersBeforeDispatchStarts
cursorMemoryHighWaterMark
doOptimzeMessageStorage
durableTopicPrefetch
enableAudit
expireMessagesPeriod
gcInactiveDestinations
gcWithNetworkConsumers
inactiveTimeoutBeforeGC
inactiveTimoutBeforeGC
includeBodyForAdvisory
lazyDispatch
maxAuditDepth
maxBrowsePageSize
maxDestinations
maxExpirePageSize
maxPageSize
maxProducersToAudit
maxQueueAuditDepth
43
Amazon MQ Developer Guide
Permitted Attributes
Element
Attribute
memoryLimit
messageGroupMapFactoryType
minimumMessageSize
optimizedDispatch
optimizeMessageStoreInFlightLimit
persistJMSRedelivered
prioritizedMessages
producerFlowControl
queue
queueBrowserPrefetch
queuePrefetch
reduceMemoryFootprint
sendAdvisoryIfNoConsumers
storeUsageHighWaterMark
strictOrderDispatch
tempQueue
tempTopic
timeBeforeDispatchStarts
topic
topicPrefetch
useCache
useConsumerPriority
usePrefetchExtension
prefetchRatePendingMessageLimitStrategy multiplier
queryBasedSubscriptionRecoveryPolicy
query
queue
DLQ
physicalName
redeliveryPlugin
fallbackToDeadLetter
sendToDlqIfMaxRetriesExceeded
redeliveryPolicy
backOffMultiplier
collisionAvoidancePercent
44
Amazon MQ Developer Guide
Permitted Attributes
Element
Attribute
initialRedeliveryDelay
maximumRedeliveries
maximumRedeliveryDelay
preDispatchCheck
queue
redeliveryDelay
tempQueue
tempTopic
topic
useCollisionAvoidance
useExponentialBackOff
sharedDeadLetterStrategy
enableAudit
expiration
maxAuditDepth
maxProducersToAudit
processExpired
processNonPersistent
storeDurableSubscriberCursor
immediatePriorityDispatch
useCache
tempDestinationAuthorizationEntry
admin
queue
read
tempQueue
tempTopic
topic
write
tempQueue
DLQ
physicalName
tempTopic
DLQ
physicalName
timedSubscriptionRecoveryPolicy
zeroExpirationOverride
45
Amazon MQ Developer Guide
Permitted Collections
Element
Attribute
timeStampingBrokerPlugin
recoverDuration
futureOnly
processNetworkMessages
ttlCeiling
topic
DLQ
physicalName
uniquePropertyMessageEvictionStrategy
evictExpiredMessagesHighWatermark
propertyName
virtualTopic
concurrentSend
local
name
postfix
prefix
selectorAware
transactedSend
Permitted Collections
The following is a detailed listing of the elements, child collection elements, and their child elements
permitted in Amazon MQ configurations. For more information, see XML Configuration in the Apache
ActiveMQ documentation.
Element
Child Collection Element
Child Element
authorizationMap
authorizationEntries
authorizationEntry
(attributes) (p. 49)
tempDestinationAuthorizationEntry
defaultEntry
authorizationEntry
tempDestinationAuthorizationEntry
tempDestinationAuthorizationEntry
tempDestinationAuthorizationEntry
authorizationPlugin
map
authorizationMap
broker
destinationInterceptors
mirroredQueue
virtualDestinationInterceptor
destinationPolicy
policyMap
destinations
queue
46
Amazon MQ Developer Guide
Permitted Collections
Element
Child Collection Element
Child Element
tempQueue
tempTopic
topic
persistenceAdapter
kahaDB
(attributes) (p. 50)
plugins
authorizationPlugin
discardingDLQBrokerPlugin
forcePersistencyModeBrokerPlugin
redeliveryPlugin
statisticsBrokerPlugin
timeStampingBrokerPlugin
compositeQueue
forwardTo
queue
tempQueue
tempTopic
topic
filteredDestination
compositeTopic
forwardTo
queue
tempQueue
tempTopic
topic
filteredDestination
policyEntry
deadLetterStrategy
discarding
individualDeadLetterStrategy
sharedDeadLetterStrategy
destination
queue
tempQueue
tempTopic
topic
dispatchPolicy
priorityDispatchPolicy
priorityNetworkDispatchPolicy
roundRobinDispatchPolicy
47
Amazon MQ Developer Guide
Permitted Collections
Element
Child Collection Element
Child Element
simpleDispatchPolicy
strictOrderDispatchPolicy
messageEvictionStrategy
oldestMessageEvictionStrategy
oldestMessageWithLowestPriorityEvict
uniquePropertyMessageEvictionStrateg
messageGroupMapFactory
cachedMessageGroupMapFactory
messageGroupHashBucketFactory
simpleMessageGroupMapFactory
pendingDurableSubscriberPolicy
fileDurableSubscriberCursor
storeDurableSubscriberCursor
vmDurableCursor
pendingMessageLimitStrategyconstantPendingMessageLimitStrategy
prefetchRatePendingMessageLimitStrat
pendingQueuePolicy
fileQueueCursor
storeCursor
vmQueueCursor
pendingSubscriberPolicy
fileCursor
vmCursor
slowConsumerStrategy
abortSlowAckConsumerStrategy
abortSlowConsumerStrategy
subscriptionRecoveryPolicy fixedCountSubscriptionRecoveryPolicy
fixedSizedSubscriptionRecoveryPolicy
lastImageSubscriptionRecoveryPolicy
noSubscriptionRecoveryPolicy
queryBasedSubscriptionRecoveryPolicy
retainedMessageSubscriptionRecoveryP
timedSubscriptionRecoveryPolicy
policyMap
defaultEntry
policyEntry
policyEntries
policyEntry
redeliveryPlugin
redeliveryPolicyMap
redeliveryPolicyMap
redeliveryPolicyMap
defaultEntry
redeliveryPolicy
48
Amazon MQ Developer Guide
Permitted Collections
Element
Child Collection Element
Child Element
redeliveryPolicyEntries
redeliveryPolicy
retainedMessageSubscriptionRecoveryPolicy
wrapped
fixedCountSubscriptionRecoveryPolicy
fixedSizedSubscriptionRecoveryPolicy
lastImageSubscriptionRecoveryPolicy
noSubscriptionRecoveryPolicy
queryBasedSubscriptionRecoveryPolicy
retainedMessageSubscriptionRecoveryP
timedSubscriptionRecoveryPolicy
sharedDeadLetterStrategy
deadLetterQueue
queue
tempQueue
tempTopic
topic
virtualDestinationInterceptor
virtualDestinations
compositeQueue
compositeTopic
virtualTopic
Child Element Attributes
The following is a detailed explanation of child element attributes. For more information, see XML
Configuration in the Apache ActiveMQ documentation.
authorizationEntry
authorizationEntry is a child of the authorizationEntries child collection element.
admin|read|write
Amazon MQ Default: Not configured.
Example Example Configuration
<authorizationPlugin>
<map>
<authorizationMap>
<authorizationEntries>
<authorizationEntry admin="admins,activemq-webconsole"
read="admins,users,activemq-webconsole" write="admins,activemq-webconsole" queue=">"/>
<authorizationEntry admin="admins,activemq-webconsole"
read="admins,users,activemq-webconsole" write="admins,activemq-webconsole" topic=">"/>
</authorizationEntries>
</authorizationMap>
</map>
</authorizationPlugin>
49
Amazon MQ Developer Guide
Working Java Example
For more information, see Always Configure an Authorization Map (p. 57).
kahaDB
kahaDB is a child of the persistenceAdapter child collection element.
concurrentStoreAndDispatchQueues
Amazon MQ Default: true
Example Example Configuration
<persistenceAdapter>
<kahaDB concurrentStoreAndDispatchQueues="false"/>
</persistenceAdapter>
For more information, see Concurrent Store and Dispatch for Queues (p. 35).
Working Example of Using Java Message Service
(JMS) with ActiveMQ
The following example Java code connects to a broker, creates a queue, and sends and receives a
message. For a detailed breakdown and explanation of this code, see Connecting a Java Application to
Your Broker (p. 19).
Prerequisites
Enable Inbound Connections
1.
Sign in to the Amazon MQ console.
2.
From the broker list, choose the name of your broker (for example, MyBroker).
3.
On the MyBroker page, in the Connections section, note the addresses and ports of the broker's
ActiveMQ Web Console URL and wire-level protocols.
4.
In the Details section, under Security and network, choose the name of your security group or
.
The Security Groups page of the EC2 Dashboard is displayed.
5.
From the security group list, choose your security group.
6.
At the bottom of the page, choose Inbound, and then choose Edit.
7.
In the Edit inbound rules dialog box, add a rule for every URL or endpoint that you want to be
publicly accessible (the following example shows how to do this for an ActiveMQ Web Console).
a.
Choose Add Rule.
b.
For Type, select Custom TCP.
c.
For Port Range, type the ActiveMQ Web Console port (8162).
d.
For Source, leave Custom selected and then type the IP address of the system that you want to
be able to access the ActiveMQ Web Console (for example, 192.0.2.1).
e.
Choose Save.
Your broker can now accept inbound connections.
50
Amazon MQ Developer Guide
AmazonMQExample.java
Add Java Dependencies
Ensure that the activemq-client.jar and activemq-pool.jar packages are in your Java build
class path.
The following example shows these dependencies in a Maven project pom.xml file.
<dependencies>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-client</artifactId>
<version>5.15.0</version>
</dependency>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-pool</artifactId>
<version>5.15.0</version>
</dependency>
</dependencies>
For more information about activemq-client.jar, see Initial Configuration in the Apache ActiveMQ
documentation.
AmazonMQExample.java
/*
* Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* https://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*
*/
import org.apache.activemq.ActiveMQConnectionFactory;
import org.apache.activemq.jms.pool.PooledConnectionFactory;
import javax.jms.*;
public class AmazonMQExample {
public static void main(String[] args) throws JMSException {
// Specify the connection parameters.
final String wireLevelEndpoint = "ssl://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617";
final String activeMqUsername = "MyUsername123";
final String activeMqPassword = "MyPassword456";
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
51
Amazon MQ Developer Guide
AmazonMQExample.java
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory for the producer.
final PooledConnectionFactory pooledConnectionFactoryProducer = new
PooledConnectionFactory();
pooledConnectionFactoryProducer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryProducer.setMaxConnections(10);
// Establish a connection for the producer.
final Connection producerConnection =
pooledConnectionFactoryProducer.createConnection();
producerConnection.start();
// Create a session.
final Session producerSession = producerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".
final Destination producerDestination = producerSession.createQueue("MyQueue");
// Create a producer from the session to the queue.
final MessageProducer producer =
producerSession.createProducer(producerDestination);
producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
// Create a message.
final String text = "Hello from Amazon MQ!";
final TextMessage producerMessage = producerSession.createTextMessage(text);
// Send the message.
producer.send(producerMessage);
System.out.println("Message sent.");
// Clean up the producer.
producer.close();
producerSession.close();
producerConnection.close();
// Create a pooled connection factory for the consumer.
final PooledConnectionFactory pooledConnectionFactoryConsumer = new
PooledConnectionFactory();
pooledConnectionFactoryConsumer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryConsumer.setMaxConnections(10);
// Establish a connection for the consumer.
final Connection consumerConnection =
pooledConnectionFactoryProducer.createConnection();
consumerConnection.start();
// Create a session.
final Session consumerSession = consumerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".
final Destination consumerDestination = consumerSession.createQueue("MyQueue");
// Create a message consumer from the session to the queue.
final MessageConsumer consumer =
consumerSession.createConsumer(consumerDestination);
// Begin to wait for messages.
final Message consumerMessage = consumer.receive(1000);
// Receive the message when it arrives.
final TextMessage consumerTextMessage = (TextMessage) consumerMessage;
System.out.println("Message received: " + consumerTextMessage.getText());
52
Amazon MQ Developer Guide
AmazonMQExample.java
}
// Clean up the consumer.
consumer.close();
consumerSession.close();
consumerConnection.close();
pooledConnectionFactoryConsumer.stop();
}
53
Amazon MQ Developer Guide
Without Service Interruption
Migrating to Amazon MQ
Use the following topics to get started with migrating your on-premises message broker to Amazon MQ.
Topics
• Migrating without Service Interruption (p. 54)
• Migrating with Service Interruption (p. 55)
Migrating without Service Interruption
The following diagrams illustrate the scenario of migrating from an on-premises message broker to an
Amazon MQ broker in the AWS Cloud without service interruption.
Important
This scenario might cause messages to be delivered out of order. If you're concerned about
message ordering, follow the steps in Migrating with Service Interruption (p. 55).
On-Premises Message Broker
Migration to Amazon MQ with
Standard (Unordered) Queues
To migrate to Amazon MQ without service
interruption
Create and configure an Amazon MQ broker (p. 11) and note your broker's endpoint, for example:
54
Amazon MQ Developer Guide
With Service Interruption
ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617
For either of the following cases, use the Failover Transport to allow your consumers to randomly
connect to your on-premises broker's endpoint or your Amazon MQ broker's endpoint. For example:
failover:(ssl://on-premises-broker.example.com:61617,ssl://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617)?randomize=true
Do one of the following:
• One by one, point each existing consumer to your Amazon MQ broker's endpoint.
• Create new consumers and point them to your Amazon MQ broker's endpoint.
Note
If you scale up your consumer fleet during the migration process, it is a best practice to scale it
down afterward.
One by one, stop each existing producer, point the producer to your Amazon MQ broker's endpoint,
and then restart the producer.
Wait for your consumers to drain the destinations on your on-premises broker.
Change your consumers' Failover transport to include only your Amazon MQ broker's endpoint. For
example:
failover:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617)
Stop your on-premises broker.
Migrating with Service Interruption
The following diagrams illustrate the scenario of migrating from an on-premises message broker to an
Amazon MQ broker in the AWS Cloud with service interruption.
Important
This scenario requires you to point your producer to your Amazon MQ broker's endpoint before
you do the same for your consumers. This sequence ensures that any messages in a FIFO (firstin-first-out) queue maintain their order during the migration process. If you're not concerned
about message ordering, follow the steps in Migrating without Service Interruption (p. 54).
55
Amazon MQ Developer Guide
To migrate to Amazon MQ with service interruption
On-Premises Message Broker
Migration to Amazon MQ
with FIFO (Ordered) Queues
To migrate to Amazon MQ with service interruption
Create and configure an Amazon MQ broker (p. 11) and note your broker's endpoint, for example:
ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617
Stop your existing producer, point the producer to your Amazon MQ broker's endpoint, and then
restart the producer.
Important
This step requires an interruption of your application's functionality because no consumers are
yet consuming messages from the Amazon MQ broker.
Wait for your consumers to drain the destinations on your on-premises broker.
Do one of the following:
• One by one, point each existing consumer to your Amazon MQ broker's endpoint.
• Create new consumers and point them to your Amazon MQ broker's endpoint.
Note
If you scale up your consumer fleet during the migration process, it is a best practice to scale it
down afterward.
Stop your on-premises broker.
56
Amazon MQ Developer Guide
Using Amazon MQ Securely
Best Practices for Amazon MQ
Use these best practices to make the most of Amazon MQ.
Topics
• Using Amazon MQ Securely (p. 57)
• Communicating with Amazon MQ (p. 58)
• Ensuring Effective Amazon MQ Performance (p. 60)
Using Amazon MQ Securely
The following design patterns can improve the security of your Amazon MQ broker.
Topics
• Prefer Brokers without Public Accessibility (p. 57)
• Always Use Client-Side Encryption as a Complement to TLS (p. 57)
• Always Configure an Authorization Map (p. 57)
• Always Configure a System Group (p. 58)
Prefer Brokers without Public Accessibility
Brokers created without public accessibility can't be accessed from outside of your VPC. This greatly
reduces your broker's susceptibility to Distributed Denial of Service (DDoS) attacks from the public
Internet. For more information, see How to Help Prepare for DDoS Attacks by Reducing Your Attack
Surface on the AWS Security Blog.
Always Use Client-Side Encryption as a Complement
to TLS
You can access your brokers using the following protocols with TLS enabled:
• AMQP
• MQTT
• MQTT over WebSocket
• OpenWire
• STOMP
• STOMP over WebSocket
Amazon MQ provides at-rest encryption using an AWS-managed Customer Master Key (CMK). For
additional security, we highly recommend to design your application to use client-side encryption. For
more information, see the AWS Encryption SDK Developer Guide.
Always Configure an Authorization Map
Because ActiveMQ has no authorization map configured by default, any authenticated user can perform
any action on the broker. Thus, it is a best practice to restrict permissions by group.
57
Amazon MQ Developer Guide
Always Configure a System Group
Always Configure a System Group
Amazon MQ uses a system group (called activemq-webconsole) to allow the ActiveMQ Web Console
to communicate with the ActiveMQ broker.
The settings for the activemq-webconsole group in the authorization map restrict which operations
can be performed on queues or topics from the web console. For more information and an example
configuration, see authorizationEntry (p. 49).
Important
If you specify an authorization map which doesn't include the activemq-webconsole group,
you won't be able to use the ActiveMQ Web Console because the group isn't authorized to send
messages to, or receive messages from, the Amazon MQ broker.
Communicating with Amazon MQ
The following design patterns can improve the effectiveness of your application's communication with
your Amazon MQ broker.
Topics
• Never Modify or Delete the Amazon MQ Elastic Network Interface (p. 58)
• Always Use Connection Pooling (p. 59)
• Always Use the Failover Transport to Connect to Multiple Broker Endpoints (p. 59)
• Avoid Using Message Selectors (p. 60)
• Prefer Virtual Destinations to Durable Subscriptions (p. 60)
Never Modify or Delete the Amazon MQ Elastic
Network Interface
When you first create an Amazon MQ broker (p. 11), Amazon MQ provisions an elastic network
interface in the Virtual Private Cloud (VPC) under your account and, thus, requires a number of EC2
permissions (p. 67). The network interface allows your client (producer or consumer) to communicate
with the Amazon MQ broker. The network interface is considered to be within the service scope of
Amazon MQ, despite being part of your account's VPC.
Warning
You must not modify or delete this network interface. Modifying or deleting the network
interface can cause a permanent loss of connection between your VPC and your broker.
Currently, you can't recover your broker if you delete its network interface. You can only
recreate your broker.
58
Amazon MQ Developer Guide
Always Use Connection Pooling
Always Use Connection Pooling
In a scenario with a single producer and single consumer (such as the Getting Started with Amazon
MQ (p. 6) tutorial), you can use a single ActiveMQConnectionFactory class for every producer and
consumer. For example:
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Establish a connection for the consumer.
final Connection consumerConnection = connectionFactory.createConnection();
consumerConnection.start();
However, in more realistic scenarios with multiple producers and consumers, it can be costly
and inefficient to create a large number of connections for multiple producers or consumers.
In these scenarios, you should group multiple producer or consumer requests using the
PooledConnectionFactory class for better throughput. For example:
// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory for the consumer.
final PooledConnectionFactory pooledConnectionFactoryConsumer = new
PooledConnectionFactory();
pooledConnectionFactoryConsumer.setConnectionFactory(connectionFactory);
pooledConnectionFactoryConsumer.setMaxConnections(10);
// Establish a connection for the consumer.
final Connection consumerConnection = pooledConnectionFactoryProducer.createConnection();
consumerConnection.start();
Always Use the Failover Transport to Connect to
Multiple Broker Endpoints
If you need your application to connect to multiple broker endpoints—for example, when you use an
active/standby broker for high availability (p. 11) or when you migrate from an on-premises message
broker to Amazon MQ—use the Failover Transport to allow your consumers to randomly connect to
either one. For example:
failover:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.useast-2.amazonaws.com:61617,ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.useast-2.amazonaws.com:61617)?randomize=true
59
Amazon MQ Developer Guide
Avoid Using Message Selectors
Avoid Using Message Selectors
It is possible to use JMS selectors to attach filters to topic subscriptions (to route messages to consumers
based on their content). However, the use of JMS selectors fills up the Amazon MQ broker's filter buffer,
preventing it from filtering messages.
In general, avoid letting consumers route messages because, for optimal decoupling of consumers and
producers, both the consumer and the producer should be ephemeral.
Prefer Virtual Destinations to Durable Subscriptions
A durable subscription can help ensure that the consumer receives all messages published to a topic, for
example, after a lost connection is restored. However, the use of durable subscriptions also precludes
the use of competing consumers and might have performance issues at scale. Consider using virtual
destinations instead.
Ensuring Effective Amazon MQ Performance
The following design patterns can improve the effectiveness and performance of your Amazon MQ
broker.
Disable Concurrent Store and Dispatch for Queues
with Slow Consumers
By default, the concurrentStoreAndDispatch flag is set to true. If your consumers are slower than
your producers, or if the combined number of your consumers is insufficient, set the flag to false.
For a detailed overview, see Concurrent Store and Dispatch for Queues (p. 35). For an example
configuration, see concurrentStoreAndDispatchQueues (p. 50).
60
Amazon MQ Developer Guide
Brokers
Limits in Amazon MQ
This topic lists limits within Amazon MQ. Many of the following limits can be changed for specific AWS
accounts. To request an increase for a limit, see AWS Service Limits in the Amazon Web Services General
Reference.
Topics
• Brokers (p. 61)
• Configurations (p. 61)
• Users (p. 62)
• Data Storage (p. 62)
• API Throttling (p. 62)
Brokers
The following table lists limits related to Amazon MQ brokers.
Limit
Description
Broker name
• Must be unique in your AWS account.
• Must be 1-50 characters long.
• Must contain only characters specified in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).
Brokers per broker instance type (p. 31), per AWS
account, per region
20
Broker configuration history depth
10
Security groups per broker
5
Destinations (queues and topics) monitored in
CloudWatch
CloudWatch monitors only the first 200
destinations.
Configurations
The following table lists limits related to Amazon MQ configurations.
Limit
Description
Configuration name
• Must be 1-150 characters long.
• Must contain only characters specified in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).
61
Amazon MQ Developer Guide
Users
Limit
Description
Configurations per AWS account
1,000
Revisions per configuration
300
Users
The following table lists limits related to Amazon MQ users (p. 32).
Limit
Description
Username
• Must be 1-100 characters long.
• Must contain only characters specified in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).
• Must not contain commas (,).
Password
• Must be 12-250 characters long.
• Must contain only characters specified in the
ASCII Printable Character Set.
• Must contain at least 4 unique characters.
• Must not contain commas (,).
Users per broker
100
Groups per user
5
Data Storage
The following table lists limits related to Amazon MQ data storage.
Limit
Description
Storage capacity per broker
200 GB
Data store
Amazon MQ uses Apache KahaDB as its data store.
Other data stores, such as JDBC and LevelDB,
aren't supported.
API Throttling
The following throttling limits are aggregated per AWS account, across all Amazon MQ APIs to maintain
service bandwidth.
Note
These limits don't apply to ActiveMQ messaging APIs.
62
Amazon MQ Developer Guide
API Throttling
Bucket Size
Refill Rate per Second
100
15
63
Amazon MQ Developer Guide
Broker Metrics
Monitoring Amazon MQ using
Amazon CloudWatch
Amazon MQ and Amazon CloudWatch are integrated so you can use CloudWatch to view and analyze
metrics for your ActiveMQ broker and the broker's destinations (queues and topics). You can view and
analyze your Amazon MQ metrics from the CloudWatch console, the AWS CLI, or the CloudWatch CLI.
CloudWatch metrics for Amazon MQ are automatically polled from the broker and then pushed to
CloudWatch every minute.
For information about accessing Amazon MQ CloudWatch metrics, see Accessing CloudWatch Metrics for
Amazon MQ (p. 26).
Note
The following statistics are valid for all of the metrics:
• Average
• Minimum
• Maximum
• Sum
The AWS/AmazonMQ namespace includes the following metrics.
Broker Metrics
Metric
Unit
Description
CpuUtilization
Percent
The percentage of allocated EC2
compute units that the broker
currently uses.
HeapUsage
Percent
The percentage of the ActiveMQ
JVM memory limit that the
broker currently uses.
NetworkIn
Bytes
The volume of incoming traffic
for the broker.
NetworkOut
Bytes
The volume of outgoing traffic
for the broker.
TotalMessageCount
Count
The number of messages stored
on the broker.
Dimension for Broker Metrics
Dimension
Description
Broker
The name of the broker.
64
Amazon MQ Developer Guide
Destination (Queue and Topic) Metrics
Dimension
Description
Note
A single-instance broker has the suffix
-1. An active-standby broker for high
availability has the suffixes -1 and -2 for
its redundant pair.
Destination (Queue and Topic) Metrics
Important
The following metrics record only values since CloudWatch polled the metrics last:
• EnqueueCount
• ExpiredCount
• DequeueCount
• DispatchCount
Metric
Unit
Description
ConsumerCount
Count
The number of consumers
subscribed to the destination.
EnqueueCount
Count
The number of messages sent to
the destination.
EnqueueTime
Time (milliseconds)
The amount of time it takes the
broker to accept a message from
the producer and send it to the
destination.
ExpiredCount
Count
The number of messages that
couldn't be delivered because
they expired.
DispatchCount
Count
The number of messages sent to
consumers.
DequeueCount
Count
The number of messages
acknowledged by consumers.
MemoryUsage
Percent
The percentage of the memory
limit that the destination
currently uses.
ProducerCount
Count
The number of producers for the
destination.
QueueSize
Count
The number of messages in the
queue.
Important
This metric applies only
to queues.
65
Amazon MQ Developer Guide
Dimensions for Destination (Queue and Topic) Metrics
Dimensions for Destination (Queue and Topic)
Metrics
Dimension
Description
Broker
The name of the broker.
Note
A single-instance broker has the suffix
-1. An active-standby broker for high
availability has the suffixes -1 and -2 for
its redundant pair.
Topic or Queue
The name of the topic or queue.
66
Amazon MQ Developer Guide
API Authentication and Authorization
Amazon MQ Security
This section provides information about Amazon MQ and ActiveMQ authentication and authorization.
For information about security best practices, see Using Amazon MQ Securely (p. 57).
Topics
• API Authentication and Authorization for Amazon MQ (p. 67)
• Messaging Authentication and Authorization for ActiveMQ (p. 68)
API Authentication and Authorization for Amazon
MQ
Amazon MQ uses standard AWS request signing for authentication. For more information, see Signing
AWS API Requests in the AWS General Reference.
Note
Currently, Amazon MQ doesn't support IAM authentication using resource-based permissions or
resource-based policies.
To authorize AWS users to work with brokers, configurations, and users, you must edit your IAM policy
permissions.
Important
To create a broker, you must either use the AmazonMQFullAccess IAM policy or include the
following EC2 permissions in your IAM policy.
• ec2:CreateNetworkInterface
• ec2:CreateNetworkInterfacePermission
• ec2:DeleteNetworkInterface
• ec2:DeleteNetworkInterfacePermission
• ec2:DetachNetworkInterface
• ec2:DescribeInternetGateways
• ec2:DescribeNetworkInterfaces
• ec2:DescribeNetworkInterfacePermissions
• ec2:DescribeRouteTables
• ec2:DescribeSecurityGroups
• ec2:DescribeSubnets
• ec2:DescribeVpcs
For more information, see Create an IAM User and Get Your AWS Credentials (p. 4) and Never
Modify or Delete the Amazon MQ Elastic Network Interface (p. 58).
The following table lists Amazon MQ REST APIs and the corresponding IAM permissions.
Amazon MQ REST APIs and Required Permissions
Amazon MQ REST APIs
Required Permissions
CreateBroker
mq:CreateBroker
67
Amazon MQ Developer Guide
Messaging Authentication and Authorization
Amazon MQ REST APIs
Required Permissions
CreateConfiguration
mq:CreateConfiguration
CreateUser
mq:CreateUser
DeleteBroker
mq:DeleteBroker
DeleteUser
mq:DeleteUser
DescribeBroker
mq:DescribeBroker
DescribeConfiguration
mq:DescribeConfiguration
DescribeConfigurationRevision
mq:DescribeConfigurationRevision
DescribeUser
mq:DescribeUser
ListBrokers
mq:ListBrokers
ListConfigurationRevisions
mq:ListConfigurationRevisions
ListConfigurations
mq:ListConfigurations
ListUsers
mq:ListUsers
RebootBroker
mq:RebootBroker
UpdateBroker
mq:UpdateBroker
UpdateConfiguration
mq:UpdateConfiguration
UpdateUser
mq:UpdateUser
Messaging Authentication and Authorization for
ActiveMQ
You can access your brokers using the following protocols with TLS enabled:
• AMQP
• MQTT
• MQTT over WebSocket
• OpenWire
• STOMP
• STOMP over WebSocket
Amazon MQ uses native ActiveMQ authentication. For information about restrictions related to ActiveMQ
usernames and passwords, see Limits Related to Users (p. 62).
To authorize ActiveMQ users and groups to works with queues and topics, you must edit your broker's
configuration (p. 16). For information about configuring Amazon MQ, see Amazon MQ Broker
Configuration Parameters (p. 37).
Note
Currently, Amazon MQ doesn't support Client Certificate Authentication or plugins for Java
Authentication and Authorization Service (JAAS).
68
Amazon MQ Developer Guide
Amazon MQ Resources
Related Resources
Amazon MQ Resources
The following table lists useful resources for working with Amazon MQ.
Resource
Description
Amazon MQ REST API Reference
Descriptions of REST resources, example requests,
HTTP methods, schemas, parameters, and the
errors that the service returns.
Amazon MQ in the AWS CLI Command Reference
Descriptions of the AWS CLI commands that you
can use to work with message brokers.
Regions and Endpoints
Information about Amazon MQ regions and
endpoints
Product Page
The primary web page for information about
Amazon MQ.
Discussion Forum
A community-based forum for developers to
discuss technical questions related to Amazon
MQ.
AWS Premium Support Information
The primary web page for information about
AWS Premium Support, a one-on-one, fastresponse support channel to help you build and
run applications on AWS infrastructure services
Apache ActiveMQ Resources
The following table lists useful resources for working with Apache ActiveMQ.
Resource
Description
Apache ActiveMQ Getting Started Guide
The official documentation of Apache ActiveMQ.
ActiveMQ in Action
A guide to Apache ActiveMQ that covers the
anatomy of JMS messages, connectors, message
persistence, authentication, and authorization.
Cross-Language Clients
A list of programming languages and
corresponding Apache ActiveMQ libraries. See also
ActiveMQ Client and QpidJMS Client.
69
Amazon MQ Developer Guide
Amazon MQ Release Notes
The following table lists Amazon MQ feature releases and improvements. For changes to the Amazon MQ
Developer Guide, see Amazon MQ Document History (p. 71).
Date
Feature Release
March 13, 2018
Creating a broker takes about 15 minutes. For more information, see Finish
creating the broker (p. 13).
March 1, 2018
You can configure the concurrent store and dispatch (p. 35) for Apache KahaDB
using the concurrentStoreAndDispatchQueues (p. 50) attribute.
January 10, 2018
The following changes affect the Amazon MQ console:
• In the broker list, the Creation column is hidden by default. To customize the
page size and columns, choose .
• On the MyBroker page, in the Connections section, choosing the name
of your security group or opens the EC2 console (instead of the VPC
console). The EC2 console allows more intuitive configuration of inbound
and outbound rules. For more information, see the updated Enable Inbound
Connections (p. 19) section.
January 9, 2018
• The permission for REST operation ID UpdateBroker is listed correctly as
mq:UpdateBroker on the IAM console.
• The erroneous mq:DescribeEngine permission is removed from the IAM
console.
November 28,
2017
This is the initial release of Amazon MQ and the Amazon MQ Developer Guide.
• You can create mq.m4.large and mq.t2.micro brokers in the following
regions:
• US East (Ohio)
• US East (N. Virginia)
• US West (Oregon)
• Asia Pacific (Sydney)
• EU (Frankfurt)
• EU (Ireland)
Using the mq.t2.micro instance type is subject to CPU credits and baseline
performance—with the ability to burst above the baseline level. If your
application requires fixed performance, consider using an mq.m4.large
instance type.
• You can use the ActiveMQ 5.15.0 broker engine.
• You can also create and manage brokers programmatically using Amazon MQ
REST API and AWS SDKs.
• You can access your brokers by using any programming language that
ActiveMQ supports and by enabling TLS explicitly for the following protocols:
• AMQP
• MQTT
• MQTT over WebSocket
• OpenWire
70
Amazon MQ Developer Guide
Document History
Date
Feature Release
• STOMP
• STOMP over WebSocket
• You can connect to ActiveMQ brokers using various ActiveMQ clients. We
recommend using the ActiveMQ Client. For more information, see Connecting a
Java Application to Your Broker (p. 19).
• Your broker can send and receive messages of any size.
Amazon MQ Document History
The following table lists changes to the Amazon MQ Developer Guide. For Amazon MQ feature releases
and improvements, see Amazon MQ Release Notes (p. 70).
Date
Documentation Update
March 19, 2018
Clarified the following statement throughout this guide: An Active/standby
broker for high availability is comprised of two brokers in two different
Availability Zones, configured in a redundant pair. These brokers communicate
synchronously with your application, and with a shared storage location.
March 15, 2018
• Restructured the Amazon MQ Basic Elements (p. 29) section.
• Improved the explanation of the diagrams in the following sections:
• Concurrent Store and Dispatch for Queues (p. 35)
• Migrating without Service Interruption (p. 54)
• Migrating with Service Interruption (p. 55)
March 12, 2018
• Clarified and corrected the information in the Using Amazon MQ
Securely (p. 57) and Communicating with Amazon MQ (p. 58) sections.
• Added the Disable Concurrent Store and Dispatch for Queues with Slow
Consumers (p. 60) section.
• Grouped admonitions into a preface for the Configure advanced broker
settings (p. 12) section.
March 9, 2018
• Clarified and corrected the information in the Always Configure an
Authorization Map (p. 57) and Always Configure a System Group (p. 58)
sections.
• Added the authorizationEntry (p. 49) section and updated the kahaDB (p. 50)
section.
• Revised the diagrams in the Concurrent Store and Dispatch for Queues (p. 35)
section.
March 8, 2018
• Added the Always Configure an Authorization Map (p. 57) and Always Configure
a System Group (p. 58) sections.
• Added notes about broker suffixes to the Monitoring Amazon MQ using
CloudWatch (p. 64) section.
March 7, 2018
Updated the New and Frequently Viewed Amazon MQ Topics (p. 3) section.
March 6, 2018
Added the following note throughout this guide:
Note
Using the mq.t2.micro instance type is subject to CPU credits and
baseline performance—with the ability to burst above the baseline
71
Amazon MQ Developer Guide
Document History
Date
Documentation Update
level. If your application requires fixed performance, consider using an
mq.m4.large instance type.
March 1, 2018
• Added the Concurrent Store and Dispatch for Queues (p. 35) and Child Element
Attributes (p. 49) section.
• Added links from elements in the the section called “Permitted
Elements” (p. 37) section to their attributes and to child collection elements.
• Made corrections to the AWS Glossary in GitHub.
February 28, 2018
Corrected image display in GitHub.
February 27, 2018
In addition to HTML, PDF, and Kindle, the Amazon MQ Developer Guide is available
on GitHub. To leave feedback, choose the GitHub icon in the upper right-hand
corner.
February 26, 2018
• Made regions consistent in all examples and diagrams.
• Optimized links to the AWS console and product webpages.
February 22, 2018
Clarified and corrected the information in the following sections:
• Prefer Brokers without Public Accessibility (p. 57)
• Always Use Client-Side Encryption as a Complement to TLS (p. 57)
• Always Use the Failover Transport to Connect to Multiple Broker
Endpoints (p. 59)
• API Authentication and Authorization for Amazon MQ (p. 67)
• Messaging Authentication and Authorization for ActiveMQ (p. 68)
February 21, 2018
Corrected the Java code in the following sections:
• Working Java Example (p. 50)
• Connect a Java Application to Your Broker (p. 7)
• Always Use Connection Pooling (p. 59)
February 20, 2018
Clarified and corrected the information in the Amazon MQ Security (p. 67) and
Best Practices for Amazon MQ (p. 57) sections.
February 19, 2018
• Corrected the Java code in the Always Use Connection Pooling (p. 59) section.
• Clarified and corrected the information in the Always Use Client-Side
Encryption as a Complement to TLS (p. 57) section.
• Restructured and expanded the Best Practices for Amazon MQ (p. 57) and
Amazon MQ Security (p. 67) sections.
February 16, 2018
• Added the Using Amazon MQ Securely (p. 57) section.
• Updated the Communicating with Amazon MQ (p. 58) section.
• Corrected the Java code in the following sections:
• Getting Started with Amazon MQ (p. 6)
• AmazonMQExample.java (p. 51)
72
Amazon MQ Developer Guide
Document History
Date
Documentation Update
February 15, 2018
• Restructured and expanded the Best Practices for Amazon MQ (p. 57) section.
• Updated the following sections:
• How Can I Get Started with Amazon MQ? (p. 1)
• Next Steps (p. 10) (Getting Started)
• Related Resources (p. 69)
February 14, 2018
Updated the following sections:
•
•
•
•
Limits in Amazon MQ (p. 61)
Limits Related to API Throttling (p. 62)
Best Practices for Amazon MQ (p. 57)
Amazon MQ Security (p. 67)
February 13, 2018
• Updated the Related Resources (p. 69) section.
• Updated the Limits in Amazon MQ (p. 61) section.
• Added the We Want to Hear from You (p. 2) section.
February 2, 2018
Created the New and Frequently Viewed Amazon MQ Topics (p. 3) section.
January 25, 2018
• Fixed an error in the Add Java Dependencies (p. 51) subsection of the Working
Java Example (p. 50) section.
• The permission for REST operation ID RebootBroker is listed correctly as
mq:RebootBroker on the IAM console.
January 24, 2018
• Added the Never Modify or Delete the Amazon MQ Elastic Network
Interface (p. 58) section.
• Updated all diagrams throughout this guide.
• Added links to the Amazon MQ REST API Reference throughout this guide and
links to specific REST APIs to the API Authentication and Authorization for
Amazon MQ (p. 67) section.
January 19, 2018
Updated the information in the Apache ActiveMQ Resources (p. 69) section.
January 18, 2018
Clarified and corrected the information in the Limits in Amazon MQ (p. 61)
section.
January 17, 2018
Reinstated the recommendation to prefer virtual destinations over durable
subscriptions (p. 60), with an improved explanation.
January 11, 2018
• The Amazon MQ Developer Guide is available in Kindle format, in addition to
HTML and PDF.
• Clarified and corrected information in the API Authentication and Authorization
for Amazon MQ (p. 67) and Create an IAM User and Get Your AWS
Credentials (p. 4) sections.
January 3, 2018
Added DescribeConfigurationRevision to the API Authentication and
Authorization for Amazon MQ (p. 67) section.
December 15,
2017
Removed the recommendation against durable subscriptions from the Best
Practices for Amazon MQ (p. 57) section.
73
Amazon MQ Developer Guide
Document History
Date
Documentation Update
December 8, 2017
• Added the Enable Inbound Connections (p. 19) prerequisite to the Connecting
a Java Application to Your Broker (p. 19) and Working Java Example (p. 50)
sections.
• Added the following note throughout this guide: Currently, it isn't possible to
delete a configuration.
December 7, 2017
• Improved the code in the AmazonMQExample.java (p. 51).
• Added the API Authentication and Authorization for Amazon MQ (p. 67)
section.
December 5, 2017
• Clarified and corrected information in the Monitoring Amazon MQ using
CloudWatch (p. 64) section:
• Improved the metric descriptions.
• Added the Dimension for Broker Metrics (p. 64) and Dimensions for
Destination (Queue and Topic) Metrics (p. 66) sub-sections.
• Added the "Introducing Amazon MQ" video to the What is Amazon MQ? (p. 1)
section.
December 4, 2017
• Clarified the following information in the Limits Related to Data Storage (p. 62)
section: Storage capacity per broker is 200 GB.
• Added the Prerequisites (p. 50) to the Working Java Example (p. 50) section.
(The activemq-client.jar and activemq-pool.jar packages are
required for the example to work. For more information, see Connecting a Java
Application to Your Broker (p. 19)).
December 1, 2017
• Updated and improved the screenshots in all the tutorials.
• Clarified the following explanation throughout this guide: Making changes
to a configuration revision or an ActiveMQ user does not apply the changes
immediately. To apply your changes, you must wait for the next maintenance
window (p. 18) or reboot the broker (p. 25). For more information, see Amazon
MQ Broker Configuration Lifecycle (p. 36).
74
Amazon MQ Developer Guide
AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.
75