The aws:mq/broker:Broker resource, part of the Pulumi AWS provider, provisions Amazon MQ message brokers that run ActiveMQ or RabbitMQ engines for application messaging. This guide focuses on three capabilities: basic broker creation with configuration, storage optimization for high throughput, and cross-region data replication.
Message brokers depend on broker configurations (XML files defining queues and topics), VPC subnets for placement, and security groups for network access. The examples are intentionally small. Combine them with your own VPC infrastructure and configuration files.
Create a basic ActiveMQ broker with configuration
Most deployments start with a single-instance ActiveMQ broker that connects applications through reliable message queuing.
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
const example = new aws.mq.Broker("example", {
brokerName: "example",
configuration: {
id: test.id,
revision: test.latestRevision,
},
engineType: "ActiveMQ",
engineVersion: "5.17.6",
hostInstanceType: "mq.t2.micro",
securityGroups: [testAwsSecurityGroup.id],
users: [{
username: "example_user",
password: "<password>",
}],
});
import pulumi
import pulumi_aws as aws
example = aws.mq.Broker("example",
broker_name="example",
configuration={
"id": test["id"],
"revision": test["latestRevision"],
},
engine_type="ActiveMQ",
engine_version="5.17.6",
host_instance_type="mq.t2.micro",
security_groups=[test_aws_security_group["id"]],
users=[{
"username": "example_user",
"password": "<password>",
}])
package main
import (
"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/mq"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
_, err := mq.NewBroker(ctx, "example", &mq.BrokerArgs{
BrokerName: pulumi.String("example"),
Configuration: &mq.BrokerConfigurationArgs{
Id: pulumi.Any(test.Id),
Revision: pulumi.Any(test.LatestRevision),
},
EngineType: pulumi.String("ActiveMQ"),
EngineVersion: pulumi.String("5.17.6"),
HostInstanceType: pulumi.String("mq.t2.micro"),
SecurityGroups: pulumi.StringArray{
testAwsSecurityGroup.Id,
},
Users: mq.BrokerUserArray{
&mq.BrokerUserArgs{
Username: pulumi.String("example_user"),
Password: pulumi.String("<password>"),
},
},
})
if err != nil {
return err
}
return nil
})
}
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;
return await Deployment.RunAsync(() =>
{
var example = new Aws.Mq.Broker("example", new()
{
BrokerName = "example",
Configuration = new Aws.Mq.Inputs.BrokerConfigurationArgs
{
Id = test.Id,
Revision = test.LatestRevision,
},
EngineType = "ActiveMQ",
EngineVersion = "5.17.6",
HostInstanceType = "mq.t2.micro",
SecurityGroups = new[]
{
testAwsSecurityGroup.Id,
},
Users = new[]
{
new Aws.Mq.Inputs.BrokerUserArgs
{
Username = "example_user",
Password = "<password>",
},
},
});
});
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.mq.Broker;
import com.pulumi.aws.mq.BrokerArgs;
import com.pulumi.aws.mq.inputs.BrokerConfigurationArgs;
import com.pulumi.aws.mq.inputs.BrokerUserArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var example = new Broker("example", BrokerArgs.builder()
.brokerName("example")
.configuration(BrokerConfigurationArgs.builder()
.id(test.id())
.revision(test.latestRevision())
.build())
.engineType("ActiveMQ")
.engineVersion("5.17.6")
.hostInstanceType("mq.t2.micro")
.securityGroups(testAwsSecurityGroup.id())
.users(BrokerUserArgs.builder()
.username("example_user")
.password("<password>")
.build())
.build());
}
}
resources:
example:
type: aws:mq:Broker
properties:
brokerName: example
configuration:
id: ${test.id}
revision: ${test.latestRevision}
engineType: ActiveMQ
engineVersion: 5.17.6
hostInstanceType: mq.t2.micro
securityGroups:
- ${testAwsSecurityGroup.id}
users:
- username: example_user
password: <password>
The broker provisions an ActiveMQ instance with the specified engineVersion and hostInstanceType. The configuration block references a broker configuration resource that defines queue and topic settings. The users array creates credentials for applications to connect; each user needs a username and password. The securityGroups property controls network access to the broker endpoints.
Optimize storage for high-throughput workloads
Production workloads with high message volumes benefit from EBS-backed storage and larger instance types.
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
const example = new aws.mq.Broker("example", {
brokerName: "example",
configuration: {
id: test.id,
revision: test.latestRevision,
},
engineType: "ActiveMQ",
engineVersion: "5.17.6",
storageType: "ebs",
hostInstanceType: "mq.m5.large",
securityGroups: [testAwsSecurityGroup.id],
users: [{
username: "example_user",
password: "<password>",
}],
});
import pulumi
import pulumi_aws as aws
example = aws.mq.Broker("example",
broker_name="example",
configuration={
"id": test["id"],
"revision": test["latestRevision"],
},
engine_type="ActiveMQ",
engine_version="5.17.6",
storage_type="ebs",
host_instance_type="mq.m5.large",
security_groups=[test_aws_security_group["id"]],
users=[{
"username": "example_user",
"password": "<password>",
}])
package main
import (
"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/mq"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
_, err := mq.NewBroker(ctx, "example", &mq.BrokerArgs{
BrokerName: pulumi.String("example"),
Configuration: &mq.BrokerConfigurationArgs{
Id: pulumi.Any(test.Id),
Revision: pulumi.Any(test.LatestRevision),
},
EngineType: pulumi.String("ActiveMQ"),
EngineVersion: pulumi.String("5.17.6"),
StorageType: pulumi.String("ebs"),
HostInstanceType: pulumi.String("mq.m5.large"),
SecurityGroups: pulumi.StringArray{
testAwsSecurityGroup.Id,
},
Users: mq.BrokerUserArray{
&mq.BrokerUserArgs{
Username: pulumi.String("example_user"),
Password: pulumi.String("<password>"),
},
},
})
if err != nil {
return err
}
return nil
})
}
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;
return await Deployment.RunAsync(() =>
{
var example = new Aws.Mq.Broker("example", new()
{
BrokerName = "example",
Configuration = new Aws.Mq.Inputs.BrokerConfigurationArgs
{
Id = test.Id,
Revision = test.LatestRevision,
},
EngineType = "ActiveMQ",
EngineVersion = "5.17.6",
StorageType = "ebs",
HostInstanceType = "mq.m5.large",
SecurityGroups = new[]
{
testAwsSecurityGroup.Id,
},
Users = new[]
{
new Aws.Mq.Inputs.BrokerUserArgs
{
Username = "example_user",
Password = "<password>",
},
},
});
});
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.mq.Broker;
import com.pulumi.aws.mq.BrokerArgs;
import com.pulumi.aws.mq.inputs.BrokerConfigurationArgs;
import com.pulumi.aws.mq.inputs.BrokerUserArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var example = new Broker("example", BrokerArgs.builder()
.brokerName("example")
.configuration(BrokerConfigurationArgs.builder()
.id(test.id())
.revision(test.latestRevision())
.build())
.engineType("ActiveMQ")
.engineVersion("5.17.6")
.storageType("ebs")
.hostInstanceType("mq.m5.large")
.securityGroups(testAwsSecurityGroup.id())
.users(BrokerUserArgs.builder()
.username("example_user")
.password("<password>")
.build())
.build());
}
}
resources:
example:
type: aws:mq:Broker
properties:
brokerName: example
configuration:
id: ${test.id}
revision: ${test.latestRevision}
engineType: ActiveMQ
engineVersion: 5.17.6
storageType: ebs
hostInstanceType: mq.m5.large
securityGroups:
- ${testAwsSecurityGroup.id}
users:
- username: example_user
password: <password>
Setting storageType to “ebs” switches from the default EFS storage to EBS volumes, which provide better I/O performance for high-throughput scenarios. EBS storage requires the mq.m5 instance family; this example uses mq.m5.large for increased network bandwidth and processing capacity. The combination of EBS storage and a larger instance type reduces message latency under load.
Replicate messages across regions for disaster recovery
Applications requiring disaster recovery use cross-region data replication (CRDR) to maintain synchronized brokers in separate regions.
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
const examplePrimary = new aws.mq.Broker("example_primary", {
applyImmediately: true,
brokerName: "example_primary",
engineType: "ActiveMQ",
engineVersion: "5.17.6",
hostInstanceType: "mq.m5.large",
securityGroups: [examplePrimaryAwsSecurityGroup.id],
deploymentMode: "ACTIVE_STANDBY_MULTI_AZ",
users: [
{
username: "example_user",
password: "<password>",
},
{
username: "example_replication_user",
password: "<password>",
replicationUser: true,
},
],
});
const example = new aws.mq.Broker("example", {
applyImmediately: true,
brokerName: "example",
engineType: "ActiveMQ",
engineVersion: "5.17.6",
hostInstanceType: "mq.m5.large",
securityGroups: [exampleAwsSecurityGroup.id],
deploymentMode: "ACTIVE_STANDBY_MULTI_AZ",
dataReplicationMode: "CRDR",
dataReplicationPrimaryBrokerArn: primary.arn,
users: [
{
username: "example_user",
password: "<password>",
},
{
username: "example_replication_user",
password: "<password>",
replicationUser: true,
},
],
});
import pulumi
import pulumi_aws as aws
example_primary = aws.mq.Broker("example_primary",
apply_immediately=True,
broker_name="example_primary",
engine_type="ActiveMQ",
engine_version="5.17.6",
host_instance_type="mq.m5.large",
security_groups=[example_primary_aws_security_group["id"]],
deployment_mode="ACTIVE_STANDBY_MULTI_AZ",
users=[
{
"username": "example_user",
"password": "<password>",
},
{
"username": "example_replication_user",
"password": "<password>",
"replication_user": True,
},
])
example = aws.mq.Broker("example",
apply_immediately=True,
broker_name="example",
engine_type="ActiveMQ",
engine_version="5.17.6",
host_instance_type="mq.m5.large",
security_groups=[example_aws_security_group["id"]],
deployment_mode="ACTIVE_STANDBY_MULTI_AZ",
data_replication_mode="CRDR",
data_replication_primary_broker_arn=primary["arn"],
users=[
{
"username": "example_user",
"password": "<password>",
},
{
"username": "example_replication_user",
"password": "<password>",
"replication_user": True,
},
])
package main
import (
"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/mq"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
_, err := mq.NewBroker(ctx, "example_primary", &mq.BrokerArgs{
ApplyImmediately: pulumi.Bool(true),
BrokerName: pulumi.String("example_primary"),
EngineType: pulumi.String("ActiveMQ"),
EngineVersion: pulumi.String("5.17.6"),
HostInstanceType: pulumi.String("mq.m5.large"),
SecurityGroups: pulumi.StringArray{
examplePrimaryAwsSecurityGroup.Id,
},
DeploymentMode: pulumi.String("ACTIVE_STANDBY_MULTI_AZ"),
Users: mq.BrokerUserArray{
&mq.BrokerUserArgs{
Username: pulumi.String("example_user"),
Password: pulumi.String("<password>"),
},
&mq.BrokerUserArgs{
Username: pulumi.String("example_replication_user"),
Password: pulumi.String("<password>"),
ReplicationUser: pulumi.Bool(true),
},
},
})
if err != nil {
return err
}
_, err = mq.NewBroker(ctx, "example", &mq.BrokerArgs{
ApplyImmediately: pulumi.Bool(true),
BrokerName: pulumi.String("example"),
EngineType: pulumi.String("ActiveMQ"),
EngineVersion: pulumi.String("5.17.6"),
HostInstanceType: pulumi.String("mq.m5.large"),
SecurityGroups: pulumi.StringArray{
exampleAwsSecurityGroup.Id,
},
DeploymentMode: pulumi.String("ACTIVE_STANDBY_MULTI_AZ"),
DataReplicationMode: pulumi.String("CRDR"),
DataReplicationPrimaryBrokerArn: pulumi.Any(primary.Arn),
Users: mq.BrokerUserArray{
&mq.BrokerUserArgs{
Username: pulumi.String("example_user"),
Password: pulumi.String("<password>"),
},
&mq.BrokerUserArgs{
Username: pulumi.String("example_replication_user"),
Password: pulumi.String("<password>"),
ReplicationUser: pulumi.Bool(true),
},
},
})
if err != nil {
return err
}
return nil
})
}
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;
return await Deployment.RunAsync(() =>
{
var examplePrimary = new Aws.Mq.Broker("example_primary", new()
{
ApplyImmediately = true,
BrokerName = "example_primary",
EngineType = "ActiveMQ",
EngineVersion = "5.17.6",
HostInstanceType = "mq.m5.large",
SecurityGroups = new[]
{
examplePrimaryAwsSecurityGroup.Id,
},
DeploymentMode = "ACTIVE_STANDBY_MULTI_AZ",
Users = new[]
{
new Aws.Mq.Inputs.BrokerUserArgs
{
Username = "example_user",
Password = "<password>",
},
new Aws.Mq.Inputs.BrokerUserArgs
{
Username = "example_replication_user",
Password = "<password>",
ReplicationUser = true,
},
},
});
var example = new Aws.Mq.Broker("example", new()
{
ApplyImmediately = true,
BrokerName = "example",
EngineType = "ActiveMQ",
EngineVersion = "5.17.6",
HostInstanceType = "mq.m5.large",
SecurityGroups = new[]
{
exampleAwsSecurityGroup.Id,
},
DeploymentMode = "ACTIVE_STANDBY_MULTI_AZ",
DataReplicationMode = "CRDR",
DataReplicationPrimaryBrokerArn = primary.Arn,
Users = new[]
{
new Aws.Mq.Inputs.BrokerUserArgs
{
Username = "example_user",
Password = "<password>",
},
new Aws.Mq.Inputs.BrokerUserArgs
{
Username = "example_replication_user",
Password = "<password>",
ReplicationUser = true,
},
},
});
});
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.mq.Broker;
import com.pulumi.aws.mq.BrokerArgs;
import com.pulumi.aws.mq.inputs.BrokerUserArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var examplePrimary = new Broker("examplePrimary", BrokerArgs.builder()
.applyImmediately(true)
.brokerName("example_primary")
.engineType("ActiveMQ")
.engineVersion("5.17.6")
.hostInstanceType("mq.m5.large")
.securityGroups(examplePrimaryAwsSecurityGroup.id())
.deploymentMode("ACTIVE_STANDBY_MULTI_AZ")
.users(
BrokerUserArgs.builder()
.username("example_user")
.password("<password>")
.build(),
BrokerUserArgs.builder()
.username("example_replication_user")
.password("<password>")
.replicationUser(true)
.build())
.build());
var example = new Broker("example", BrokerArgs.builder()
.applyImmediately(true)
.brokerName("example")
.engineType("ActiveMQ")
.engineVersion("5.17.6")
.hostInstanceType("mq.m5.large")
.securityGroups(exampleAwsSecurityGroup.id())
.deploymentMode("ACTIVE_STANDBY_MULTI_AZ")
.dataReplicationMode("CRDR")
.dataReplicationPrimaryBrokerArn(primary.arn())
.users(
BrokerUserArgs.builder()
.username("example_user")
.password("<password>")
.build(),
BrokerUserArgs.builder()
.username("example_replication_user")
.password("<password>")
.replicationUser(true)
.build())
.build());
}
}
resources:
examplePrimary:
type: aws:mq:Broker
name: example_primary
properties:
applyImmediately: true
brokerName: example_primary
engineType: ActiveMQ
engineVersion: 5.17.6
hostInstanceType: mq.m5.large
securityGroups:
- ${examplePrimaryAwsSecurityGroup.id}
deploymentMode: ACTIVE_STANDBY_MULTI_AZ
users:
- username: example_user
password: <password>
- username: example_replication_user
password: <password>
replicationUser: true
example:
type: aws:mq:Broker
properties:
applyImmediately: true
brokerName: example
engineType: ActiveMQ
engineVersion: 5.17.6
hostInstanceType: mq.m5.large
securityGroups:
- ${exampleAwsSecurityGroup.id}
deploymentMode: ACTIVE_STANDBY_MULTI_AZ
dataReplicationMode: CRDR
dataReplicationPrimaryBrokerArn: ${primary.arn}
users:
- username: example_user
password: <password>
- username: example_replication_user
password: <password>
replicationUser: true
This configuration creates two brokers: a primary in one region and a replica in another. The primary broker uses deploymentMode “ACTIVE_STANDBY_MULTI_AZ” for high availability within its region. The replica broker sets dataReplicationMode to “CRDR” and references the primary’s ARN via dataReplicationPrimaryBrokerArn. Both brokers require a replicationUser (set to true) in addition to regular application users. Amazon MQ automatically replicates messages from the primary to the replica, enabling failover if the primary region becomes unavailable. See the AWS MQ documentation for replication behavior details.
Beyond these examples
These snippets focus on specific broker-level features: broker engine and version selection, storage optimization for throughput, and cross-region data replication. They’re intentionally minimal rather than full messaging infrastructures.
The examples may reference pre-existing infrastructure such as broker configurations (XML files defining queues/topics), VPC subnets for broker placement, and security groups for network access. They focus on configuring the broker rather than provisioning the surrounding infrastructure.
To keep things focused, common broker patterns are omitted, including:
- LDAP authentication (ldapServerMetadata)
- Encryption configuration (encryptionOptions)
- Logging setup (logs block)
- Maintenance windows (maintenanceWindowStartTime)
- Public accessibility controls (publiclyAccessible)
These omissions are intentional: the goal is to illustrate how each broker feature is wired, not provide drop-in messaging modules. See the MQ Broker resource reference for all available configuration options.
Let's deploy AWS MQ Message Brokers
Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.
Try Pulumi Cloud for FREEFrequently Asked Questions
RabbitMQ-Specific Limitations
Why can't I update users on my RabbitMQ broker?
Amazon MQ doesn’t return broker users for RabbitMQ, preventing Pulumi from detecting drift or making user updates after initial creation.
Can I use LDAP authentication with RabbitMQ?
No,
ldap authentication strategy is not supported for RabbitMQ brokers. Use simple authentication instead.Storage & Instance Configuration
What storage types are available for my broker?
ActiveMQ supports
efs (AWS default) and ebs. RabbitMQ only supports ebs. When using ebs, you must use the mq.m5 instance family (e.g., mq.m5.large).How do I optimize my broker for high throughput?
Use
storageType: ebs with a larger mq.m5 instance type like mq.m5.large, as shown in the high-throughput example.Deployment & Networking
How many subnets do I need for different deployment modes?
SINGLE_INSTANCE requires one subnet. ACTIVE_STANDBY_MULTI_AZ and CLUSTER_MULTI_AZ require multiple subnets.What deployment modes are available?
Valid values are
SINGLE_INSTANCE (default), ACTIVE_STANDBY_MULTI_AZ, and CLUSTER_MULTI_AZ.Cross-Region Data Replication
How do I set up cross-region data replication?
Configure the primary broker with
deploymentMode: ACTIVE_STANDBY_MULTI_AZ and a user with replicationUser: true. On the replica, set dataReplicationMode: CRDR and dataReplicationPrimaryBrokerArn to the primary’s ARN.What's required when using CRDR data replication mode?
You must specify
dataReplicationPrimaryBrokerArn pointing to the primary broker’s ARN when dataReplicationMode is set to CRDR.Resource Management
What properties can't be changed after creating a broker?
These properties are immutable:
brokerName, engineType, subnetIds, deploymentMode, encryptionOptions, ldapServerMetadata, publiclyAccessible, and dataReplicationPrimaryBrokerArn. Changing them requires broker replacement.Are broker modifications applied immediately by default?
No,
applyImmediately defaults to false. Set it to true to apply modifications immediately instead of during the maintenance window.Using a different cloud?
Explore messaging guides for other cloud providers: