Skip to content

Commit

Permalink
Add cert-manager documentation (#1317)
Browse files Browse the repository at this point in the history
Adds cert-manager docs for Kubernetes outputs.

Closes #1245 

Partially addresses #1273
  • Loading branch information
djwfyi authored Oct 1, 2024
1 parent 3f9a46b commit ca34aa7
Showing 12 changed files with 1,560 additions and 1 deletion.
373 changes: 373 additions & 0 deletions source/images/k8s/cert-manager-cluster.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/images/k8s/cert-manager-graph.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions source/images/k8s/cert-manager-graph.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
530 changes: 530 additions & 0 deletions source/images/k8s/cert-manager-namespaces.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions source/includes/k8s/deploy-operator.rst
Original file line number Diff line number Diff line change
@@ -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
---------

2 changes: 1 addition & 1 deletion source/includes/k8s/file-transfer-protocol-k8s.rst
Original file line number Diff line number Diff line change
@@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 change: 1 addition & 0 deletions source/index.rst
Original file line number Diff line number Diff line change
@@ -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
113 changes: 113 additions & 0 deletions source/operations/cert-manager.rst
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit ca34aa7

Please sign in to comment.