# AWS::AmazonMQ L2 Construct Library
<!--BEGIN STABILITY BANNER-->---
Features | Stability
---------------------------------------------|--------------------------------------------------------
Higher level constructs for ActiveMQ Brokers | 
Higher level constructs for RabbitMQ Bokers | 
> **Experimental:** Higher level constructs in this module that are marked as experimental are
> under active development. They are subject to non-backward compatible changes or removal in any
> future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and
> breaking changes will be announced in the release notes. This means that while you may use them,
> you may need to update your source code when upgrading to a newer version of this package.
---
<!--END STABILITY BANNER-->
## Table of Contents
* [Introduction](#introduction)
* [Security](#security)
* [ActiveMQ Brokers](#activemq-brokers)
* [ActiveMQ Broker Deployments](#activemq-broker-deployments)
* [ActiveMQ Broker Endpoints](#activemq-broker-endpoints)
* [Allowing Connections to ActiveMQ Brokers](#allowing-connections-to-activemq-brokers)
* [ActiveMQ Broker Configurations](#activemq-broker-configurations)
* [ActiveMQ Broker User Management](#activemq-broker-user-management)
* [ActiveMQ Broker Simple Authentication](#activemq-broker-simple-authentication)
* [ActiveMQ Broker LDAP Integration](#activemq-broker-ldap-integration)
* [Monitoring ActiveMQ Brokers](#monitoring-activemq-brokers)
* [ActiveMQ Broker Integration with AWS Lambda](#activemq-broker-integration-with-aws-lambda)
* [RabbitMQ Brokers](#rabbitmq-brokers)
* [RabbitMQ Broker Deployments](#rabbitmq-broker-deployments)
* [RabbitMQ Broker Endpoints](#rabbitmq-broker-endpoints)
* [Allowing Connections to a RabbitMQ Broker](#allowing-connections-to-a-rabbitmq-broker)
* [RabbitMQ Broker Configurations](#rabbitmq-broker-configurations)
* [Monitoring RabbitMQ Brokers](#monitoring-rabbitmq-brokers)
* [RabbitMQ Broker Integration with AWS Lambda](#rabbitmq-broker-integration-with-aws-lambda)
## Introduction
Amazon MQ is a managed service that makes it easy to create and run Apache ActiveMQ and RabbitMQ message brokers at scale. This library brings L2 AWS CDK constructs for Amazon MQ and introduces a notion of *broker deployment* and distincts between *a broker* and *a broker deployment*.
* *broker deployment* represents the configuration that defines how the broker (or a set of brokers in a particular configuration) will be deployed. Effectively, this is the representation of the `AWS::AmazonMQ::Broker` resource type, and will expose the relevant attributes of the resource type (such as ARN, Id).
* *broker* represents the means for accessing the broker, that is its endpoints and (in the case of ActiveMQ) IPv4 address(es).
This stems from the fact that when creating the `AWS::AmazonMQ::Broker` resource for ActiveMQ in the `ACTIVE_STANDBY_MULTI_AZ` deployment mode, the resulting AWS resource will in fact contain a set of two, distinct brokers.
The separation allows for expressing the resources as types in two ways:
* *is*, where a *broker deployment* implements the *broker* behavioral interface
* *has*, where a *broker deployment* contains (a set of) *brokers*.
### Security
In order to build secure solutions follow the guidelines and recommendations in the *[Security](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/using-amazon-mq-securely.html)* section of the AWS documentation for the Amazon MQ.
## ActiveMQ Brokers
Amazon MQ allows for creating AWS-managed ActiveMQ brokers. The brokers enable exchanging messages over [a number of protocols](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/broker.html#broker-protocols), e.g. AMQP 1.0, OpenWire, STOMP, MQTT.
### ActiveMQ Broker Deployments
The following example creates a minimal, [single-instance ActiveMQ Broker deployment](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/single-broker-deployment.html):
```python
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import ActiveMqBrokerEngineVersion, ActiveMqBrokerInstance, ActiveMqBrokerUserManagement
# stack: Stack
# broker_user: ISecret
broker = ActiveMqBrokerInstance(stack, "ActiveMqBroker",
publicly_accessible=False,
version=ActiveMqBrokerEngineVersion.V5_17_6,
instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),
user_management=ActiveMqBrokerUserManagement.simple(
users=[ActiveMqUser(
username=broker_user.secret_value_from_json("username").unsafe_unwrap(),
password=broker_user.secret_value_from_json("password")
)]
),
auto_minor_version_upgrade=True
)
```
The example below shows how to instantiate an active-standby redundant pair. `ActiveMqBrokerRedundantPair` doesn't implement `IActiveMqBroker`, but has two properties: `first`, and `second` that do. This stems from the fact that [ActiveMq redundant-pair deployment](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/active-standby-broker-deployment.html) exposes two, separate brokers that work in an active-standby configuration. The names are `first` (instead of `active`) and `second` (instead of `standby`) as there cannot be a guarantee which broker will be the `active` and which - the `standby`.
```python
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType, IVpc, SubnetSelection
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import ActiveMqBrokerEngineVersion, ActiveMqBrokerRedundantPair, ActiveMqBrokerUserManagement
# stack: Stack
# broker_user: ISecret
# vpc: IVpc
# vpc_subnets: SubnetSelection
broker_pair = ActiveMqBrokerRedundantPair(stack, "ActiveMqBrokerPair",
publicly_accessible=False,
version=ActiveMqBrokerEngineVersion.V5_17_6,
instance_type=InstanceType.of(InstanceClass.M5, InstanceSize.LARGE),
user_management=ActiveMqBrokerUserManagement.simple(
users=[ActiveMqUser(
username=broker_user.secret_value_from_json("username").unsafe_unwrap(),
password=broker_user.secret_value_from_json("password")
)]
),
auto_minor_version_upgrade=True,
vpc=vpc,
vpc_subnets=vpc_subnets
)
```
### ActiveMQ Broker Endpoints
Each created broker instance implements `IActiveMqBroker` and has `endpoints` property representing each allowed transport with url and port.
One can use the endpoints as in the example below
```python
from aws_cdk import CfnOutput
from cdklabs.cdk_amazonmq import IActiveMqBroker
# broker: IActiveMqBroker
CfnOutput(self, "AmqpEndpointUrl", value=broker.endpoints.amqp.url)
CfnOutput(self, "AmqpEndpointPort", value=broker.endpoints.amqp.port.to_string())
CfnOutput(self, "StompEndpointUrl", value=broker.endpoints.stomp.url)
CfnOutput(self, "StompEndpointPort", value=broker.endpoints.stomp.port.to_string())
CfnOutput(self, "OpenWireEndpointUrl", value=broker.endpoints.open_wire.url)
CfnOutput(self, "OpenWireEndpointPort", value=broker.endpoints.open_wire.port.to_string())
CfnOutput(self, "MqttEndpointUrl", value=broker.endpoints.mqtt.url)
CfnOutput(self, "MqttEndpointPort", value=broker.endpoints.mqtt.port.to_string())
CfnOutput(self, "WssEndpointUrl", value=broker.endpoints.wss.url)
CfnOutput(self, "WssEndpointPort", value=broker.endpoints.wss.port.to_string())
CfnOutput(self, "WebConsoleUrl", value=broker.endpoints.console.url)
CfnOutput(self, "WebConsolePort", value=broker.endpoints.console.port.to_string())
CfnOutput(self, "IpAddress", value=broker.ip_address)
```
For the redundant pair deployments one can access all the endpoints under properties `first` and `second`, as each implements `IActiveMqBroker`.
### Allowing Connections to ActiveMQ Brokers
For ActiveMQ broker deployments that are not publically accessible and with specified VPC and subnets you can control who can access the Broker using `connections` attribute. By default no connection is allowed and it has to be explicitly allowed.
```python
from aws_cdk.aws_ec2 import Peer, Port
from cdklabs.cdk_amazonmq import IActiveMqBroker, IActiveMqBrokerDeployment
# deployment: IActiveMqBrokerDeployment
# broker: IActiveMqBroker
# for the applications to interact over the STOMP protocol
deployment.connections.allow_from(Peer.ipv4("1.2.3.4/8"), Port.tcp(broker.endpoints.stomp.port))
# for the applications to interact over the OpenWire protocol
deployment.connections.allow_from(Peer.ipv4("1.2.3.4/8"), Port.tcp(broker.endpoints.open_wire.port))
# for the Web Console access
deployment.connections.allow_from(Peer.ipv4("1.2.3.4/8"), Port.tcp(broker.endpoints.console.port))
```
Mind that `connections` will be defined only if VPC and subnets are specified. For an instance of `ActiveMqBrokerRedundantPair` one would access the broker endpoints under either `first` or `second` property.
***Security:*** It is a security best practice *[to block unnecessary protocols with VPC security groups](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/using-amazon-mq-securely.html#amazon-mq-vpc-security-groups)*.
### ActiveMQ Broker Configurations
By default Amazon MQ will create a default configuration for the broker(s) on your deployment. You can introduce custom configurations by explicitly creating one as in the example below:
```python
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import ActiveMqBrokerConfiguration, ActiveMqBrokerConfigurationDefinition, ActiveMqAuthenticationStrategy, ActiveMqBrokerEngineVersion, ActiveMqBrokerInstance, ActiveMqBrokerUserManagement
# stack: Stack
# broker_user: ISecret
# configuration_data: str
custom_configuration = ActiveMqBrokerConfiguration(stack, "CustomConfiguration",
configuration_name="ConfigurationName",
description="ConfigurationDescription",
engine_version=ActiveMqBrokerEngineVersion.V5_18,
authentication_strategy=ActiveMqAuthenticationStrategy.SIMPLE,
definition=ActiveMqBrokerConfigurationDefinition.data(configuration_data)
)
broker = ActiveMqBrokerInstance(stack, "Broker",
publicly_accessible=False,
version=ActiveMqBrokerEngineVersion.V5_18,
instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),
user_management=ActiveMqBrokerUserManagement.simple(
users=[ActiveMqUser(
username=broker_user.secret_value_from_json("username").unsafe_unwrap(),
password=broker_user.secret_value_from_json("password")
)]
),
auto_minor_version_upgrade=True,
configuration=custom_configuration
)
```
A configuration can be associated with a specific broker also after the broker creation. Then, it is required to be explicitly associated with the broker.
```python
from cdklabs.cdk_amazonmq import IActiveMqBrokerConfiguration, IActiveMqBrokerDeployment
# configuration: IActiveMqBrokerConfiguration
# deployment: IActiveMqBrokerDeployment
configuration.associate_with(deployment)
```
This library also allows to modify an existing configuration. Such update of a particular configuration is [creating a new configuration *revision*](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/amazon-mq-creating-applying-configurations.html#creating-new-configuration-revision-console) so that a history of revisions can be viewed in the AWS Console. The new revision can be then associated with the broker so it uses it as a working configuration.
```python
from cdklabs.cdk_amazonmq import ActiveMqBrokerConfigurationDefinition, IActiveMqBrokerConfiguration, IActiveMqBrokerDeployment
# configuration: IActiveMqBrokerConfiguration
# deployment: IActiveMqBrokerDeployment
# new_data: str
new_revision = configuration.create_revision(
description="We need to modify an AuthorizationEntry",
definition=ActiveMqBrokerConfigurationDefinition.data(new_data)
)
new_revision.associate_with(deployment)
```
### ActiveMQ Broker User Management
#### ActiveMQ Broker Simple Authentication
Using ActiveMQ built-in [Simple Authentication](http://activemq.apache.org/security.html#Security-SimpleAuthenticationPlugin) users need to be provided during the broker deployment definition.
***Security:*** In the Simple Authentication User Management authorization is managed in the configuration. It is a security best practice to *[always configure an authorization map](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/using-amazon-mq-securely.html#always-configure-authorization-map)*.
#### ActiveMQ Broker LDAP Integration
Amazon MQ for ActiveMQ enables LDAP integration. An example below shows a minimal setup to configure an Amazon MQ for ActiveMQ broker.
```python
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import ActiveMqBrokerEngineVersion, ActiveMqBrokerInstance, ActiveMqBrokerUserManagement
# stack: Stack
# service_account_secret: ISecret
broker = ActiveMqBrokerInstance(stack, "ActiveMqBrokerInstance",
publicly_accessible=False,
version=ActiveMqBrokerEngineVersion.V5_17_6,
instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),
user_management=ActiveMqBrokerUserManagement.ldap(
hosts=["ldap.example.com"],
user_search_matching="uid={0}",
user_role_name="amq",
user_base="ou=users,dc=example,dc=com",
role_base="ou=roles,dc=example,dc=com",
role_search_matching="cn={0}",
role_name="amq",
service_account_password=service_account_secret.secret_value_from_json("password"),
service_account_username=service_account_secret.secret_value_from_json("username")
),
auto_minor_version_upgrade=True
)
```
### Monitoring ActiveMQ Brokers
This library introduces [a set of metrics](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/security-logging-monitoring-cloudwatch.html#activemq-logging-monitoring) that we can use for the `IActiveMqBrokerDeployment` monitoring. Each can be accessed as a method on the `IActiveMqBrokerDeployment` with the convention `metric[MetricName]`. An example below shows how one can use that:
```python
from cdklabs.cdk_amazonmq import IActiveMqBrokerDeployment
# stack: Stack
# deployment: IActiveMqBrokerDeployment
consumer_count_metric = deployment.metric_consumer_count()
consumer_count_metric.create_alarm(stack, "ConsumerCountAlarm",
threshold=100,
evaluation_periods=3,
datapoints_to_alarm=2
)
```
### ActiveMQ Broker Integration with AWS Lambda
Amazon MQ for ActiveMQ broker queues can be used as event sources for AWS Lambda functions. For authentication only the ActiveMQ SimpleAuthenticationPlugin is supported. Lambda consumes messages using the OpenWire/Java Message Service (JMS) protocol. No other protocols are supported for consuming messages. Within the JMS protocol, only TextMessage and BytesMessage are supported. Lambda also supports JMS custom properties. For more details on the requirements of the integration read [the documentation](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html).
The example below presents an example of creating such an event source mapping:
```python
from aws_cdk.aws_lambda import IFunction
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import ActiveMqEventSource, IActiveMqBrokerDeployment
# target: IFunction
# creds: ISecret # with username and password fields
# broker: IActiveMqBrokerDeployment
# queue_name: str
target.add_event_source(ActiveMqEventSource(
broker=broker,
credentials=creds,
queue_name=queue_name
))
```
***Security:*** When adding an Amazon MQ for ActiveMQ as an AWS Lambda function's event source the library updates the execution role's permissions to satisfy [Amazon MQ requirements for provisioning the event source mapping](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html#events-mq-permissions).
In the case of a private deployment the defined event source mapping will create a set of Elastic Network Interfaces (ENIs) in the subnets in which the broker deployment created communication endpoints. Thus, in order to allow the event source mapping to communicate with the broker one needs to additionally allow inbound traffic from the ENIs on the OpenWire port. As ENIs will use the same security group that governs the access to the broker endpoints you can simply allow communication from the broker's security group to itself on the OpenWire port as in the example below:
```python
from aws_cdk.aws_ec2 import Port
from cdklabs.cdk_amazonmq import IActiveMqBroker, IActiveMqBrokerDeployment
# deployment: IActiveMqBrokerDeployment
# broker: IActiveMqBroker
deployment.connections.allow_internally(Port.tcp(broker.endpoints.open_wire.port), "Allowing for the ESM")
```
## RabbitMQ Brokers
Amazon MQ allows for creating AWS-managed RabbitMQ brokers. The brokers enable exchanging messages over AMQP 0-9-1 protocol.
### RabbitMQ Broker Deployments
The following example creates a minimal, single-instance RabbitMQ broker deployment:
```python
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import RabbitMqBrokerEngineVersion, RabbitMqBrokerInstance
# stack: Stack
# admin_secret: ISecret
broker = RabbitMqBrokerInstance(stack, "RabbitMqBroker",
publicly_accessible=False,
version=RabbitMqBrokerEngineVersion.V3_11_20,
instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),
admin=Admin(
username=admin_secret.secret_value_from_json("username").unsafe_unwrap(),
password=admin_secret.secret_value_from_json("password")
),
auto_minor_version_upgrade=True
)
```
The next example creates a minimal RabbitMQ broker cluster:
```python
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import RabbitMqBrokerCluster, RabbitMqBrokerEngineVersion
# stack: Stack
# admin_secret: ISecret
broker = RabbitMqBrokerCluster(stack, "RabbitMqBroker",
publicly_accessible=False,
version=RabbitMqBrokerEngineVersion.V3_11_20,
instance_type=InstanceType.of(InstanceClass.M5, InstanceSize.LARGE),
admin=Admin(
username=admin_secret.secret_value_from_json("username").unsafe_unwrap(),
password=admin_secret.secret_value_from_json("password")
),
auto_minor_version_upgrade=True
)
```
### RabbitMQ Broker Endpoints
Each created broker has `endpoints` property with the AMQP endpoint url and port.
```python
from aws_cdk import CfnOutput
from cdklabs.cdk_amazonmq import IRabbitMqBroker
# broker: IRabbitMqBroker
CfnOutput(self, "AmqpEndpointUrl", value=broker.endpoints.amqp.url)
CfnOutput(self, "AmqpEndpointPort", value=broker.endpoints.amqp.port.to_string())
CfnOutput(self, "WebConsoleUrl", value=broker.endpoints.console.url)
CfnOutput(self, "WebConsolePort", value=broker.endpoints.console.port.to_string())
```
### Allowing Connections to a RabbitMQ Broker
For the RabbitMQ broker deployments that are not publically accessible and with specified VPC and subnets you can control who can access the broker using `connections` attribute.
```python
from aws_cdk.aws_ec2 import Peer, Port
from cdklabs.cdk_amazonmq import IRabbitMqBroker, IRabbitMqBrokerDeployment
# deployment: IRabbitMqBrokerDeployment
# broker: IRabbitMqBroker
# for the applications to interact over the AMQP protocol
deployment.connections.allow_from(Peer.ipv4("1.2.3.4/8"), Port.tcp(broker.endpoints.amqp.port))
# for the Web Console access
deployment.connections.allow_from(Peer.ipv4("1.2.3.4/8"), Port.tcp(broker.endpoints.console.port))
```
Mind that `connections` will be defined only if VPC and subnets are specified.
### RabbitMQ Broker Configurations
If you do not specify a custom RabbitMQ Broker configuration, Amazon MQ for RabbitMQ will create a default configuration for the broker on your behalf. You can introduce custom configurations by explicitly creating one as in the example below:
```python
from aws_cdk import Duration
from aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import RabbitMqBrokerConfiguration, RabbitMqBrokerConfigurationDefinition, RabbitMqBrokerEngineVersion, RabbitMqBrokerInstance
# stack: Stack
# admin_secret: ISecret
custom_configuration = RabbitMqBrokerConfiguration(stack, "CustomConfiguration",
configuration_name="ConfigurationName",
description="ConfigurationDescription",
engine_version=RabbitMqBrokerEngineVersion.V3_11_20,
definition=RabbitMqBrokerConfigurationDefinition.parameters(
consumer_timeout=Duration.minutes(20)
)
)
broker = RabbitMqBrokerInstance(stack, "Broker",
publicly_accessible=False,
version=RabbitMqBrokerEngineVersion.V3_11_20,
instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),
admin=Admin(
username=admin_secret.secret_value_from_json("username").unsafe_unwrap(),
password=admin_secret.secret_value_from_json("password")
),
auto_minor_version_upgrade=True,
configuration=custom_configuration
)
```
A configuration can be associated with a specific broker also after the deployment. Then, it is required to be explicitly associated with the broker.
```python
from cdklabs.cdk_amazonmq import IRabbitMqBrokerConfiguration, IRabbitMqBrokerDeployment
# configuration: IRabbitMqBrokerConfiguration
# deployment: IRabbitMqBrokerDeployment
configuration.associate_with(deployment)
```
This library also allows to modify an existing configuration. Such update of a particular configuration is [creating a new configuration *revision*](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/rabbitmq-creating-applying-configurations.html#creating-new-rabbitmq-configuration-revision-console) so that a history of revisions can be viewed in the AWS Console. The new revision can be then associated with the broker so it uses it as a working configuration.
```python
from aws_cdk import Duration
from cdklabs.cdk_amazonmq import IRabbitMqBrokerConfiguration, IRabbitMqBrokerDeployment, RabbitMqBrokerConfigurationDefinition
# configuration: IRabbitMqBrokerConfiguration
# deployment: IRabbitMqBrokerDeployment
# new_consumer_timeout: Duration
new_revision = configuration.create_revision(
description="We need to modify the consumer timeout",
definition=RabbitMqBrokerConfigurationDefinition.parameters(
consumer_timeout=new_consumer_timeout
)
)
new_revision.associate_with(deployment)
```
### Monitoring RabbitMQ Brokers
This library introduces [a set of metrics](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/security-logging-monitoring-cloudwatch.html#rabbitmq-logging-monitoring) that we can use for the `IRabbitMqBrokerDeployment` monitoring. Each can be accessed as a method on the `IRabbitMqBrokerDeployment` with the convention `metric[MetricName]`. An example below shows how one can use that:
```python
from cdklabs.cdk_amazonmq import IRabbitMqBrokerDeployment
# stack: Stack
# deployment: IRabbitMqBrokerDeployment
consumer_count_metric = deployment.metric_consumer_count()
consumer_count_metric.create_alarm(stack, "ConsumerCountAlarm",
threshold=100,
evaluation_periods=3,
datapoints_to_alarm=2
)
```
### RabbitMQ Broker Integration with AWS Lambda
Amazon MQ for RabbitMQ broker queues can be used as event sources for AWS Lambda functions. For authentication only the PLAIN authentication mechanism is supported. Lambda consumes messages using the AMQP 0-9-1 protocol. No other protocols are supported for consuming messages. For more details on the requirements of the integration read [the documentation](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html).
The example below presents an example of creating such an event source mapping:
```python
from aws_cdk.aws_lambda import IFunction
from aws_cdk.aws_secretsmanager import ISecret
from cdklabs.cdk_amazonmq import IRabbitMqBrokerDeployment, RabbitMqEventSource
# target: IFunction
# creds: ISecret # with username and password fields
# broker: IRabbitMqBrokerDeployment
# queue_name: str
target.add_event_source(RabbitMqEventSource(
broker=broker,
credentials=creds,
queue_name=queue_name
))
```
***Security:*** When adding an Amazon MQ for RabbitMQ as an AWS Lambda function's event source the library updates the execution role's permissions to satisfy [Amazon MQ requirements for provisioning the event source mapping](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html#events-mq-permissions).
In the case of a private deployment the defined event source mapping will create a set of Elastic Network Interfaces (ENIs) in the subnets in which the broker deployment created communication VPC Endpoints. Thus, in order to allow the event source mapping to communicate with the broekr one needs to additionally allow inbound traffic from the ENIs. As ENIs will use the same security group that governs the access to the VPC Endpoints you can simply allow communication from the broker's security group to itself on the AMQP port as in the example below:
```python
from cdklabs.cdk_amazonmq import IRabbitMqBrokerDeployment
# deployment: IRabbitMqBrokerDeployment
deployment.connections.allow_default_port_internally()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cdklabs/cdk-amazonmq.git",
"name": "cdklabs.cdk-amazonmq",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services<aws-cdk-dev@amazon.com>",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f1/34/35e64e71c59a7f7d67d17fe8dc79010bd6009558f3bd5a8afa2f93081bb3/cdklabs_cdk_amazonmq-0.0.1.tar.gz",
"platform": null,
"description": "# AWS::AmazonMQ L2 Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\nFeatures | Stability\n---------------------------------------------|--------------------------------------------------------\nHigher level constructs for ActiveMQ Brokers | \nHigher level constructs for RabbitMQ Bokers | \n\n> **Experimental:** Higher level constructs in this module that are marked as experimental are\n> under active development. They are subject to non-backward compatible changes or removal in any\n> future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and\n> breaking changes will be announced in the release notes. This means that while you may use them,\n> you may need to update your source code when upgrading to a newer version of this package.\n\n---\n<!--END STABILITY BANNER-->\n\n## Table of Contents\n\n* [Introduction](#introduction)\n\n * [Security](#security)\n* [ActiveMQ Brokers](#activemq-brokers)\n\n * [ActiveMQ Broker Deployments](#activemq-broker-deployments)\n * [ActiveMQ Broker Endpoints](#activemq-broker-endpoints)\n * [Allowing Connections to ActiveMQ Brokers](#allowing-connections-to-activemq-brokers)\n * [ActiveMQ Broker Configurations](#activemq-broker-configurations)\n * [ActiveMQ Broker User Management](#activemq-broker-user-management)\n\n * [ActiveMQ Broker Simple Authentication](#activemq-broker-simple-authentication)\n * [ActiveMQ Broker LDAP Integration](#activemq-broker-ldap-integration)\n * [Monitoring ActiveMQ Brokers](#monitoring-activemq-brokers)\n * [ActiveMQ Broker Integration with AWS Lambda](#activemq-broker-integration-with-aws-lambda)\n* [RabbitMQ Brokers](#rabbitmq-brokers)\n\n * [RabbitMQ Broker Deployments](#rabbitmq-broker-deployments)\n * [RabbitMQ Broker Endpoints](#rabbitmq-broker-endpoints)\n * [Allowing Connections to a RabbitMQ Broker](#allowing-connections-to-a-rabbitmq-broker)\n * [RabbitMQ Broker Configurations](#rabbitmq-broker-configurations)\n * [Monitoring RabbitMQ Brokers](#monitoring-rabbitmq-brokers)\n * [RabbitMQ Broker Integration with AWS Lambda](#rabbitmq-broker-integration-with-aws-lambda)\n\n## Introduction\n\nAmazon MQ is a managed service that makes it easy to create and run Apache ActiveMQ and RabbitMQ message brokers at scale. This library brings L2 AWS CDK constructs for Amazon MQ and introduces a notion of *broker deployment* and distincts between *a broker* and *a broker deployment*.\n\n* *broker deployment* represents the configuration that defines how the broker (or a set of brokers in a particular configuration) will be deployed. Effectively, this is the representation of the `AWS::AmazonMQ::Broker` resource type, and will expose the relevant attributes of the resource type (such as ARN, Id).\n* *broker* represents the means for accessing the broker, that is its endpoints and (in the case of ActiveMQ) IPv4 address(es).\n\nThis stems from the fact that when creating the `AWS::AmazonMQ::Broker` resource for ActiveMQ in the `ACTIVE_STANDBY_MULTI_AZ` deployment mode, the resulting AWS resource will in fact contain a set of two, distinct brokers.\n\nThe separation allows for expressing the resources as types in two ways:\n\n* *is*, where a *broker deployment* implements the *broker* behavioral interface\n* *has*, where a *broker deployment* contains (a set of) *brokers*.\n\n### Security\n\nIn order to build secure solutions follow the guidelines and recommendations in the *[Security](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/using-amazon-mq-securely.html)* section of the AWS documentation for the Amazon MQ.\n\n## ActiveMQ Brokers\n\nAmazon MQ allows for creating AWS-managed ActiveMQ brokers. The brokers enable exchanging messages over [a number of protocols](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/broker.html#broker-protocols), e.g. AMQP 1.0, OpenWire, STOMP, MQTT.\n\n### ActiveMQ Broker Deployments\n\nThe following example creates a minimal, [single-instance ActiveMQ Broker deployment](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/single-broker-deployment.html):\n\n```python\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import ActiveMqBrokerEngineVersion, ActiveMqBrokerInstance, ActiveMqBrokerUserManagement\n\n# stack: Stack\n# broker_user: ISecret\n\n\nbroker = ActiveMqBrokerInstance(stack, \"ActiveMqBroker\",\n publicly_accessible=False,\n version=ActiveMqBrokerEngineVersion.V5_17_6,\n instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),\n user_management=ActiveMqBrokerUserManagement.simple(\n users=[ActiveMqUser(\n username=broker_user.secret_value_from_json(\"username\").unsafe_unwrap(),\n password=broker_user.secret_value_from_json(\"password\")\n )]\n ),\n auto_minor_version_upgrade=True\n)\n```\n\nThe example below shows how to instantiate an active-standby redundant pair. `ActiveMqBrokerRedundantPair` doesn't implement `IActiveMqBroker`, but has two properties: `first`, and `second` that do. This stems from the fact that [ActiveMq redundant-pair deployment](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/active-standby-broker-deployment.html) exposes two, separate brokers that work in an active-standby configuration. The names are `first` (instead of `active`) and `second` (instead of `standby`) as there cannot be a guarantee which broker will be the `active` and which - the `standby`.\n\n```python\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType, IVpc, SubnetSelection\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import ActiveMqBrokerEngineVersion, ActiveMqBrokerRedundantPair, ActiveMqBrokerUserManagement\n\n# stack: Stack\n# broker_user: ISecret\n# vpc: IVpc\n# vpc_subnets: SubnetSelection\n\n\nbroker_pair = ActiveMqBrokerRedundantPair(stack, \"ActiveMqBrokerPair\",\n publicly_accessible=False,\n version=ActiveMqBrokerEngineVersion.V5_17_6,\n instance_type=InstanceType.of(InstanceClass.M5, InstanceSize.LARGE),\n user_management=ActiveMqBrokerUserManagement.simple(\n users=[ActiveMqUser(\n username=broker_user.secret_value_from_json(\"username\").unsafe_unwrap(),\n password=broker_user.secret_value_from_json(\"password\")\n )]\n ),\n auto_minor_version_upgrade=True,\n vpc=vpc,\n vpc_subnets=vpc_subnets\n)\n```\n\n### ActiveMQ Broker Endpoints\n\nEach created broker instance implements `IActiveMqBroker` and has `endpoints` property representing each allowed transport with url and port.\n\nOne can use the endpoints as in the example below\n\n```python\nfrom aws_cdk import CfnOutput\nfrom cdklabs.cdk_amazonmq import IActiveMqBroker\n\n# broker: IActiveMqBroker\n\n\nCfnOutput(self, \"AmqpEndpointUrl\", value=broker.endpoints.amqp.url)\nCfnOutput(self, \"AmqpEndpointPort\", value=broker.endpoints.amqp.port.to_string())\n\nCfnOutput(self, \"StompEndpointUrl\", value=broker.endpoints.stomp.url)\nCfnOutput(self, \"StompEndpointPort\", value=broker.endpoints.stomp.port.to_string())\n\nCfnOutput(self, \"OpenWireEndpointUrl\", value=broker.endpoints.open_wire.url)\nCfnOutput(self, \"OpenWireEndpointPort\", value=broker.endpoints.open_wire.port.to_string())\n\nCfnOutput(self, \"MqttEndpointUrl\", value=broker.endpoints.mqtt.url)\nCfnOutput(self, \"MqttEndpointPort\", value=broker.endpoints.mqtt.port.to_string())\n\nCfnOutput(self, \"WssEndpointUrl\", value=broker.endpoints.wss.url)\nCfnOutput(self, \"WssEndpointPort\", value=broker.endpoints.wss.port.to_string())\n\nCfnOutput(self, \"WebConsoleUrl\", value=broker.endpoints.console.url)\nCfnOutput(self, \"WebConsolePort\", value=broker.endpoints.console.port.to_string())\n\nCfnOutput(self, \"IpAddress\", value=broker.ip_address)\n```\n\nFor the redundant pair deployments one can access all the endpoints under properties `first` and `second`, as each implements `IActiveMqBroker`.\n\n### Allowing Connections to ActiveMQ Brokers\n\nFor ActiveMQ broker deployments that are not publically accessible and with specified VPC and subnets you can control who can access the Broker using `connections` attribute. By default no connection is allowed and it has to be explicitly allowed.\n\n```python\nfrom aws_cdk.aws_ec2 import Peer, Port\nfrom cdklabs.cdk_amazonmq import IActiveMqBroker, IActiveMqBrokerDeployment\n\n# deployment: IActiveMqBrokerDeployment\n# broker: IActiveMqBroker\n\n\n# for the applications to interact over the STOMP protocol\ndeployment.connections.allow_from(Peer.ipv4(\"1.2.3.4/8\"), Port.tcp(broker.endpoints.stomp.port))\n\n# for the applications to interact over the OpenWire protocol\ndeployment.connections.allow_from(Peer.ipv4(\"1.2.3.4/8\"), Port.tcp(broker.endpoints.open_wire.port))\n\n# for the Web Console access\ndeployment.connections.allow_from(Peer.ipv4(\"1.2.3.4/8\"), Port.tcp(broker.endpoints.console.port))\n```\n\nMind that `connections` will be defined only if VPC and subnets are specified. For an instance of `ActiveMqBrokerRedundantPair` one would access the broker endpoints under either `first` or `second` property.\n\n***Security:*** It is a security best practice *[to block unnecessary protocols with VPC security groups](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/using-amazon-mq-securely.html#amazon-mq-vpc-security-groups)*.\n\n### ActiveMQ Broker Configurations\n\nBy default Amazon MQ will create a default configuration for the broker(s) on your deployment. You can introduce custom configurations by explicitly creating one as in the example below:\n\n```python\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import ActiveMqBrokerConfiguration, ActiveMqBrokerConfigurationDefinition, ActiveMqAuthenticationStrategy, ActiveMqBrokerEngineVersion, ActiveMqBrokerInstance, ActiveMqBrokerUserManagement\n\n# stack: Stack\n# broker_user: ISecret\n# configuration_data: str\n\n\ncustom_configuration = ActiveMqBrokerConfiguration(stack, \"CustomConfiguration\",\n configuration_name=\"ConfigurationName\",\n description=\"ConfigurationDescription\",\n engine_version=ActiveMqBrokerEngineVersion.V5_18,\n authentication_strategy=ActiveMqAuthenticationStrategy.SIMPLE,\n definition=ActiveMqBrokerConfigurationDefinition.data(configuration_data)\n)\n\nbroker = ActiveMqBrokerInstance(stack, \"Broker\",\n publicly_accessible=False,\n version=ActiveMqBrokerEngineVersion.V5_18,\n instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),\n user_management=ActiveMqBrokerUserManagement.simple(\n users=[ActiveMqUser(\n username=broker_user.secret_value_from_json(\"username\").unsafe_unwrap(),\n password=broker_user.secret_value_from_json(\"password\")\n )]\n ),\n auto_minor_version_upgrade=True,\n configuration=custom_configuration\n)\n```\n\nA configuration can be associated with a specific broker also after the broker creation. Then, it is required to be explicitly associated with the broker.\n\n```python\nfrom cdklabs.cdk_amazonmq import IActiveMqBrokerConfiguration, IActiveMqBrokerDeployment\n\n# configuration: IActiveMqBrokerConfiguration\n# deployment: IActiveMqBrokerDeployment\n\n\nconfiguration.associate_with(deployment)\n```\n\nThis library also allows to modify an existing configuration. Such update of a particular configuration is [creating a new configuration *revision*](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/amazon-mq-creating-applying-configurations.html#creating-new-configuration-revision-console) so that a history of revisions can be viewed in the AWS Console. The new revision can be then associated with the broker so it uses it as a working configuration.\n\n```python\nfrom cdklabs.cdk_amazonmq import ActiveMqBrokerConfigurationDefinition, IActiveMqBrokerConfiguration, IActiveMqBrokerDeployment\n\n# configuration: IActiveMqBrokerConfiguration\n# deployment: IActiveMqBrokerDeployment\n# new_data: str\n\n\nnew_revision = configuration.create_revision(\n description=\"We need to modify an AuthorizationEntry\",\n definition=ActiveMqBrokerConfigurationDefinition.data(new_data)\n)\n\nnew_revision.associate_with(deployment)\n```\n\n### ActiveMQ Broker User Management\n\n#### ActiveMQ Broker Simple Authentication\n\nUsing ActiveMQ built-in [Simple Authentication](http://activemq.apache.org/security.html#Security-SimpleAuthenticationPlugin) users need to be provided during the broker deployment definition.\n\n***Security:*** In the Simple Authentication User Management authorization is managed in the configuration. It is a security best practice to *[always configure an authorization map](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/using-amazon-mq-securely.html#always-configure-authorization-map)*.\n\n#### ActiveMQ Broker LDAP Integration\n\nAmazon MQ for ActiveMQ enables LDAP integration. An example below shows a minimal setup to configure an Amazon MQ for ActiveMQ broker.\n\n```python\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import ActiveMqBrokerEngineVersion, ActiveMqBrokerInstance, ActiveMqBrokerUserManagement\n\n# stack: Stack\n# service_account_secret: ISecret\n\n\nbroker = ActiveMqBrokerInstance(stack, \"ActiveMqBrokerInstance\",\n publicly_accessible=False,\n version=ActiveMqBrokerEngineVersion.V5_17_6,\n instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),\n user_management=ActiveMqBrokerUserManagement.ldap(\n hosts=[\"ldap.example.com\"],\n user_search_matching=\"uid={0}\",\n user_role_name=\"amq\",\n user_base=\"ou=users,dc=example,dc=com\",\n role_base=\"ou=roles,dc=example,dc=com\",\n role_search_matching=\"cn={0}\",\n role_name=\"amq\",\n service_account_password=service_account_secret.secret_value_from_json(\"password\"),\n service_account_username=service_account_secret.secret_value_from_json(\"username\")\n ),\n auto_minor_version_upgrade=True\n)\n```\n\n### Monitoring ActiveMQ Brokers\n\nThis library introduces [a set of metrics](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/security-logging-monitoring-cloudwatch.html#activemq-logging-monitoring) that we can use for the `IActiveMqBrokerDeployment` monitoring. Each can be accessed as a method on the `IActiveMqBrokerDeployment` with the convention `metric[MetricName]`. An example below shows how one can use that:\n\n```python\nfrom cdklabs.cdk_amazonmq import IActiveMqBrokerDeployment\n\n# stack: Stack\n# deployment: IActiveMqBrokerDeployment\n\n\nconsumer_count_metric = deployment.metric_consumer_count()\nconsumer_count_metric.create_alarm(stack, \"ConsumerCountAlarm\",\n threshold=100,\n evaluation_periods=3,\n datapoints_to_alarm=2\n)\n```\n\n### ActiveMQ Broker Integration with AWS Lambda\n\nAmazon MQ for ActiveMQ broker queues can be used as event sources for AWS Lambda functions. For authentication only the ActiveMQ SimpleAuthenticationPlugin is supported. Lambda consumes messages using the OpenWire/Java Message Service (JMS) protocol. No other protocols are supported for consuming messages. Within the JMS protocol, only TextMessage and BytesMessage are supported. Lambda also supports JMS custom properties. For more details on the requirements of the integration read [the documentation](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html).\n\nThe example below presents an example of creating such an event source mapping:\n\n```python\nfrom aws_cdk.aws_lambda import IFunction\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import ActiveMqEventSource, IActiveMqBrokerDeployment\n\n# target: IFunction\n# creds: ISecret # with username and password fields\n# broker: IActiveMqBrokerDeployment\n# queue_name: str\n\n\ntarget.add_event_source(ActiveMqEventSource(\n broker=broker,\n credentials=creds,\n queue_name=queue_name\n))\n```\n\n***Security:*** When adding an Amazon MQ for ActiveMQ as an AWS Lambda function's event source the library updates the execution role's permissions to satisfy [Amazon MQ requirements for provisioning the event source mapping](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html#events-mq-permissions).\n\nIn the case of a private deployment the defined event source mapping will create a set of Elastic Network Interfaces (ENIs) in the subnets in which the broker deployment created communication endpoints. Thus, in order to allow the event source mapping to communicate with the broker one needs to additionally allow inbound traffic from the ENIs on the OpenWire port. As ENIs will use the same security group that governs the access to the broker endpoints you can simply allow communication from the broker's security group to itself on the OpenWire port as in the example below:\n\n```python\nfrom aws_cdk.aws_ec2 import Port\nfrom cdklabs.cdk_amazonmq import IActiveMqBroker, IActiveMqBrokerDeployment\n\n# deployment: IActiveMqBrokerDeployment\n# broker: IActiveMqBroker\n\n\ndeployment.connections.allow_internally(Port.tcp(broker.endpoints.open_wire.port), \"Allowing for the ESM\")\n```\n\n## RabbitMQ Brokers\n\nAmazon MQ allows for creating AWS-managed RabbitMQ brokers. The brokers enable exchanging messages over AMQP 0-9-1 protocol.\n\n### RabbitMQ Broker Deployments\n\nThe following example creates a minimal, single-instance RabbitMQ broker deployment:\n\n```python\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import RabbitMqBrokerEngineVersion, RabbitMqBrokerInstance\n\n# stack: Stack\n# admin_secret: ISecret\n\n\nbroker = RabbitMqBrokerInstance(stack, \"RabbitMqBroker\",\n publicly_accessible=False,\n version=RabbitMqBrokerEngineVersion.V3_11_20,\n instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),\n admin=Admin(\n username=admin_secret.secret_value_from_json(\"username\").unsafe_unwrap(),\n password=admin_secret.secret_value_from_json(\"password\")\n ),\n auto_minor_version_upgrade=True\n)\n```\n\nThe next example creates a minimal RabbitMQ broker cluster:\n\n```python\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import RabbitMqBrokerCluster, RabbitMqBrokerEngineVersion\n\n# stack: Stack\n# admin_secret: ISecret\n\n\nbroker = RabbitMqBrokerCluster(stack, \"RabbitMqBroker\",\n publicly_accessible=False,\n version=RabbitMqBrokerEngineVersion.V3_11_20,\n instance_type=InstanceType.of(InstanceClass.M5, InstanceSize.LARGE),\n admin=Admin(\n username=admin_secret.secret_value_from_json(\"username\").unsafe_unwrap(),\n password=admin_secret.secret_value_from_json(\"password\")\n ),\n auto_minor_version_upgrade=True\n)\n```\n\n### RabbitMQ Broker Endpoints\n\nEach created broker has `endpoints` property with the AMQP endpoint url and port.\n\n```python\nfrom aws_cdk import CfnOutput\nfrom cdklabs.cdk_amazonmq import IRabbitMqBroker\n\n# broker: IRabbitMqBroker\n\n\nCfnOutput(self, \"AmqpEndpointUrl\", value=broker.endpoints.amqp.url)\nCfnOutput(self, \"AmqpEndpointPort\", value=broker.endpoints.amqp.port.to_string())\nCfnOutput(self, \"WebConsoleUrl\", value=broker.endpoints.console.url)\nCfnOutput(self, \"WebConsolePort\", value=broker.endpoints.console.port.to_string())\n```\n\n### Allowing Connections to a RabbitMQ Broker\n\nFor the RabbitMQ broker deployments that are not publically accessible and with specified VPC and subnets you can control who can access the broker using `connections` attribute.\n\n```python\nfrom aws_cdk.aws_ec2 import Peer, Port\nfrom cdklabs.cdk_amazonmq import IRabbitMqBroker, IRabbitMqBrokerDeployment\n\n# deployment: IRabbitMqBrokerDeployment\n# broker: IRabbitMqBroker\n\n\n# for the applications to interact over the AMQP protocol\ndeployment.connections.allow_from(Peer.ipv4(\"1.2.3.4/8\"), Port.tcp(broker.endpoints.amqp.port))\n\n# for the Web Console access\ndeployment.connections.allow_from(Peer.ipv4(\"1.2.3.4/8\"), Port.tcp(broker.endpoints.console.port))\n```\n\nMind that `connections` will be defined only if VPC and subnets are specified.\n\n### RabbitMQ Broker Configurations\n\nIf you do not specify a custom RabbitMQ Broker configuration, Amazon MQ for RabbitMQ will create a default configuration for the broker on your behalf. You can introduce custom configurations by explicitly creating one as in the example below:\n\n```python\nfrom aws_cdk import Duration\nfrom aws_cdk.aws_ec2 import InstanceClass, InstanceSize, InstanceType\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import RabbitMqBrokerConfiguration, RabbitMqBrokerConfigurationDefinition, RabbitMqBrokerEngineVersion, RabbitMqBrokerInstance\n\n# stack: Stack\n# admin_secret: ISecret\n\n\ncustom_configuration = RabbitMqBrokerConfiguration(stack, \"CustomConfiguration\",\n configuration_name=\"ConfigurationName\",\n description=\"ConfigurationDescription\",\n engine_version=RabbitMqBrokerEngineVersion.V3_11_20,\n definition=RabbitMqBrokerConfigurationDefinition.parameters(\n consumer_timeout=Duration.minutes(20)\n )\n)\n\nbroker = RabbitMqBrokerInstance(stack, \"Broker\",\n publicly_accessible=False,\n version=RabbitMqBrokerEngineVersion.V3_11_20,\n instance_type=InstanceType.of(InstanceClass.T3, InstanceSize.MICRO),\n admin=Admin(\n username=admin_secret.secret_value_from_json(\"username\").unsafe_unwrap(),\n password=admin_secret.secret_value_from_json(\"password\")\n ),\n auto_minor_version_upgrade=True,\n configuration=custom_configuration\n)\n```\n\nA configuration can be associated with a specific broker also after the deployment. Then, it is required to be explicitly associated with the broker.\n\n```python\nfrom cdklabs.cdk_amazonmq import IRabbitMqBrokerConfiguration, IRabbitMqBrokerDeployment\n\n# configuration: IRabbitMqBrokerConfiguration\n# deployment: IRabbitMqBrokerDeployment\n\n\nconfiguration.associate_with(deployment)\n```\n\nThis library also allows to modify an existing configuration. Such update of a particular configuration is [creating a new configuration *revision*](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/rabbitmq-creating-applying-configurations.html#creating-new-rabbitmq-configuration-revision-console) so that a history of revisions can be viewed in the AWS Console. The new revision can be then associated with the broker so it uses it as a working configuration.\n\n```python\nfrom aws_cdk import Duration\nfrom cdklabs.cdk_amazonmq import IRabbitMqBrokerConfiguration, IRabbitMqBrokerDeployment, RabbitMqBrokerConfigurationDefinition\n\n# configuration: IRabbitMqBrokerConfiguration\n# deployment: IRabbitMqBrokerDeployment\n# new_consumer_timeout: Duration\n\n\nnew_revision = configuration.create_revision(\n description=\"We need to modify the consumer timeout\",\n definition=RabbitMqBrokerConfigurationDefinition.parameters(\n consumer_timeout=new_consumer_timeout\n )\n)\n\nnew_revision.associate_with(deployment)\n```\n\n### Monitoring RabbitMQ Brokers\n\nThis library introduces [a set of metrics](https://docs.aws.amazon.com/amazon-mq/latest/developer-guide/security-logging-monitoring-cloudwatch.html#rabbitmq-logging-monitoring) that we can use for the `IRabbitMqBrokerDeployment` monitoring. Each can be accessed as a method on the `IRabbitMqBrokerDeployment` with the convention `metric[MetricName]`. An example below shows how one can use that:\n\n```python\nfrom cdklabs.cdk_amazonmq import IRabbitMqBrokerDeployment\n\n# stack: Stack\n# deployment: IRabbitMqBrokerDeployment\n\n\nconsumer_count_metric = deployment.metric_consumer_count()\nconsumer_count_metric.create_alarm(stack, \"ConsumerCountAlarm\",\n threshold=100,\n evaluation_periods=3,\n datapoints_to_alarm=2\n)\n```\n\n### RabbitMQ Broker Integration with AWS Lambda\n\nAmazon MQ for RabbitMQ broker queues can be used as event sources for AWS Lambda functions. For authentication only the PLAIN authentication mechanism is supported. Lambda consumes messages using the AMQP 0-9-1 protocol. No other protocols are supported for consuming messages. For more details on the requirements of the integration read [the documentation](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html).\n\nThe example below presents an example of creating such an event source mapping:\n\n```python\nfrom aws_cdk.aws_lambda import IFunction\nfrom aws_cdk.aws_secretsmanager import ISecret\nfrom cdklabs.cdk_amazonmq import IRabbitMqBrokerDeployment, RabbitMqEventSource\n\n# target: IFunction\n# creds: ISecret # with username and password fields\n# broker: IRabbitMqBrokerDeployment\n# queue_name: str\n\n\ntarget.add_event_source(RabbitMqEventSource(\n broker=broker,\n credentials=creds,\n queue_name=queue_name\n))\n```\n\n***Security:*** When adding an Amazon MQ for RabbitMQ as an AWS Lambda function's event source the library updates the execution role's permissions to satisfy [Amazon MQ requirements for provisioning the event source mapping](https://docs.aws.amazon.com/lambda/latest/dg/with-mq.html#events-mq-permissions).\n\nIn the case of a private deployment the defined event source mapping will create a set of Elastic Network Interfaces (ENIs) in the subnets in which the broker deployment created communication VPC Endpoints. Thus, in order to allow the event source mapping to communicate with the broekr one needs to additionally allow inbound traffic from the ENIs. As ENIs will use the same security group that governs the access to the VPC Endpoints you can simply allow communication from the broker's security group to itself on the AMQP port as in the example below:\n\n```python\nfrom cdklabs.cdk_amazonmq import IRabbitMqBrokerDeployment\n\n# deployment: IRabbitMqBrokerDeployment\n\n\ndeployment.connections.allow_default_port_internally()\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "@cdklabs/cdk-amazonmq",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/cdklabs/cdk-amazonmq.git",
"Source": "https://github.com/cdklabs/cdk-amazonmq.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b5bdf7e42ae1fbccda6208310597c5f7581925a0369dcfd98e1112e0e02f4f7",
"md5": "25a5b0bf05dae0592d69a05e300c2a60",
"sha256": "b7ad09b8e8deca94afd63a7440dae51b9ab7ca83c3a50542a952ee7369c1e0eb"
},
"downloads": -1,
"filename": "cdklabs.cdk_amazonmq-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25a5b0bf05dae0592d69a05e300c2a60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 232989,
"upload_time": "2024-09-12T10:20:36",
"upload_time_iso_8601": "2024-09-12T10:20:36.022171Z",
"url": "https://files.pythonhosted.org/packages/2b/5b/df7e42ae1fbccda6208310597c5f7581925a0369dcfd98e1112e0e02f4f7/cdklabs.cdk_amazonmq-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f13435e64e71c59a7f7d67d17fe8dc79010bd6009558f3bd5a8afa2f93081bb3",
"md5": "64f242f808c264b85621c72042142903",
"sha256": "525deecfee0e55d446cd3b34083c297c49f9e012794ece9f4aa5c2f77cfd5222"
},
"downloads": -1,
"filename": "cdklabs_cdk_amazonmq-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "64f242f808c264b85621c72042142903",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 238882,
"upload_time": "2024-09-12T10:20:37",
"upload_time_iso_8601": "2024-09-12T10:20:37.605348Z",
"url": "https://files.pythonhosted.org/packages/f1/34/35e64e71c59a7f7d67d17fe8dc79010bd6009558f3bd5a8afa2f93081bb3/cdklabs_cdk_amazonmq-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-12 10:20:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cdklabs",
"github_project": "cdk-amazonmq",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cdklabs.cdk-amazonmq"
}
JSON
