Deploy AWS MQ Message Brokers

The aws:mq/broker:Broker resource, part of the Pulumi AWS provider, provisions Amazon MQ message brokers for ActiveMQ and RabbitMQ engines, managing compute, storage, networking, and user configuration. This guide focuses on three capabilities: single-instance broker creation, storage type optimization, and cross-region data replication.

Amazon MQ brokers run in VPC subnets with security groups and reference broker configurations for engine-specific settings. The examples are intentionally small. Combine them with your own VPC infrastructure, security groups, and configuration resources.

Create a single-instance ActiveMQ broker

Most deployments start with a single-instance ActiveMQ broker for moderate message volumes, providing managed message queuing without multi-AZ complexity.

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 engineType and engineVersion specify which message broker software runs. The hostInstanceType determines compute capacity (mq.t2.micro for development, larger for production). The users block creates administrative accounts; for RabbitMQ, only one user can be created during provisioning. The configuration block references an existing broker configuration resource that defines ActiveMQ or RabbitMQ settings.

Optimize for high throughput with EBS storage

Applications with high message volumes benefit from EBS-backed storage and larger instance types that deliver better I/O performance than the default EFS storage.

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>

The storageType property switches from EFS (AWS default for ActiveMQ) to EBS, which requires mq.m5 instance types. EBS provides lower latency and higher throughput for message-intensive workloads. RabbitMQ brokers only support EBS storage.

Replicate messages across regions for disaster recovery

Mission-critical systems replicate data across regions to maintain availability during regional outages. Amazon MQ’s CRDR (Cross-Region Data Replication) creates a primary-replica pair.

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

The dataReplicationMode property enables CRDR when set to “CRDR”. The replica broker references the primary via dataReplicationPrimaryBrokerArn. Both brokers require a replicationUser (set replicationUser to true in the users block) and must use ACTIVE_STANDBY_MULTI_AZ deployment mode. The applyImmediately property forces immediate application of changes, causing a brief reboot.

Beyond these examples

These snippets focus on specific broker-level features: single-instance and multi-AZ deployments, storage type selection, and cross-region data replication. They’re intentionally minimal rather than full messaging infrastructures.

The examples reference pre-existing infrastructure such as VPC subnets (required but not shown in examples), security groups, and broker configurations for ActiveMQ/RabbitMQ settings. They focus on configuring the broker rather than provisioning the surrounding network.

To keep things focused, common broker patterns are omitted, including:

Subnet placement (subnetIds required but not shown)
LDAP authentication (ldapServerMetadata)
Encryption configuration (encryptionOptions)
Logging and audit configuration (logs)
Maintenance window scheduling (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 Amazon 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 FREE

Frequently Asked Questions

RabbitMQ-Specific Limitations

Why does changing RabbitMQ users recreate my broker?

For RabbitMQ brokers, any changes to the user block trigger full broker recreation. Amazon MQ doesn’t return RabbitMQ user information via APIs, preventing Pulumi from detecting drift or making updates. Create only one administrative user during provisioning, then manage additional users via the RabbitMQ Management API or Amazon MQ console.

What are the limitations of RabbitMQ brokers?

RabbitMQ brokers cannot have ENI-attached instances, LDAP authentication (authenticationStrategy: ldap), storage type efs, audit logging, console access for users, or user groups. Use ActiveMQ if you need these features.

Configuration & Updates

When do broker configuration changes take effect?

Changes to configuration or user are applied during the next maintenance window by default. This can cause Pulumi to show pending changes in planning. Set applyImmediately: true to apply changes immediately, but this causes brief downtime as the broker reboots.

What's the difference between SINGLE_INSTANCE and ACTIVE_STANDBY_MULTI_AZ?

SINGLE_INSTANCE (default) runs one broker in one subnet. ACTIVE_STANDBY_MULTI_AZ runs active and standby brokers across multiple subnets for high availability. CLUSTER_MULTI_AZ is also available for clustered deployments.

Storage & Deployment

What storage types are available for my broker?

For ActiveMQ: efs (AWS default) or ebs. For RabbitMQ: only ebs. When using ebs, you must use the mq.m5 instance type family (e.g., mq.m5.large).

How many subnets do I need for my deployment?

SINGLE_INSTANCE requires one subnet. ACTIVE_STANDBY_MULTI_AZ requires multiple subnets (one per availability zone).

Cross-Region Replication

How do I set up cross-region data replication?

Create a primary broker with deploymentMode: ACTIVE_STANDBY_MULTI_AZ and a user with replicationUser: true. Then create a replica broker with dataReplicationMode: CRDR and dataReplicationPrimaryBrokerArn pointing to the primary’s ARN.

What's required for CRDR mode?

When dataReplicationMode is CRDR, you must provide dataReplicationPrimaryBrokerArn with the ARN of the primary broker. Both brokers need a replication user configured.

Security & Lifecycle

Are my broker credentials stored securely?

Usernames and passwords are stored in plain-text in the Pulumi state. Use appropriate state encryption and access controls for your state backend.

Can I use LDAP authentication with RabbitMQ?

No, authenticationStrategy: ldap is only supported for ActiveMQ brokers. RabbitMQ brokers must use simple authentication.

What properties can't be changed after broker creation?

These properties are immutable: brokerName, engineType, subnetIds, deploymentMode, publiclyAccessible, encryptionOptions, ldapServerMetadata, and dataReplicationPrimaryBrokerArn. Changing them requires recreating the broker.

Using a different cloud?

Explore messaging guides for other cloud providers:

Azure Guides GCP Guides