Merge pull request #1802 from rabbitmq/kubernetes/limitations-top-op

Document Topology Operator known limitation

Author: michaelklishin

site/kubernetes/operator/operator-overview.md

@@ -18,6 +18,7 @@ used by applications running on Kubernetes or outside of Kubernetes.
 
 Documentation of Cluster Operator spans several guides:
 
+ * [Limitations](#limitations)
  * [Quickstart guide](quickstart-operator.html) for RabbitMQ Cluster Kubernetes Operator
  * [Installing](install-operator.html) RabbitMQ Cluster Kubernetes Operator
  * [Configuring Defaults](configure-operator-defaults.html) for RabbitMQ Cluster Operator
@@ -79,11 +80,27 @@ The RabbitMQ Messaging Topology Operator supports managing RabbitMQ messaging to
 
 Documentation for the Messaging Topology Operator is structured as follows:
 
+ * [Limitations](#top-op-limitations)
  * [Installing RabbitMQ Messaging Topology Operator](./install-topology-operator.html)
  * [Using RabbitMQ Messaging Topology Operator](./using-topology-operator.html)
  * [TLS for Messaging Topology Operator](./tls-topology-operator.html)
  * [Troubleshooting Messaging Topology Operator](./troubleshooting-topology-operator.html)
 
+### <a id='top-op-limitations' class='anchor' href='#top-op-limitations'>Limitations</a>
+
+#### Custom default credentials result in 401 unauthorised
+
+The Topology Operator relies on the default credentials `Secret` created by the Cluster Operator. If the `RabbitmqCluster`
+`spec` defines the default user in `additionalConfig` using the keys `default_user` and `default_pass`, it will
+result in incorrect credentials generated for the default credentials `Secret`. Due to the incorrect credentials, all
+operations from the Topology Operator will error and print the following message in the log:
+
+<pre>
+Error: API responded with a 401 Unauthorized
+</pre>
+
+See the [troubleshooting Messaging Topology Operator](./troubleshooting-topology-operator.html) section for more details and a workaround.
+
 ## <a id='source' class='anchor' href='#source'>The Source Code for these Kubernetes Operators</a>
 
 Both Operators are open source. You can contribute to its development on GitHub:

site/kubernetes/operator/troubleshooting-topology-operator.md

@@ -47,4 +47,50 @@ status:
     type: Ready
     Reason: "SuccessfulCreateOrUpdate" # status false result in reason FailedCreateOrUpdate
     Message: "" # set with error message when status is false
-</pre>
+</pre>
+
+### kubectl apply succeeds, but no object is created inside RabbitMQ
+
+The Topology Operator relies of the default user `Secret` created by the Cluster Operator. If default user `Secret` does not
+have working credentials, the Topology Operator will fail to communicate with RabbitMQ HTTP API. This can happen if `RabbitmqCluster`
+object defines a default user and password, for example:
+
+<pre class="lang-yaml">
+apiVersion: rabbitmq.com/v1beta1
+kind: RabbitmqCluster
+metadata:
+  name: custom-configuration
+spec:
+  replicas: 1
+  rabbitmq:
+    additionalConfig: |
+      default_user = some-user
+      default_pass = some-pass
+</pre>
+
+The above will result in incorrect credentials generated in the default user `Secret`. Attempting to target a `RabbitmqCluster` with a Topology
+object will result in an error. For example, the following manifest:
+
+<pre class="lang-yaml">
+apiVersion: rabbitmq.com/v1beta1
+kind: Queue
+metadata:
+  name: my-queue
+spec:
+  name: qq # name of the queue
+  type: quorum
+  durable: true
+  rabbitmqClusterReference:
+    name: custom-configuration
+</pre>
+
+The error observed in Topology Operator logs will have the message:
+
+<pre>
+Error: API responded with a 401 Unauthorized
+</pre>
+
+#### Workaround
+
+Update the default credentials `Secret` with the username and password used in `default_user` and `default_pass`.
+