VMWare Tanzu RabbitMQ for Kubernetes Installation

The following information provides all the details to install VMware Tanzu RabbitMQ for Kubernetes using the Carvel toolchain.

Follow these steps to complete the installation:

At this point, your Tanzu RabbitMQ for Kubernetes installation should be complete, if you want, you can now complete the following post installation tasks:

Accept the End User License Agreements

Before downloading and installing Tanzu RabbitMQ for Kubernetes packages, you must accept the End User License Agreements (EULAs) for the following packages:

To accept the EULAs, complete the following steps:

  1. Sign into the VMware Tanzu Network and search for Cluster Essentials for VMware Tanzu.
  2. Select the Click here to sign the EULA link in the yellow warning box under the RELEASE: drop-down menu. If the yellow warning box is not visible, the EULA is previously accepted.
  3. Select Agree.
  4. Next, accept the EULA for VMWare Tanzu RabbitMQ. You are already signed, go back and search for VMWare Tanzu RabbitMQ, and repeat steps 2 and 3.

Prerequisites

Before you install VMware Tanzu RabbitMQ, ensure you have:

  1. Connected to a running Kubernetes cluster.
  2. kubectl is installed. You can get kubectl for your system by downloading it here.
  3. The Tanzu Cluster Essentials package is installed on your Kubernetes cluster. Tanzu Cluster Essentials is required because it installs the kapp-controller and secretgen-controller controllers on your Kubernetes cluster. To download and install Tanzu Cluster Essentials, go to Cluster Essentials for VMware Tanzu Documentation, select the documentation set for the specific version of Tanzu Cluster Essentials that you are installing and complete the installation steps. After installation, you can verify that Tanzu Cluster Essentials is installed correctly by checking the relevant pods are running. Run this command:
    $ kubectl get all -n kapp-controller && kubectl get all -n secretgen-controller
    
    You should see that the STATUS is running for the kapp-controller and secretgen-controller pods.

Prepare for the Installation

Important: If you plan to deploy VMware Tanzu RabbitMQ for Kubernetes to a Kubernetes cluster on an airgapped network, you must first follow the instructions on the kapp-controller docs to relocate the package registry.tanzu.vmware.com/p-rabbitmq-for-kubernetes/tanzu-rabbitmq-package-repo to your internal registry. In the following instructions, you should use the URL of your registry anywhere there are references to registry.tanzu.vmware.com.

Provide imagePullSecrets

You must export an imagePullSecret using secretgen-controller so that the components of the package can pull from the registry containing the Tanzu RabbitMQ package.

To do this, complete the following steps:

  1. Ensure you have a Secret object created on your cluster with this type: kubernetes.io/dockerconfigjson. This secret type includes the authenticated credentials for the registry, which contains the Tanzu RabbitMQ package. It is highly recommended that these credentials provide only read-only access to the registry.

  2. You must then create a SecretExport object on your cluster to provide this imagePullSecret to any namespace where Tanzu RabbitMQ is being installed.

    The following is an example of the yaml manifest, which you can use to create both the Secret and the SecretExport objects together. Remember, the Secret type must be set to kubernetes.io/dockerconfigjson.

    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: tanzu-rabbitmq-registry-creds  # could be any name
      namespace: secrets-ns                # could be any namespace
    type: kubernetes.io/dockerconfigjson   # needs to be this type
    stringData:
      .dockerconfigjson: |
        {
          "auths": {
            "registry.tanzu.vmware.com": { # update to your own registry url if the package is placed in another location
              "username": "user...",
              "password": "password...",
              "auth": ""
            }
          }
        }
    
    ---
    apiVersion: secretgen.carvel.dev/v1alpha1
    kind: SecretExport
    metadata:
      name: tanzu-rabbitmq-registry-creds    # must match source secret name
      namespace: secrets-ns                  # must match source secret namespace
    spec:
      toNamespaces:
      - "*"  # star means export is available for all namespaces
    
  3. Deploy both the Secret and the SecretExport objects by running the following command. Replace <secret_secretobjects_filename> with the name of the yaml file that you used when you created these objects.

    kubectl apply -f <secret_secretobjects_filename>.yml -y
    

    Alternatively, you can create the Secret object using kubectl instead. If you use this method, you must create the SecretExport object seperately afterwards and then deploy these objects. Run the following command to create the Secret object:

    kubectl create secret docker-registry tanzu-rabbitmq-registry-creds -secrets-ns --docker-server "registry.tanzu.vmware.com" --docker-username "user." --docker-password "password..."
    

