This guide covers the installation of the RabbitMQ Cluster Kubernetes Operator in a Kubernetes cluster.
The Operator requires
To install the Operator, run the following command:
kubectl apply -f "https://github.com/rabbitmq/cluster-operator/releases/latest/download/cluster-operator.yml" # namespace/rabbitmq-system created # customresourcedefinition.apiextensions.k8s.io/rabbitmqclusters.rabbitmq.com created # serviceaccount/rabbitmq-cluster-operator created # role.rbac.authorization.k8s.io/rabbitmq-cluster-leader-election-role created # clusterrole.rbac.authorization.k8s.io/rabbitmq-cluster-operator-role created # rolebinding.rbac.authorization.k8s.io/rabbitmq-cluster-leader-election-rolebinding created # clusterrolebinding.rbac.authorization.k8s.io/rabbitmq-cluster-operator-rolebinding created # deployment.apps/rabbitmq-cluster-operator created
At this point, the RabbitMQ Cluster Kubernetes Operator is successfully installed. Once the RabbitMQ Cluster Kubernetes Operator pod is running, head over to Using Kubernetes RabbitMQ Cluster Kubernetes Operator for instructions on how to deploy RabbitMQ using a Kubernetes Custom Resource.
If you want to install a specific version of the Operator, you will have to obtain the manifest link from the Operator Releases. Please note that releases prior to 0.46.0 do not have this manifest. We strongly recommend to install versions 0.46.0+
If you want to relocate the Operator image to a custom location, the section Relocate the Image has instructions to relocate the Operator image to a private registry.
The kubectl rabbitmq plugin provides commands for managing RabbitMQ clusters. The plugin can be installed using krew:
kubectl krew install rabbitmq
To get the list of available commands, use:
kubectl rabbitmq help # USAGE: # Install RabbitMQ Cluster Operator (optionally provide image to use a relocated image or a specific version) # kubectl rabbitmq install-cluster-operator [IMAGE] # [...] kubectl rabbitmq install-cluster-operator # namespace/rabbitmq-system created # customresourcedefinition.apiextensions.k8s.io/rabbitmqclusters.rabbitmq.com created # serviceaccount/rabbitmq-cluster-operator created # role.rbac.authorization.k8s.io/rabbitmq-cluster-leader-election-role created # clusterrole.rbac.authorization.k8s.io/rabbitmq-cluster-operator-role created # rolebinding.rbac.authorization.k8s.io/rabbitmq-cluster-leader-election-rolebinding created # clusterrolebinding.rbac.authorization.k8s.io/rabbitmq-cluster-operator-rolebinding created # deployment.apps/rabbitmq-cluster-operator created
To install the Operator using Bitnami Helm chart, run the following command:
helm repo add bitnami https://charts.bitnami.com/bitnami helm install my-release bitnami/rabbitmq-cluster-operator
The last command deploys the RabbitMQ Cluster Kubernetes Operator on the Kubernetes cluster in the default configuration. The Parameters section lists the parameters that can be configured during installation.
The Operator's Helm chart requires
If you can't pull images from Docker Hub directly to your Kubernetes cluster, you need to relocate the images to your private registry first. The exact steps depend on your environment but will likely look like this:
docker pull rabbitmqoperator/cluster-operator:{some-version} docker tag rabbitmqoperator/cluster-operator:{some-version} {someregistry}/cluster-operator:{some-version} docker push {someregistry}/cluster-operator:{some-version}
The value of {someregistry} should be the address of an OCI compatible registry. The value of {some-version} is a version number of the Cluster Operator.
If you require authentication to pull images from your private image registry, you must Configure Kubernetes Cluster Access to Private Images.
Download the manifest from the release you are relocating and edit the section in Deployment image. You can locate this section by grep'ing the string image:
grep -C3 image: releases/cluster-operator.yml # [...] # -- # valueFrom: # fieldRef: # fieldPath: metadata.namespace # image: rabbitmqoperator/cluster-operator:0.49.0 # name: operator # resources: # limits:
If you relocated the image to a private registry and your registry requires authentication, you need to follow these steps to allow Kubernetes to pull the image.
First, create the Service Account that the Operator will use to run and to pull images:
apiVersion: v1 kind: ServiceAccount metadata: name: rabbitmq-cluster-operator namespace: rabbitmq-system
Second, create a Secret with the credentials to pull from the private registry:
kubectl -n rabbitmq-system create secret \ docker-registry rabbitmq-cluster-registry-access \ --docker-server=DOCKER-SERVER \ --docker-username=DOCKER-USERNAME \ --docker-password=DOCKER-PASSWORD
Where:
For example:
kubectl -n rabbitmq-system create secret \ docker-registry rabbitmq-cluster-registry-access \ --docker-server=docker.io/my-registry \ --docker-username=my-username \ --docker-password=example-password1
Now update the Operator Service Account by running:
kubectl -n rabbitmq-system patch serviceaccount \ rabbitmq-cluster-operator -p '{"imagePullSecrets": [{"name": "rabbitmq-cluster-registry-access"}]}'
Please note that the name of the Operator Service Account is not configurable and it must be rabbitmq-cluster-operator.
You will need to modify the configuration of the operator to use the relocated images by default for new RabbitmqCluster instances. T set the values of DEFAULT_RABBITMQ_IMAGE, DEFAULT_USER_UPDATER_IMAGE and DEFAULT_IMAGE_PULL_SECRETS at Operator deployment time, see Configuring Defaults for RabbitMQ Cluster Operator.
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.
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!