Add guide for enabling RGW with TLS certificate

docs/how-to/enable-rgw-with-tls.rst

@@ -0,0 +1,133 @@
+========================================
+How to enable RGW with a TLS certificate
+========================================
+
+This guide will demonstrate how to enable RGW with a TLS certificate, in order to access a MicroCeph single node installation through a https endpoint.
+
+Prerequisites
+=============
+
+- `a MicroCeph single node installation <https://canonical-microceph.readthedocs-hosted.com/latest/tutorial/get-started/>`_. This will have RGW enabled.
+- `a valid TLS certificate`_. We will use Certbot to obtain a TLS certificate from Let's Encrypt. You can also use a self-signed certificate, or request one from an external/commercial CA.
+
+.. _a valid TLS certificate: https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs
+
+Get a TLS certificate with Certbot
+==================================
+
+Certbot is a command line utility which makes acquiring and renewing SSL certificates from LetsEncrypt an easy, free and automated process. You can install Certbot with the snap or apt package manager.
+
+Install Certbot
+---------------
+
+To install Certbot with snap:
+
+``sudo snap install certbot --classic``
+
+Or apt:
+
+``sudo apt-get install certbot python3-certbot-apache -y``
+
+Get a certificate
+-----------------
+
+In the following command, replace the placeholders with your domain and valid email address (for certificate renewals).
+
+.. code::
+
+    sudo certbot certonly --manual \
+        --preferred-challenges dns \
+        -d s3.yourdomain.com \
+        -m your-email@example.com \
+        --agree-tos
+
+You will be asked to set a DNS record in order to verify ownership of your domain.
+
+.. code::
+
+    Please deploy a DNS TXT record under the name:
+
+    _acme-challenge.s3.yourdomain.com.
+
+    with the following value:
+
+    MKc2mNJmrOuZ5-6zcxnD3NUCb_0w_mRG8bOPIA8K66w
+
+Your certificate should be automatically issued and downloaded.
+
+
+Disable RGW
+===========
+
+If you try enabling RGW when it is already enabled, you will get the following error:
+
+.. code::
+
+    Error: failed placing service rgw: host failed hospitality checks
+    for rgw enablement: rgw service already active on host`
+
+So, if you followed the above guide to set up your MicroCeph node, you first need to run:
+
+.. code::
+
+    sudo microceph disable rgw
+
+Enable RGW with your certificate
+================================
+
+The ``enable`` command expects the actual base 64 certificate and key, not just the file path. This can be done with the following command, where you will need to substitute the actual path to your certificate and key.
+
+.. code::
+
+    sudo microceph enable rgw \
+    --ssl-certificate "$(base64 -w0 ./domain.crt)" \
+    --ssl-private-key "$(base64 -w0 ./domain.key)"
+
+.. note::
+    If you used Let's Encrypt to obtain your certificate, the paths should look like ``/etc/letsencrypt/live/s3.yourdomain.com/fullchain.pem`` for the certificate and ``/etc/letsencrypt/live/s3.yourdomain.com/privkey.pem`` for the key.
+
+If your port 443 is already in use, you can specify a different SSL port:
+
+.. code::
+
+    sudo microceph enable rgw \
+    --ssl-port 7443 \
+    --ssl-certificate "$(base64 -w0 ./domain.crt)" \
+    --ssl-private-key "$(base64 -w0 ./domain.key)"
+
+.. note::
+    If you use a different port number, you will need to include it when accessing your endpoint: in this example, connect to ``https://s3.yourdomain.com:7443``
+
+Verify the configuration
+========================
+
+You can check your configuration with the following command: ``cat /var/snap/microceph/current/conf/radosgw.conf``
+
+The output should be similar to this, with your own IP address and port number:
+
+.. code::
+
+    # Generated by MicroCeph, DO NOT EDIT.
+    [global]
+    mon host = [IP ADDRESS]
+    run dir = /var/snap/microceph/1601/run
+    auth allow insecure global id reclaim = false
+
+    [client.radosgw.gateway]
+    rgw init timeout = 1200
+    rgw frontends = beast ssl_port=7443 ssl_certificate=/var/snap/microceph/    common/server.crt ssl_private_key=/var/snap/microceph/common/server.key
+
+Connect to your endpoint
+========================
+
+You can now use your chosen domain name to access your S3 endpoint through https.
+
+.. code-block:: console
+
+    $ curl https://s3.yourdomain.com:7443
+
+    <?xml version="1.0" encoding="UTF-8"?><ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>anonymous</ID></Owner><Buckets></Buckets></ListAllMyBucketsResult>#
+
+.. note::
+    If your certificate is self-signed, you may get a browser warning. This is okay to bypass, but we recommend using Certbot.
+