Using the RabbitMQ Messaging Topology Kubernetes Operator
Use this information to learn how to deploy Custom Resource objects that will be managed by the Messaging Topology Operator.
How to Use the RabbitMQ Message Topology Operator
If RabbitMQ Messaging Topology Operator is not installed, see the quickstart information to deploy it.
This information includes the following sections:
- Cluster Operator Requirements
- Scope across multiple namespaces
- Non Operator managed RabbitMQ
- Custom Connection URI
- Queues and policies
- Users and user permissions
- Exchanges and bindings
- Virtual hosts
- Federation
- Shovel
- Update a resource
- Delete a resource
- Limitations
- TLS
- Use HashiCorp Vault
- Configure Log Level for the Operator
- Time based Reconciliation
Note: Additional information about using the operator on Openshift can be found at Using the RabbitMQ Kubernetes Operators on Openshift.
RabbitMQ Cluster Operator Requirements
- Messaging Topology Operator can be used with RabbitMQ clusters deployed using the Kubernetes Cluster Operator.
The minimal version required for Cluster Operator is
1.7.0
. - Messaging Topology Operator custom resources can only be created in the same namespace as the RabbitMQ cluster is deployed. For a RabbitmqCluster deployed in namespace
"my-test-namespace", all Messaging Topology custom resources for this RabbitMQ cluster, such as
queues.rabbitmq.com
andusers.rabbitmq.com
, can only be created in namespace "my-test-namespace".
Scope Across Multiple Namespaces
Messaging Topology Operator can reconcile its objects in any namespace. However, by default, it will limit its interactions to RabbitmqCluster
objects within
same namespace as the topology object, for example Queue
. In other words, Messaging Topology Operator will reconcile a Queue
object, in namespace default
,
only if RabbitmqCluster
object is also in namespace default
.
This is the default behaviour, and it can be customised to allow a specific list of namespaces to allow reconciliation from. To create a list of
allowed namespaces, the RabbitmqCluster
object has to be annotated with key rabbitmq.com/topology-allowed-namespaces
, and value a comma-separated list,
without spaces, of namespace names; for example default,ns1,my-namespace
. The value asterisk *
can be used to allow all namespaces.
Any topology object can be declared to target a RabbitmqCluster
in a different namespace using .spec.rabbitmqClusterReference.namespace
. Topology
objects within the same namespace as RabbitmqCluster
are always allowed.
The following YAML declares a RabbitmqCluster
object that allows topology objects from namespace my-app
:
apiVersion: rabbitmq.com/v1beta1
kind: RabbitmqCluster
metadata:
name: example-rabbit
namespace: rabbitmq-service
annotations:
rabbitmq.com/topology-allowed-namespaces: "my-app"
spec:
replicas: 1
Note that the above YAML specifies namespace rabbitmq-service
. Then the following YAML will target the above RabbitMQ, from namespace my-app
.
apiVersion: rabbitmq.com/v1beta1
kind: Queue
metadata:
name: test # name of this custom resource; does not have to the same as the actual queue name
namespace: my-app
spec:
name: test-queue # name of the queue
rabbitmqClusterReference:
name: example-rabbit
namespace: rabbitmq-service
Important Information about Forbidden Cross-Namespace Objects
If topology objects, for example Queue
, target a RabbitmqCluster
, and such RabbitmqCluster
do not allow requests from the topology object's
namespace, a status condition is created with an error message,
and the object is not reconciled, until it is updated.
For example, RabbitmqCluster
in namespace ns1
allows topologies from my-app
, and topology object Queue
in namespace not-allowed
targets said
RabbitmqCluster
, Messaging Topology Operator will log an error message, update a status condition in the Queue
object, and give up reconciling the
Queue
object. If the RabbitmqCluster
object is updated to allow topology objects from namespace not-allowed
, the Queue
object must be manually
updated to trigger a reconciliation; for example, by adding a label to the Queue
object.
Non Operator Managed RabbitMQ
- For any RabbitMQ that's not deployed by Cluster Operator, a connection secret can be provided to create RabbitMQ topology objects.
- This feature is released since Messaging Topology Operator
1.4.0
. - The following manifest creates a queue and uses credentials in kubernetes secret
my-rabbit-creds
to connect to the RabbitMQ server:
---
apiVersion: v1
kind: Secret
metadata:
name: my-rabbit-creds
type: Opaque
stringData:
username: a-user # has to be an existing user
password: a-secure-password
uri: https://my.rabbit:15672 # uri for the management api; when scheme is not provided in uri, operator defaults to 'http'
---
apiVersion: rabbitmq.com/v1beta1
kind: Queue
metadata:
name: qq-example
spec:
name: my-queue
rabbitmqClusterReference:
connectionSecret:
name: my-rabbit-creds # has to an existing secret in the same namespace as this Queue object
Note that spec.rabbitmqClusterReference
is an immutable field. You cannot update the connectionSecret name after creation.
Custom Connection URI
- For RabbitmqClusters that cannot be connected by its Kubernetes service object (for example if the TLS certificate is generated for a custom domain, not the Kubernetes service), you can annotate Rabbitmqclusters with a custom connection URI. Messaging Topology Operator will use the provided information to connect instead of Kubernetes dns.
- This feature is released since Messaging Topology Operator
1.12.0
.
To annotate RabbitmqClusters,
kubectl annotate rmq RMQ-NAME rabbitmq.com/operator-connection-uri=https://test:1234
Queues and Policies
Messaging Topology Operator can declare queues and policies in a RabbitMQ cluster.
The following manifest will create a queue named 'test' in the default vhost:
apiVersion: rabbitmq.com/v1beta1
kind: Queue
metadata:
name: test # name of this custom resource; does not have to the same as the actual queue name
namespace: rabbitmq-system
spec:
name: test # name of the queue
autoDelete: false
durable: true
rabbitmqClusterReference:
name: example-rabbit
The following manifest will create a policy named 'lazy-queue' in default virtual host:
apiVersion: rabbitmq.com/v1beta1
kind: Policy
metadata:
name: policy-example # name of this custom resource
namespace: rabbitmq-system
spec:
name: lazy-queue
pattern: "^lazy-queue-" # matches any queue begins with "lazy-queue-"
applyTo: "queues"
definition:
queue-mode: lazy
rabbitmqClusterReference:
name: example-rabbit
Note that it's not recommended setting optional queue arguments on queues directly. Once set, queue properties cannot be changed. Use policies instead.
The Messaging Topology repo has more examples on queues and policies.