Merge pull request #1157 from rabbitmq/document-k8s-tls

Add Kubernetes TLS configuration documentation.

Author: michaelklishin

site/img/mTLS.png

@@ -8,19 +8,20 @@ If RabbitMQ Cluster Kubernetes Operator is not installed,
 see the [installation guide](/kubernetes/operator/install-operator.html). For instructions on getting started quickly, see the [quickstart guide](/kubernetes/operator/quickstart-operator.html).
 This guide is structured in the following sections:
 
-* [Confirm Service Availability](#service-availability).
-* [Apply Pod Security Policies](#psp).
-* [Create a RabbitMQ Instance](#create).
-* [Existing examples](#examples).
-* [Configure a RabbitMQ Instance](#configure).
-* [Update a RabbitMQ Instance](#update).
-* [Set a Pod Disruption Budget](#set-pdb).
-* [Find Your RabbitmqCluster Service Name and Admin Credentials](#find).
-* [Verify the Instance is Running](#verify-instance).
-* [Use the RabbitMQ Service in Your App](#use).
-* [Monitor RabbitMQ Clusters](#monitoring).
-* [Delete a RabbitMQ Instance](#delete).
-* [Pause Reconciliation for a RabbitMQ Instance](#pause).
+* [Confirm Service Availability](#service-availability)
+* [Apply Pod Security Policies](#psp)
+* [Create a RabbitMQ Instance](#create)
+* [Existing examples](#examples)
+* [Configure a RabbitMQ Instance](#configure)
+* [Update a RabbitMQ Instance](#update)
+* [Set a Pod Disruption Budget](#set-pdb)
+* [Configure TLS](#tls)
+* [Find Your RabbitmqCluster Service Name and Admin Credentials](#find)
+* [Verify the Instance is Running](#verify-instance)
+* [Use the RabbitMQ Service in Your App](#use)
+* [Monitor RabbitMQ Clusters](#monitoring)
+* [Delete a RabbitMQ Instance](#delete)
+* [Pause Reconciliation for a RabbitMQ Instance](#pause)
 
 ## <a id='service-availability' class='anchor' href='#service-availability'>Confirm Service Availability</a>
 
@@ -940,6 +941,92 @@ For more information about concepts mentioned above, see:
   </col>
 </table>
 
+## <a id='tls' class='anchor' href='#tls'>(Optional) Configure TLS</a>
+
+Transport Layer Security (TLS) is a protocol for encrypting network traffic. <a href="/ssl.html">RabbitMQ supports TLS</a>, and the cluster operator simplifies the process of configuring a RabbitMQ cluster with [TLS](#one-way-tls) or
+[mutual TLS (mTLS)](#mutual-tls) encrypted traffic between clients and the cluter, as well
+as supporting [encrypting RabbitMQ inter-node traffic with mTLS](https://github.com/rabbitmq/cluster-operator/tree/main/docs/examples/mtls-inter-node).
+A [basic overview of TLS](/ssl.html#certificates-and-keys) is helpful for understanding this guide.
+
+### <a id='one-way-tls' class='anchor' href='#one-way-tls'>TLS encrypting traffic between clients and RabbitMQ</a>
+
+In order to encrypt traffic between clients and the RabbitMQ cluster, the RabbitMQ cluster must be configured with a server certificate and key pair signed by a Certificate Authority (CA) trusted by the clients. This allows clients to verify that the server is trusted, and traffic sent between the client and server are encrypted using the server's keys.
+
+The certificate's Subject Alternative Name (SAN) must contain at least the following attributes:
+* `*.<RabbitMQ cluster name>-nodes.<namespace>.svc.<K8s cluster domain name>`
+* `<RabbitMQ cluster name>.<namespace>.svc.<K8s cluster domain name>`
+
+If wildcards are not permitted, the certificate must provide a SAN attribute for each RabbitMQ node in the RabbitMQ cluster.
+For example, if you deploy a 3-node RabbitMQ cluster named `myrabbit` in namespace `mynamespace` with the default Kubernetes cluster domain `cluster.local`, the SAN must include at least the following attributes:
+* `myrabbit-server-0.myrabbit-nodes.mynamespace.svc.cluster.local`
+* `myrabbit-server-1.myrabbit-nodes.mynamespace.svc.cluster.local`
+* `myrabbit-server-2.myrabbit-nodes.mynamespace.svc.cluster.local`
+* `myrabbit.mynamespace.svc.cluster.local`
+
+Note that the last SAN attribute is the client service DNS name.
+Depending on the service type used (`spec.service.type`), further SAN attributes may be required.
+For example, if using service type `NodePort`, the SAN must include the external IP address of each Kubernetes node.
+
+To enable TLS, create a Kubernetes secret containing the PEM-encoded server certificate `server.pem` and private key `server-key.pem`
+
+<pre class='lang-bash'>
+kubectl create secret tls tls-secret --cert=server.pem --key=server-key.pem
+</pre>
+
+or use a tool such as <a href="https://cert-manager.io/">Cert Manger</a> to generate a TLS secret.
+
+Once this secret exists, a RabbitMQ cluster can be deployed following the <a href="https://github.com/rabbitmq/cluster-operator/tree/main/docs/examples/tls">TLS example</a>.
+
+<pre class="lang-yaml">
+apiVersion: rabbitmq.com/v1beta1
+kind: RabbitmqCluster
+metadata:
+  name: additional-port
+spec:
+  replicas: 1
+  tls:
+    secretName: tls-secret
+</pre>
+
+### <a id='mutual-tls' class='anchor' href='#mutual-tls'>Mutual TLS encryption between clients and RabbitMQ</a>
+
+Mutual TLS (mTLS) enhances TLS by requiring that the server verify the identity of the client, in addition to the client verifying the server, which already occurs in TLS encryption. In order for this mutual verification to occur, both the client and server must be configured with certificate and key pairs, with the client pair signed by a CA trusted by the server and the server pair signed by a CA trusted by the client. The mutual verification process is shown in the following diagram:
+
+<img src="/img/mTLS.png"/>
+
+In addition to the [configuration required to support TLS](#one-way-tls), configuring mutual TLS requires the RabbitMQ cluster to be configured with the CA certificate
+used to sign the client certificate and key pair, `ca.pem`. Create a Kuberntes secret with key `ca.crt` containing this secret
+
+<pre class='lang-bash'>
+kubectl create secret generic ca-secret --from-file=ca.crt=ca.pem
+</pre>
+
+or create this secret using a tool such as <a href="https://cert-manager.io/">Cert Manager</a>.
+
+Once this secret and the `tls-secret` exist, a RabbitMQ cluster cluster can be deployed following the [mTLS example](https://github.com/rabbitmq/cluster-operator/tree/main/docs/examples/mtls).
+
+<pre class="lang-yaml">
+apiVersion: rabbitmq.com/v1beta1
+kind: RabbitmqCluster
+metadata:
+  name: mtls
+spec:
+  replicas: 1
+  tls:
+    secretName: tls-secret
+    caSecretName: ca-secret
+</pre>
+
+In order to enforce client verification, RabbitMQ must be configured to reject clients that do not present certificates. This can be done by enabling [TLS peer verification](ssl.html#peer-verification) using
+the `ssl_options.fail_if_no_peer_cert` option in the additional config:
+
+<pre class="lang-yaml">
+spec:
+  rabbitmq:
+    additionalConfig: |
+      ssl_options.fail_if_no_peer_cert = true
+</pre>
+
 
 ## <a id='find' class='anchor' href='#find'>Find Your RabbitmqCluster Service Name and Admin Credentials</a>
 

site/kubernetes/operator/using-operator.md

@@ -51,6 +51,8 @@ TLS can be enabled for all protocols supported by RabbitMQ, not just AMQP 0-9-1,
 which this guide focuses on. [HTTP API](/management.html), [inter-node and CLI tool traffic](/clustering-ssl.html) can be configured
 to use TLS (HTTPS) as well.
 
+To configure TLS on Kubernetes using the RabbitMQ Cluster Operator, see the guide for [Configuring TLS](/kubernetes/operator/using-operator.html#tls).
+
 For an overview of common TLS troubleshooting techniques, see [Troubleshooting TLS-related issues](troubleshooting-ssl.html)
 and [Troubleshooting Networking](troubleshooting-networking.html).