Install the PackageRepository

You must install the Tanzu RabbitMQ PackageRepository to provide the versioned Tanzu RabbitMQ packages to your cluster. To do this, complete the following steps:

  1. Create a PackageRepository object yaml file with the following contents. Replace BUNDLE_VERSION below with the Tanzu RabbitMQ release version.

    apiVersion: packaging.carvel.dev/v1alpha1
    kind: PackageRepository
    metadata:
      name: tanzu-rabbitmq-repo
    spec:
      fetch:
        imgpkgBundle:
          image: registry.tanzu.vmware.com/p-rabbitmq-for-kubernetes/tanzu-rabbitmq-package-repo:${BUNDLE_VERSION} # Replace BUNDLE_VERSION with the release version and replace registry.tanzu.vmware.com with your own registry url if the package is placed in another location
    
  2. Deploy the PackageRepository object by running the following command. Replace <PackageRepository_object_filename> with the name of the PackageRepository yaml file that you used when you created the object.

    kapp deploy -a tanzu-rabbitmq-repo -f <PackageRepository_object_filename>.yml -y
    
  3. After the PackageRepository object is deployed, verify that the expected packages are visible to your client by running the following command:

    $ kubectl get packages
    NAME                                               PACKAGEMETADATA NAME                     VERSION     AGE
    cert-manager.rabbitmq.tanzu.vmware.com.1.5.3+rmq   cert-manager.rabbitmq.tanzu.vmware.com   1.5.3+rmq   42s
    rabbitmq.tanzu.vmware.com.1.2.0                    rabbitmq.tanzu.vmware.com                1.2.0       42s
    rabbitmq.tanzu.vmware.com.1.2.1                    rabbitmq.tanzu.vmware.com                1.2.1       42s
    rabbitmq.tanzu.vmware.com.1.2.2                    rabbitmq.tanzu.vmware.com                1.2.2       42s
    rabbitmq.tanzu.vmware.com.1.3.0                    rabbitmq.tanzu.vmware.com                1.3.0       42s
    

Create a ServiceAccount

You need a ServiceAccount during the Tanzu RabbitMQ installation to create the resources provided by Tanzu RabbitMQ. This service account is used to create cluster-scope objects such as CustomResourceDefinitions so it must have the correct permissions to create objects on any namespace.

For a list of the permissions that are required by this service account and the yaml file syntax that you need to create the service account, see Service Account Permissions.

Take note of the name of this service account, you need it in later steps of the installation.

Install cert-manager

cert-manager v1.5.0 or higher is required for Tanzu RabbitMQ for Kubernetes. It must be installed on your cluster now before you can install the Tanzu RabbitMQ Package later.

Important: If you have cert-manager previously installed on your Kubernetes cluster, you can skip this section. To check whether cert-manager is installed, search for installed cert-manager api-resources. For example:

$ kubectl api-resources | grep 'cert-manager'
challenges                                     acme.cert-manager.io/v1                  true         Challenge
orders                                         acme.cert-manager.io/v1                  true         Order
certificaterequests               cr,crs       cert-manager.io/v1                       true         CertificateRequest
certificates                      cert,certs   cert-manager.io/v1                       true         Certificate
clusterissuers                                 cert-manager.io/v1                       false        ClusterIssuer
issuers                                        cert-manager.io/v1                       true         Issuer

Install cert-manager using one of the options below depending on the type of network your cluster is running in.

Option 1: Installing cert-manager from GitHub

If your cluster has access to the public internet, install cert-manager from its GitHub release by running the following command:

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

Option 2: Installing cert-manager from the Internal PackageRepository

