Menu

Installing RabbitMQ Messaging Topology Operator

Overview

This guide covers the installation of the RabbitMQ Messaging Topology Operator in a Kubernetes cluster.

Compatibility

The Operator requires

  • Kubernetes 1.19 or above
  • RabbitMQ Cluster Operator 1.7.0+ (if not, RabbitMQ Messaging Topology Operator will fail to start)

Installation

There are two options for installing the Operator:

  1. Install with cert-manager
  2. Install generated certificates

Install with cert-manager

First, install cert-manager version 1.2.0+ on your cluster. For example, for version 1.3.1, run:

kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.3.1/cert-manager.yaml

Then, to install the Operator, run the following command:

kubectl apply -f https://github.com/rabbitmq/messaging-topology-operator/releases/latest/download/messaging-topology-operator-with-certmanager.yaml

Install with Generated Certificates

Without cert-manager installed, you will need to generate certificates used by admission webhooks yourself and include them in the operator and webhooks manifests.

Download the latest release manifest https://github.com/rabbitmq/messaging-topology-operator/releases/latest/download/messaging-topology-operator.yaml.

The Messaging Topology Operator has multiple admission webhooks. Their endpoints are TLS-enabled and require a webhook certificate that must be used in multiple places in the downloaded release manifest.

Sections below explain the steps involved into installing certificates for webhook admission.

Generate Key/Certificate Pair

First, generate one or more key/certificate pairs for webhook admission. These certificates must be valid for webhook-service.rabbitmq-system.svc.

Create a K8S Secret

Next, create a Kubernetes secret object with the name of webhook-server-cert in the rabbitmq-system namespace. The secret object must contain the following keys:

  • ca.crt (CA certificate)
  • tls.crt (leaf/webhook certificate)
  • tls.key (leaf/webhook private key)

The secret will be mounted to the Operator container, where all webhooks will run from.

For example:

apiVersion: v1
kind: Secret
type: kubernetes.io/tls
metadata:
  name: webhook-server-cert
  namespace: rabbitmq-system
data:
  ca.crt: # ca cert that can be used to validate the webhook's server certificate
  tls.crt: # generated certificate
  tls.key: # generated private key

Use Generated Certificates in Release Manifest

Finally, add webhook's CA certificate to the release manifest, messaging-topology-operator.yaml. There are multiple admission webhooks, one for each CRD type.

Look for keyword clientConfig in the manifest, and paste the webhook CA certificate under clientConfig.caBundle. Because there are several webhooks, perform this action in several places.

The example below shows how to add a CA certificate to the queues.rabbitmq.com validating webhook:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  annotations:
  name: validating-webhook-configuration
webhooks:
- admissionReviewVersions:
  - v1
  clientConfig:
    caBundle: # generated ca certificate goes in here
    service:
      name: webhook-service
      namespace: rabbitmq-system
      path: /validate-rabbitmq-com-v1beta1-queue
  failurePolicy: Fail
  name: vqueue.kb.io
  rules:
  - apiGroups:
    - rabbitmq.com
...

Then, to install the Operator, run the following command:

kubectl apply -f messaging-topology-operator.yaml

At this point, the RabbitMQ Messaging Topology Operator is successfully installed.

Using a non-default Kubernetes internal domain

By default, Kubernetes internal domain name is .cluster.local. This can be configured in kubeadm to be something else e.g. my.cluster.domain. In such cases, the Messaging Topology Operator can append the domain name to the connection strings it uses to interact with RabbitMQ.

To configure the Messaging Topology Operator to append the domain name in the connection string, set the environment variable MESSAGING_DOMAIN_NAME to your domain name e.g. ".my.cluster.domain".

To set this environment variable:

  • Download the installation manifest from the releases
  • Open the manifest and search for the Deployment with name messaging-topology-operator
  • Add a new element to the env list, with name MESSAGING_DOMAIN_NAME and value your domain name

The manifest related to the Deployment should look similar to this:

apiVersion: apps/v1
kind: Deployment
metadata:
  [...]
  name: messaging-topology-operator
  namespace: rabbitmq-system
spec:
  template:
    [...]
    spec:
      containers:
      - command:
        - /manager
        env:
        - name: OPERATOR_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: MESSAGING_DOMAIN_NAME
          value: "my.cluster.domain"

Apply the edited manifest. Once the Pod has applied the changes, subsequent HTTP API requests to RabbitMQ will append the domain name to the connection string.

Older Operator Versions

To install a specific version of the Operator, obtain the manifest link from the Operator Releases. Using the latest version is strongly recommended.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!