Overview

This guide covers installation of VMware Tanzu RabbitMQ to Kubernetes using the Carvel toolchain.

Prerequisite

Before you install, you will require the following:

A running Kubernetes cluster, with the following installed on the cluster:
The Carvel toolchain installed on your system
- This can be installed by either visiting the Carvel website or installing the following components from TanzuNet:

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:

Sign into the VMware Tanzu Network and search for Cluster Essentials for VMware Tanzu.
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.
Select Agree.
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.

Installation

Installing VMware Tanzu RabbitMQ for Kubernetes

Setup

N.B.: If you are planning on deploying 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 below instructions, you should use the URL of your registry in place of any 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:

Create a Secret object on your cluster with type: kubernetes.io/dockerconfigjson if it is not already created. 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.

The following is an example of the yaml manifest, which you can use to create the Secret object. 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": ""
        }
      }
    }

Deploy the Secret object by running the following command. Replace <secret_filename> with the name of the Secret object yaml file which you created above.

kubectl apply -f <secret_filename>.yml

Alternatively, you can create and deploy the Secret object using kubectl instead.

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

Create a SecretExport object on your cluster if it is not already created. The SecretExport object provides the 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 the SecretExport object.
```
---
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
```
Deploy the SecretExport object by running the following command. Replace <secretexport_filename> with the name of the SecretExport object yaml file which you created above.
```
kubectl apply -f <secretexport_filename>.yml
```

Install the PackageRepository

To do this, ensure you have a Secret of type kubernetes.io/dockerconfigjson containing authenticated credentials for the registry containing the Tanzu RabbitMQ package. We strongly recommend that these credentials provide only read-only access to the registry. You must then create a SecretExport object on your cluster to provide this imagePullSecret to any namespace installing Tanzu RabbitMQ.

Below is an example of a manifest to create both the secret and the SecretExport object.

---
apiVersion: v1
kind: Secret
metadata:
  name: reg-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: reg-creds        # must match source secret name
  namespace: secrets-ns  # must match source secret namespace
spec:
  toNamespaces:
  - "*"  # star means export is available for all namespaces

If preferred, you can create the secret through kubectl instead, though you will still need to create the SecretExport afterwards:

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

Install the PackageRepository

Installing the Tanzu RabbitMQ PackageRepository will provide the versioned Packages of Tanzu RabbitMQ to your cluster. Do this by creating a PackageRepository object:

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:${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

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

After this is installed, verify that the expected packages are visible to your client:

$ kubectl get packages
NAME                              PACKAGEMETADATA NAME        VERSION   AGE
rabbitmq.tanzu.vmware.com.1.2.0   rabbitmq.tanzu.vmware.com   1.2.0     7s

Install the Package

You can now install the Package in order to install the Tanzu RabbitMQ Operators to your cluster. This is done by creating a PackageInstall object. Note that you will need to provide the name of a service account to install the package; this service account will be used to create cluster-scope objects such as CustomResourceDefinitions, and so must have permissions to create objects on any namespace. For a complete list of permissions necessary to install Tanzu RabbitMQ, see Service Account Permissions.

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

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

By default, this installs the Operators to the "rabbitmq-system" namespace. If you wish to override this, you can do so by providing the desired namespace as a value in the PackageInstall via a secret:

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

This will install the operators in the provided namespace, however the operators will watch all namespaces for RabbitmqCluster objects to reconcile.

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.

Deploying 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.