cert-manager is included as an ancillary package in the Tanzu RabbitMQ for Kubernetes PackageRepository, therefore it is available even on airgapped networks. To install cert-manager from this PackageRepository within your network, complete the following steps:

  1. Create a PackageInstall object for cert-manager with the following yaml manifest. Replace ${SERVICE_ACCOUNT} with the name of the ServiceAccount that you created previously in Create a ServiceAccount.

    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: cert-manager-overlay
    stringData:
      add-placeholder-secret.yml: |
        apiVersion: v1
        kind: Secret
        metadata:
          name: tanzu-rabbitmq-registry-creds
          annotations:
            secretgen.carvel.dev/image-pull-secret: ""
        type: kubernetes.io/dockerconfigjson
        data:
          .dockerconfigjson: e30K
      add-placeholder-namespace.yml: |
        #@ load("@ytt:data", "data")
        #@ load("@ytt:overlay", "overlay")
        #@overlay/match by=overlay.subset({"kind":"Secret","metadata": {"name":"tanzu-rabbitmq-registry-creds"}}),expects="1+"
        ---
        metadata:
          #@overlay/match missing_ok=True
          namespace: #@ data.values.namespace
      add-image-pull-secret.yml: |
        #@ load("@ytt:overlay", "overlay")
        #@overlay/match by=overlay.subset({"kind":"Deployment"}),expects="1+"
        ---
        spec:
          template:
            spec:
              #@overlay/match missing_ok=True
              imagePullSecrets:
                - name: tanzu-rabbitmq-registry-creds
    ---
    apiVersion: packaging.carvel.dev/v1alpha1
    kind: PackageInstall
    metadata:
      name: cert-manager-rabbitmq
      annotations:
        ext.packaging.carvel.dev/ytt-paths-from-secret-name.0: cert-manager-overlay
    spec:
      serviceAccountName: ${SERVICE_ACCOUNT} # Replace with service account name
      packageRef:
        refName: cert-manager.rabbitmq.tanzu.vmware.com
        versionSelection:
          constraints: 1.5.3+rmq
    
  2. Deploy cert-manager by running the following command. Replace <certmanagerpackageinstall_filename> with the name of the PackageInstall object for cert-manager yaml file that you used when you created the object.

    kapp deploy -a cert-manager-rabbitmq -f <certmanagerpackageinstall_filename>.yml -y
    

Install the Tanzu RabbitMQ Package

You can now install the Tanzu RabbitMQ package to install the Tanzu RabbitMQ Cluster Operator, Message Topology Operator, and Standby Replication Operator on your cluster. To do this, complete the following steps:

  1. Create the PackageInstall object using the following manifest. In your PackageInstall object yaml file, replace <SERVICE_ACCOUNT> with the name of your ServiceAccount and <BUNDLE_VERSION> with the version of Tanzu RabbitMQ you are installing.

    apiVersion: packaging.carvel.dev/v1alpha1
    kind: PackageInstall
    metadata:
      name: tanzu-rabbitmq
    spec:
      serviceAccountName: ${SERVICE_ACCOUNT} # Replace with service account name
      packageRef:
        refName: rabbitmq.tanzu.vmware.com
        versionSelection:
          constraints: ${BUNDLE_VERSION} # Replace with release version
    
  2. Deploy the PackageInstall object by running the following command. Replace <PackageInstall_object_filename> with the name of the PackageInstall yaml file that you used when you created the object.

    kapp deploy -a tanzu-rabbitmq -f <PackageInstall_object_filename>.yml -y
    

    By default, the Operators are installed in the "rabbitmq-system" namespace. If you want to change this, enter your own namespace name as a value in the PackageInstall via a secret as outlined below. This will install the operators in the provided namespace, however the operators will watch all namespaces forRabbitmqCluster objects to reconcile.

    apiVersion: packaging.carvel.dev/v1alpha1
    kind: PackageInstall
    metadata:
      name: tanzu-rabbitmq
    spec:
      serviceAccountName: ${SERVICE_ACCOUNT} # Replace with service account name
      packageRef:
        refName: rabbitmq.tanzu.vmware.com
        versionSelection:
          constraints: ${BUNDLE_VERSION} # Replace with release version
      values:
      - secretRef:
          name: tanzu-rabbitmq-values
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: tanzu-rabbitmq-values
    stringData:
      values.yml: |
        ---
        namespace: ${NAMESPACE} # Replace with the target install namespace
    

Observability

At this point you may choose to set up observability on your cluster. To do so, you can follow the instructions in the Cluster Operator repo or the RabbitMQ website.

Deploy your RabbitmqClusters and Topology objects

Once this installation is complete, you can now create your RabbitMQ objects with the Carvel tooling. Since the RabbitMQ container image will also require authentication, you will need to provide the same imagePullSecrets as earlier.

If creating RabbitmqClusters in the same namespace as the operators were installed, simply add the existing secret:

apiVersion: rabbitmq.com/v1beta1
kind: RabbitmqCluster
metadata:
  name: my-tanzu-rabbit
  namespace: rabbitmq-system
