Skip to content

Getting Started with Message Queues

This guide will walk you through the process of configuring your managed RabbitMQ cluster. Following the platform's GitOps approach, you will define your messaging topology—users, permissions, queues, and more—as declarative Kubernetes resources.

The Service Model

Our Message Queues service uses the official RabbitMQ Cluster Operator. This creates a shared responsibility model:

  • We Manage the Cluster: We provision and manage the core RabbitmqCluster resource for you. This includes handling high availability, upgrades, and the underlying infrastructure.
  • You Manage the Topology: You have full control over your application's messaging topology. You define all the necessary components as custom resources in your GitOps repository.

Prerequisites

Before you begin, you need a managed RabbitmqCluster instance. Please contact us to have one provisioned in your namespace. We will provide you with the name of the RabbitmqCluster resource you should reference in your topology definitions.

Step 1: Create a User and Credentials

The first step is to create a user for your application. You do this by creating a User resource. The RabbitMQ Operator will automatically generate a corresponding Kubernetes Secret containing the user's password.

Create the following manifest:

apiVersion: rabbitmq.com/v1beta1
kind: User
metadata:
  # This is the name of the Kubernetes resource
  name: my-app-user
  # This should be the namespace where your RabbitmqCluster is running
  namespace: your-application-namespace
spec:
  rabbitmqClusterReference:
    # The name of the cluster we provided to you
    name: my-rabbitmq-cluster
  # The operator will create a Secret with this name
  # containing the username and a generated password.
  importCredentialsSecret:
    name: my-app-credentials

Step 2: Create a Virtual Host (Vhost)

A virtual host provides a way to segregate applications using the same RabbitMQ instance. It's a namespace for your queues and exchanges.

apiVersion: rabbitmq.com/v1beta1
kind: Vhost
metadata:
  name: my-app-vhost
  namespace: your-application-namespace
spec:
  rabbitmqClusterReference:
    name: my-rabbitmq-cluster

Step 3: Grant Permissions

Now, grant your new user permissions to access the virtual host by creating a Permission resource.

apiVersion: rabbitmq.com/v1beta1
kind: Permission
metadata:
  name: my-app-user-permissions
  namespace: your-application-namespace
spec:
  vhost: my-app-vhost       # Grant permission to this vhost
  userReference:
    name: my-app-user       # For this user
  permissions:
    write: ".*"             # Allow writing to any resource
    configure: ".*"         # Allow configuring any resource
    read: ".*"              # Allow reading from any resource
  rabbitmqClusterReference:
    name: my-rabbitmq-cluster

Step 4: Define a Queue

With the user and permissions in place, you can now define your messaging topology. Let's create a durable queue for processing background tasks.

apiVersion: rabbitmq.com/v1beta1
kind: Queue
metadata:
  name: my-app-task-queue
  namespace: your-application-namespace
spec:
  name: tasks.work   # The actual name of the queue inside RabbitMQ
  vhost: my-app-vhost
  durable: true       # Ensures the queue survives a broker restart
  autoDelete: false
  rabbitmqClusterReference:
    name: my-rabbitmq-cluster

Step 5: Connect Your Application

Finally, you can configure your application's Deployment to connect to RabbitMQ. Your application should get its connection details from environment variables, which are populated from the Secret you created in Step 1.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-worker-app
  namespace: your-application-namespace
spec:
  # ... other deployment specs
  template:
    # ... other pod specs
    spec:
      containers:
      - name: worker-container
        image: your-image/worker
        env:
        # The service DNS name follows this pattern:
        # <cluster-name>.<namespace>.svc.cluster.local
        - name: RABBITMQ_HOST
          value: "my-rabbitmq-cluster.your-application-namespace.svc.cluster.local"
        - name: RABBITMQ_VHOST
          value: "my-app-vhost"
        - name: RABBITMQ_USER
          valueFrom:
            secretKeyRef:
              name: my-app-credentials # The Secret from Step 1
              key: username
        - name: RABBITMQ_PASSWORD
          valueFrom:
            secretKeyRef:
              name: my-app-credentials # The Secret from Step 1
              key: password

Once you commit and push these resources to your GitOps repository, the RabbitMQ Operator will create the user, vhost, permissions, and queue. Your application will then be able to connect and start sending or receiving messages.

Next Steps

You have now configured a basic messaging setup. The RabbitMQ Operator can manage many other topology objects, such as Exchange, Binding, and Policy.