Add cert-manager documentation

source/includes/k8s/deploy-operator.rst

@@ -162,6 +162,12 @@ The output of the example command above may differ from the output in your termi
    Alternatively, you can generate x.509 TLS certificates signed by a known and trusted CA and pass those certificates to MinIO Tenants. 
    See :ref:`minio-tls` for more complete documentation.
 
+Certificate Management with cert-manager
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rather than the MinIO Operator managing certificates, you can configure the deployment to use `cert-manager <https://cert-manager.io/>`__.
+For instructions for deploying the MinIO Operator and tenants using cert-manager, refer to the :ref:`cert-manager page <minio-certmanager>`.
+
 Procedure
 ---------
 

source/includes/k8s/file-transfer-protocol-k8s.rst

@@ -164,7 +164,7 @@ If SFTP is enabled, the output resembles the following:
 
    enableSFTP: true
 
-.. _minio-certificate-key-file-sftp-k8s
+.. _minio-certificate-key-file-sftp-k8s:
 
 Connect to MinIO Using SFTP with a Certificate Key File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/index.rst

@@ -106,6 +106,7 @@ For more about connecting to ``play``, see :ref:`MinIO Console play Login <minio
       /operations/external-iam
       /operations/server-side-encryption
       /operations/network-encryption
+      /operations/cert-manager
       /operations/checklists
       /operations/data-recovery
       /operations/troubleshooting

source/operations/cert-manager.rst

@@ -0,0 +1,113 @@
+.. _minio-certmanager:
+
+============
+cert-manager
+============
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 1
+
+TLS certificate management with cert-manager
+--------------------------------------------
+
+This guide shows you how to install cert-manager for TLS certificate management.
+The guide assumes a new or fresh MinIO Operator installation.
+
+.. note::
+
+   This guide uses a self-signed ``Cluster Issuer``. 
+   You can also use `other Issuers supported by cert-manager <https://cert-manager.io/docs/configuration/issuers/>`__.
+
+   The main difference is that you must provide that ``Issuer`` CA certificate to MinIO, instead of the CA's mentioned in this guide.
+
+Refer to the `cert-manager documentation <https://cert-manager.io>`__ and your own organization's certificate requirements for more advanced configurations.
+
+cert-manager manages certificates within Kubernetes clusters.
+The MinIO Operator supports using cert-manager for managing and provisioning certificates as an alternative to the MinIO Operator managing certificates for itself and its tenants.
+
+cert-manager obtains valid certificates from an ``Issuer`` or ``ClusterIssuer`` and can automatically renew certificates prior to expiration.
+
+A ``ClusterIssuer`` issues certificates for multiple namespaces.
+An ``Issuer`` only mints certificates for its own namespace.
+
+The following graphic depicts how cert-manager provides certificates in namespaces across a Kubernetes cluster.
+
+- A ``ClusterIssuer`` exists at the root level of the Kubernetes cluster, typically the ``default`` namespace, to provide certificates to all other namespaces.
+- The ``minio-operator`` namespace receives its own, local ``Issuer``. 
+- Each tenant's namespace receives its own, local ``Issuer``.
+- The certificates issued by each tenant namespace must be made known to and trusted by the MinIO Operator.
+
+.. image:: /images/k8s/cert-manager-graph.png
+   :width: 600px
+   :alt: A graph of the namespaces in a Kubernetes cluster showing the relationship between the root level ClusterIssuer and three other namespaces with their own Issuer.
+   :align: center
+
+
+Prerequisites
+-------------
+
+- A `supported version of Kubernetes <https://kubernetes.io/releases/>`__. 
+- `kustomize <https://kustomize.io/>`__ installed
+- ``kubectl`` access to your ``k8s`` cluster
+
+.. _minio-setup-certmanager:
+
+Setup cert-manager
+------------------
+
+Install cert-manager
+~~~~~~~~~~~~~~~~~~~~
+
+The following command installs version 1.12.13 using ``kubectl``.
+
+.. code-block:: shell
+   :class: copyable
+
+   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.13/cert-manager.yaml
+
+`Release 1.12.X LTS <https://cert-manager.io/docs/releases/release-notes/release-notes-1.12/>`__ is preferred, but you may install the latest version.
+For more details on installing cert-manager, see their `installation instructions <https://cert-manager.io/docs/installation/>`__.
+
+.. _minio-cert-manager-create-cluster-issuer:
+
+Create a self-signed Cluster Issuer for the cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``Cluster Issuer`` is the top level Issuer from which all other certificates in the cluster derive. 
+
+1. Request cert-manager to generate this by creating a ``ClusterIssuer`` resource.
+
+   Create a file called ``selfsigned-root-clusterissuer.yaml`` with the following contents:
+
+   .. code-block:: yaml
+      :class: copyable
+
+      # selfsigned-root-clusterissuer.yaml
+      apiVersion: cert-manager.io/v1
+      kind: ClusterIssuer
+      metadata:
+        name: selfsigned-root
+      spec:
+        selfSigned: {}
+
+2. Apply the resource to the cluster:
+
+   .. code-block:: shell
+      :class: copyable
+
+      kubectl apply -f selfsigned-root-clusterissuer.yaml
+
+Next steps
+----------
+
+Set up :ref:`cert-manager for the MinIO Operator <minio-certmanager-operator>`.
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   /operations/cert-manager/cert-manager-operator
+   /operations/cert-manager/cert-manager-tenants