spec:
  replicas: 1
  imagePullSecrets:
  - name: tanzu-rabbitmq-registry-creds

Important: If you are creating clusters in a different namespace, you must create a placeholder Secret, and direct the RabbitmqCluster to use it:

---
apiVersion: v1
kind: Secret
metadata:
  name: tanzu-rabbitmq-registry-creds
  namespace: my-namespace
  annotations:
    secretgen.carvel.dev/image-pull-secret: ""
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: e30K
---
apiVersion: rabbitmq.com/v1beta1
kind: RabbitmqCluster
metadata:
  name: my-tanzu-rabbit
  namespace: my-namespace
spec:
  replicas: 1
  imagePullSecrets:
  - name: tanzu-rabbitmq-registry-creds

Since we earlier created a SecretExport object, this placeholder secret will be autopopulated by secretgen-controller, and the RabbitmqCluster will be able to authenticate to the registry using this Secret.

Use TLS with Operators

If the RabbitmqClusters that are managed by the Messaging Topology and Standby Replication Operators are configured to serve management over HTTPS with self signed certificates, then these operators must trust the Certificate Authority (CA) that signed the TLS certificates, which are being used by the RabbitmqClusters.

One or more trusted certificates must be mounted as volumes to the trust store of the Topology Operator Pod in the /etc/ssl/certs/ directory.

To set up the operators to trust the Certificate Authority (CA) that signed the TLS certificates which are being used by the RabbitmqClusters, complete the following steps:

  1. Create a Kubernetes Secret containing the certificate of the CA that signed the RabbitMQ server's certificate:

    kubectl -n rabbitmq-system create secret generic rabbitmq-ca --from-file=ca.crt=$CA_PATH
    
  2. Apply a PackageInstall extension that mounts the Secret to both the Messaging Topology and Standby Replication Operators in the correct path. You can refer to the following yaml as an example.

    ---
    apiVersion: v1
    kind: Secret
    metadata:
      name: resource-overlay
      namespace: # same namespace as the tanzu rabbitmq PackageInstall
    stringData:
      overlay.yaml: |
        #@ load("@ytt:overlay", "overlay")
        #@overlay/match by=overlay.subset({"kind":"Deployment", "metadata": {"name": "messaging-topology-operator"}}),expects=1
        ---
        spec:
          template:
            spec:
              containers:
                #@overlay/match by=overlay.subset({"name": "manager"}),expects=1
                - volumeMounts:
                  #@overlay/append
                  - mountPath: /etc/ssl/certs/rabbitmq-ca.crt
                    name: rabbitmq-ca
                    subPath: ca.crt
              volumes:
                #@overlay/append
                - name: rabbitmq-ca
                  secret:
                    defaultMode: 420
                    secretName: rabbitmq-ca
        #@overlay/match by=overlay.subset({"kind":"Deployment", "metadata": {"name": "standby-replication-operator"}}),expects=1
        ---
        spec:
          template:
            spec:
              containers:
                #@overlay/match by=overlay.subset({"name": "manager"}),expects=1
                - volumeMounts:
                  #@overlay/append
                  - mountPath: /etc/ssl/certs/rabbitmq-ca.crt
                    name: rabbitmq-ca
                    subPath: ca.crt
              volumes:
                #@overlay/append
                - name: rabbitmq-ca
                  secret:
                    defaultMode: 420
                    secretName: rabbitmq-ca
    

Apply the above PackageInstall extension by:

kubectl apply -f resource-overlay.yaml
  1. Update the annotations of the PackageInstall that you used to install the operators to reference the resource-overlay secret. You can refer to the following yaml as an example.

    apiVersion: packaging.carvel.dev/v1alpha1
    kind: PackageInstall
    metadata:
      name: tanzu-rabbitmq
      annotations:
        ext.packaging.carvel.dev/ytt-paths-from-secret-name.0: resource-overlay
    spec:
      serviceAccountName: tanzu
      packageRef:
        refName: rabbitmq.tanzu.vmware.com
        versionSelection:
          constraints: 1.2.1
    

Update the PackageInstall by:

kapp deploy -a tanzu-rabbitmq-repo -f repo.yml -y

The operators are now setup to trust the Certificate Authority (CA) that signed the TLS certificates which are being used by the RabbitmqClusters.

check-circle-line exclamation-circle-line close-line
Scroll to top icon