Skip to main content

Create a RabbitMQ Broker (RC)

This is an example of how to create a RabbitMQBroker.

The RabbitMQBroker provisions an Amazon MQ for RabbitMQ broker. Security group and security group rules that allow access to the broker (AMQPS on port 5671) and to the management console (HTTPS on port 443) from pods are created automatically.

1. Create a RabbitMQBroker manifest​

Create a RabbitMQBroker manifest and deploy it to the cluster. It is a good practice to include it in the application's Helm chart.

Connection credentials for the admin user mqadmin are stored in a Kubernetes secret <.metadata.name>-credentials.

# Example RabbitMQBroker
apiVersion: mq.entigo.com/v1alpha1
kind: RabbitMQBroker
metadata:
  name: example-rabbitmq
spec:
  instanceType: mq.m7g.medium

---
# Example RabbitMQBroker with an explicit engine version and single-instance deployment
apiVersion: mq.entigo.com/v1alpha1
kind: RabbitMQBroker
metadata:
  name: example-rabbitmq
spec:
  instanceType: mq.m7g.medium
  engineVersion: '4.2'
  deploymentMode: SINGLE_INSTANCE
  publiclyAccessible: false

---
# Example RabbitMQBroker deployed as a multi-AZ cluster with a maintenance window
apiVersion: mq.entigo.com/v1alpha1
kind: RabbitMQBroker
metadata:
  name: example-rabbitmq
spec:
  instanceType: mq.m7g.large
  engineVersion: '4.2'
  deploymentMode: CLUSTER_MULTI_AZ
  autoMinorVersionUpgrade: true
  maintenanceWindowStartTime:
    dayOfWeek: MONDAY
    timeOfDay: '02:00'
    timeZone: CET

---
# Example RabbitMQBroker with a custom rabbitmq.conf (Cuttlefish) configuration
apiVersion: mq.entigo.com/v1alpha1
kind: RabbitMQBroker
metadata:
  name: example-rabbitmq
spec:
  instanceType: mq.m7g.medium
  engineVersion: '4.2'
  configuration:
    description: Custom broker configuration
    data: |
      consumer_timeout = 1800000
      channel_max = 2047

Note: Creation of the RabbitMQBroker can take more than 10 minutes.

Use kubectl watch to verify it is ready.

kubectl get rabbitmqbrokers.mq.entigo.com example-rabbitmq -w

For all the options see https://docs.entigo.com/api/RabbitMQBroker

2. Mount connection credentials to a container​

Connection credentials for the admin user mqadmin are stored in a Kubernetes secret <.metadata.name>-credentials.

The broker connection details (endpoints) written by the provider are stored in a Kubernetes secret <.metadata.name>-connection.

For more information about Secrets in Kubernetes, see Kubernetes documentation.

# Example
apiVersion: v1
kind: Pod
metadata:
  name: rabbitmq-client
spec:
  terminationGracePeriodSeconds: 1
  containers:
    - name: rabbitmq-client
      image: rabbitmq:management
      command: ['sleep', 'infinity']
      env:
        - name: RABBITMQ_USER
          valueFrom:
            secretKeyRef:
              name: example-rabbitmq-credentials
              key: username
        - name: RABBITMQ_PASSWORD
          valueFrom:
            secretKeyRef:
              name: example-rabbitmq-credentials
              key: password

3. Result​

3.1 RabbitMQBroker​

RabbitMQBroker created in Kubernetes

$ kubectl get rabbitmqbrokers.mq.entigo.com
NAME               SYNCED   READY   COMPOSITION                      AGE
example-rabbitmq   True     True    rabbitmqbrokers.mq.entigo.com    22m

3.2 Secret with connection credentials​

Kubernetes secret with the admin user credentials

$ kubectl get secret
NAME                           TYPE     DATA   AGE
example-rabbitmq-credentials   Opaque   2      22m
example-rabbitmq-connection    Opaque   3      22m

$ kubectl get secret example-rabbitmq-credentials -o yaml
apiVersion: v1
kind: Secret
metadata:
  name: example-rabbitmq-credentials
  namespace: <namespace>
type: Opaque
data:
  username: <base64-encoded-username>
  password: <base64-encoded-password>

4. Limitations​

4.1 Configuration changes​

The broker configuration (spec.configuration) has limitations that come from the Amazon MQ API:

  • A configuration cannot be removed once set. Amazon MQ does not support disassociating a configuration from a broker, only switching to a different one. The API enforces this, so a manifest that removes spec.configuration after it was set is rejected.
  • Configuration changes are applied on the next broker reboot, not immediately.
  • Changing the engine version creates a new configuration. An Amazon MQ Configuration is tied to a single engine version, so an engineVersion bump provisions a new configuration rather than editing the existing one.

4.2 Deletion​

  • Amazon MQ Configurations are not deleted. Amazon MQ does not support deleting Configuration objects through its API. Configurations created for a broker (including previous ones left behind after a configuration or engine-version switch) remain in AWS after the broker is deleted.
  • Deleting the RabbitMQBroker is destructive. The broker and all of its messages, queues and vhosts are permanently removed. There is no snapshot or restore.

4.3 User management​

The Amazon MQ API only manages the single admin user (mqadmin) for the RabbitMQ engine. Additional RabbitMQ users, vhosts and permissions are not supported through the AWS API, so there is no separate user resource (such as a RabbitMQUser).

To create additional users, the admin (mqadmin) must create them inside RabbitMQ using the management console (port 443) or the RabbitMQ management HTTP API / AMQP, authenticating with the mqadmin credentials from the <.metadata.name>-credentials secret.