diff --git a/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst b/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst index 5289180e7..67b0a6b1e 100644 --- a/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst +++ b/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst @@ -146,9 +146,19 @@ MinIO server host in the deployment: :class: copyable export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373 - export MINIO_KMS_KES_KEY_FILE=root.key - export MINIO_KMS_KES_CERT_FILE=root.cert - export MINIO_KMS_KES_KEY_NAME=my-minio-sse-kms-key + export MINIO_KMS_KES_API_KEY= # Replace with the key string for your credentials + export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key + +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. .. list-table:: :stub-columns: 1 @@ -157,15 +167,14 @@ MinIO server host in the deployment: * - :envvar:`MINIO_KMS_KES_ENDPOINT` - The endpoint for the MinIO ``Play`` KES service. - * - :envvar:`MINIO_KMS_KES_KEY_FILE` - - The private key file corresponding to an :kes-docs:`identity ` on the KES service. - The identity must grant permission to create, generate, and decrypt keys. - Specify the same identity key file as the ``KES_KEY_FILE`` environment variable in the previous step. + * - :envvar:`MINIO_KMS_KES_API_KEY` + - The API key :kes-docs:`generated by KES ` for the MinIO deployment. + The identity of the API key must grant permission to create, generate, and decrypt keys. - * - :envvar:`MINIO_KMS_KES_CERT_FILE` - - The public certificate file corresponding to an :kes-docs:`identity ` on the KES service. - The identity must grant permission to create, generate, and decrypt keys. - Specify the same identity certificate as the ``KES_CERT_FILE`` environment variable in the previous step. + The API key is the preferred way to authenticate with the KES server. + If circumstances require it, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead. + Specify *either* the API key *or* the Key File and Cert File. + Do *not* populate all three environment variables. * - :envvar:`MINIO_KMS_KES_KEY_NAME` - The name of the External Key (EK) to use for performing SSE encryption operations. diff --git a/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst b/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst index a446e2c23..c70a17bfc 100644 --- a/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst +++ b/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst @@ -148,10 +148,20 @@ MinIO server host in the deployment: :class: copyable export MINIO_KMS_KES_ENDPOINT=https://play.min.io:7373 - export MINIO_KMS_KES_KEY_FILE=root.key - export MINIO_KMS_KES_CERT_FILE=root.cert + export MINIO_KMS_KES_API_KEY= # Replace with the key string for your credentials export MINIO_KMS_KES_KEY_NAME=my-minio-sse-s3-key +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. + .. list-table:: :stub-columns: 1 :widths: 30 80 diff --git a/source/images/k8s/cert-manager-cluster.svg b/source/images/k8s/cert-manager-cluster.svg new file mode 100644 index 000000000..6c58eb1da --- /dev/null +++ b/source/images/k8s/cert-manager-cluster.svg @@ -0,0 +1,373 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/source/images/k8s/cert-manager-graph.png b/source/images/k8s/cert-manager-graph.png new file mode 100644 index 000000000..1730e57d1 Binary files /dev/null and b/source/images/k8s/cert-manager-graph.png differ diff --git a/source/images/k8s/cert-manager-graph.svg b/source/images/k8s/cert-manager-graph.svg new file mode 100644 index 000000000..69a0c1712 --- /dev/null +++ b/source/images/k8s/cert-manager-graph.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/k8s/cert-manager-namespaces.svg b/source/images/k8s/cert-manager-namespaces.svg new file mode 100644 index 000000000..251e5bfb5 --- /dev/null +++ b/source/images/k8s/cert-manager-namespaces.svg @@ -0,0 +1,530 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/source/includes/common/common-deploy.rst b/source/includes/common/common-deploy.rst index 832733aa6..2902e0a92 100644 --- a/source/includes/common/common-deploy.rst +++ b/source/includes/common/common-deploy.rst @@ -36,11 +36,14 @@ Include any other environment variables as required for your deployment. MinIO automatically generates unique root credentials if all of the following conditions are true: - :kes-docs:`KES ` Release 2024-03-01T18-06-46Z or later running + - **Have not** defined: + - ``MINIO_ROOT_USER`` variable - ``MINIO_ROOT_PASSWORD`` variable - **Have**: + - set up KES with a :kes-docs:`supported KMS target <#supported-kms-targets>` - disabled root access with the :ref:`MinIO environment variable ` diff --git a/source/includes/container/common-minio-kes.rst b/source/includes/container/common-minio-kes.rst index f35d5aec0..7dae61c15 100644 --- a/source/includes/container/common-minio-kes.rst +++ b/source/includes/container/common-minio-kes.rst @@ -99,11 +99,21 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server # KES Configurations MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373 - MINIO_KMS_KES_CERT_FILE=/certs/minio-kes.cert - MINIO_KMS_KES_KEY_FILE=/certs/minio-kes.key + MINIO_KMS_KES_API_KEY= # Replace with the key string for your credentials MINIO_KMS_KES_CAPATH=/certs/server.cert MINIO_KMS_KES_KEY_NAME=minio-backend-default-key +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. + MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations: - Encrypting the MinIO backend (IAM, configuration, etc.) diff --git a/source/includes/k8s/deploy-operator.rst b/source/includes/k8s/deploy-operator.rst index 246d34fa2..a5991c728 100644 --- a/source/includes/k8s/deploy-operator.rst +++ b/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 `__. +For instructions for deploying the MinIO Operator and tenants using cert-manager, refer to the :ref:`cert-manager page `. + Procedure --------- diff --git a/source/includes/k8s/file-transfer-protocol-k8s.rst b/source/includes/k8s/file-transfer-protocol-k8s.rst index 408db992a..6096eebc5 100644 --- a/source/includes/k8s/file-transfer-protocol-k8s.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/linux/steps-deploy-minio-single-node-single-drive.rst b/source/includes/linux/steps-deploy-minio-single-node-single-drive.rst index 9d289688a..d2dd83630 100644 --- a/source/includes/linux/steps-deploy-minio-single-node-single-drive.rst +++ b/source/includes/linux/steps-deploy-minio-single-node-single-drive.rst @@ -8,20 +8,137 @@ 2) Create the ``systemd`` Service File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: /includes/linux/common-installation.rst - :start-after: start-install-minio-systemd-desc - :end-before: end-install-minio-systemd-desc +The ``.deb`` or ``.rpm`` packages install the following `systemd `__ service file to ``/usr/lib/systemd/system/minio.service``. +For binary installations, create this file manually on all MinIO hosts. + +.. note:: + + ``systemd`` checks the ``/etc/systemd/...`` path before checking the ``/usr/lib/systemd/...`` path and uses the first file it finds. + To avoid conflicting or unexpected configuration options, check that the file exists only at the ``/usr/lib/systemd/system/minio.service`` path. + + Refer to the `man page for systemd.unit `__ for details on the file path search order. + +.. code-block:: shell + :class: copyable + + [Unit] + Description=MinIO + Documentation=https://min.io/docs/minio/linux/index.html + Wants=network-online.target + After=network-online.target + AssertFileIsExecutable=/usr/local/bin/minio + + [Service] + WorkingDirectory=/usr/local + + User=minio-user + Group=minio-user + ProtectProc=invisible + + EnvironmentFile=-/etc/default/minio + ExecStartPre=/bin/bash -c "if [ -z \"${MINIO_VOLUMES}\" ]; then echo \"Variable MINIO_VOLUMES not set in /etc/default/minio\"; exit 1; fi" + ExecStart=/usr/local/bin/minio server $MINIO_OPTS $MINIO_VOLUMES + + # MinIO RELEASE.2023-05-04T21-44-30Z adds support for Type=notify (https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=) + # This may improve systemctl setups where other services use `After=minio.server` + # Uncomment the line to enable the functionality + # Type=notify + + # Let systemd restart this service always + Restart=always + + # Specifies the maximum file descriptor number that can be opened by this process + LimitNOFILE=65536 + + # Specifies the maximum number of threads this process can create + TasksMax=infinity + + # Disable timeout logic and wait until process is stopped + TimeoutStopSec=infinity + SendSIGKILL=no + + [Install] + WantedBy=multi-user.target + + # Built for ${project.name}-${project.version} (${project.name}) + +The ``minio.service`` file runs as the ``minio-user`` User and Group by default. +You can create the user and group using the ``groupadd`` and ``useradd`` +commands. The following example creates the user and group, and sets permissions +to access the folder paths intended for use by MinIO. These commands typically +require root (``sudo``) permissions. + +.. code-block:: shell + :class: copyable + + groupadd -r minio-user + useradd -M -r -g minio-user minio-user + chown minio-user:minio-user /mnt/data + +The drive path in this example is specified by the `MINIO_VOLUMES` environment variable. Change the value here and in the environment variable file to match +the path to the drive intended for use by MinIO. + +Alternatively, change the ``User`` and ``Group`` values to another user and +group on the system host with the necessary access and permissions. + +MinIO publishes additional startup script examples on +:minio-git:`github.com/minio/minio-service `. + +To update deployments managed using ``systemctl``, see :ref:`minio-upgrade-systemctl`. + 3) Create the Environment Variable File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: /includes/common/common-deploy.rst - :start-after: start-common-deploy-create-environment-file-single-drive - :end-before: end-common-deploy-create-environment-file-single-drive +Create an environment variable file at ``/etc/default/minio``. +The MinIO Server container can use this file as the source of all :ref:`environment variables `. + +The following example provides a starting environment file: + +.. code-block:: shell + :class: copyable + + # MINIO_ROOT_USER and MINIO_ROOT_PASSWORD sets the root account for the MinIO server. + # This user has unrestricted permissions to perform S3 and administrative API operations on any resource in the deployment. + # Omit to use the default values 'minioadmin:minioadmin'. + # MinIO recommends setting non-default values as a best practice, regardless of environment + + MINIO_ROOT_USER=myminioadmin + MINIO_ROOT_PASSWORD=minio-secret-key-change-me + + # MINIO_VOLUMES sets the storage volume or path to use for the MinIO server. + + MINIO_VOLUMES="/mnt/data" + + # MINIO_OPTS sets any additional commandline options to pass to the MinIO server. + # For example, `--console-address :9001` sets the MinIO Console listen port + MINIO_OPTS="--console-address :9001" + +Include any other environment variables as required for your deployment. + +.. versionadded:: Server RELEASE.2024-03-03T17-50-39Z + +MinIO automatically generates unique root credentials if all of the following conditions are true: + +- :kes-docs:`KES ` Release 2024-03-01T18-06-46Z or later running + +- **Have not** defined: + + - ``MINIO_ROOT_USER`` variable + - ``MINIO_ROOT_PASSWORD`` variable + +- **Have**: + + - set up KES with a :kes-docs:`supported KMS target <#supported-kms-targets>` + - disabled root access with the :ref:`MinIO environment variable ` + +When those conditions are met at startup, MinIO uses the KMS to generate unique root credentials for the deployment using a `hash-based message authentication code (HMAC) `__. + +If MinIO generates such credentials, the key used to generate the credentials **must** remain the same *and* continue to exist. +All data on the deployment is encrypted with this key! + +To rotate the generated root credentials, generate a new key in the KMS, then update the value of the :envvar:`MINIO_KMS_KES_KEY_NAME` with the new key. -.. include:: /includes/common/common-deploy.rst - :start-after: start-common-deploy-create-unique-root-credentials - :end-before: end-common-deploy-create-unique-root-credentials 4) Start the MinIO Service ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/windows/common-minio-kes.rst b/source/includes/windows/common-minio-kes.rst index 7e827449a..c7b24e542 100644 --- a/source/includes/windows/common-minio-kes.rst +++ b/source/includes/windows/common-minio-kes.rst @@ -98,11 +98,29 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server # Add these environment variables to the existing environment file MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373 - MINIO_KMS_KES_CERT_FILE=|miniocertpath|\minio-kes.cert - MINIO_KMS_KES_KEY_FILE=|miniocertpath|\minio-kes.key + MINIO_KMS_KES_API_KEY= MINIO_KMS_KES_CAPATH=|miniocertpath|\kes-server.cert MINIO_KMS_KES_KEY_NAME=minio-backend-default-key + +.. note:: + + - An API key is the preferred way to authenticate with the KES server, as it provides a streamlined and secure authentication process to the KES server. + + - Alternatively, specify the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` instead of :envvar:`MINIO_KMS_KES_API_KEY`. + + API keys are mutually exclusive with certificate-based authentication. + Specify *either* the API key variable *or* the Key File and Cert File variables. + + - The documentation on this site uses API keys. + + .. code-block:: shell + :substitions: + + MINIO_KMS_KES_CERT_FILE=|miniocertpath|\minio-kes.cert + MINIO_KMS_KES_KEY_FILE=|miniocertpath|\minio-kes.key + + MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations: - Encrypting the MinIO backend (IAM, configuration, etc.) diff --git a/source/index.rst b/source/index.rst index e3d376e4d..4b9706933 100644 --- a/source/index.rst +++ b/source/index.rst @@ -106,6 +106,7 @@ For more about connecting to ``play``, see :ref:`MinIO Console play Login `__. + + 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 `__ 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 `__. +- `kustomize `__ 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 `__ is preferred, but you may install the latest version. +For more details on installing cert-manager, see their `installation instructions `__. + +.. _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 `. + +.. toctree:: + :titlesonly: + :hidden: + + /operations/cert-manager/cert-manager-operator + /operations/cert-manager/cert-manager-tenants \ No newline at end of file diff --git a/source/operations/cert-manager/cert-manager-operator.rst b/source/operations/cert-manager/cert-manager-operator.rst new file mode 100644 index 000000000..a9ddc944d --- /dev/null +++ b/source/operations/cert-manager/cert-manager-operator.rst @@ -0,0 +1,255 @@ +.. _minio-certmanager-operator: + +========================= +cert-manager for Operator +========================= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + + +MinIO Operator manages TLS certificate issuing for the services hosted in the ``minio-operator`` namespace. + +This page describes how to manage the Operator's TLS certificates with :ref:`cert-manager `. + +Prerequisites +------------- + +- A `supported version of Kubernetes `__. +- `kustomize `__ installed +- ``kubectl`` access to your ``k8s`` cluster +- Completed the steps to :ref:`set up cert-manager ` +- The MinIO Operator must not yet be installed. + + +1) Create a CA Issuer for the ``minio-operator`` namespace +---------------------------------------------------------- + +This guide **disables** the automatic generation of certificates in MinIO Operator and issues certificates using cert-manager instead. + +The ``minio-operator`` namespace must have its own certificate authority (CA), derived from the cluster's ``ClusterIssuer`` certificate created during :ref:`cert-manager setup `. +Create this CA certificate using cert-manager. + +.. important:: + + This CA certificate **must** exist *before* installing MinIO Operator. + +1. If it does not exist, create the ``minio-operator`` namespace + + .. code-block:: shell + :class: copyable + + kubectl create ns minio-operator + +2. Request a new Certificate with ``spec.isCA: true`` specified. + + This certificate serves as the :abbr:`CA (Certificate Authority)` for the `minio-operator` namespace. + + Create a file called ``operator-ca-tls-secret.yaml`` with the following contents: + + .. code-block:: yaml + :class: copyable + :emphasize-lines: 7,8 + + # operator-ca-tls-secret.yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: minio-operator-ca-certificate + namespace: minio-operator + spec: + isCA: true + commonName: operator + secretName: operator-ca-tls + duration: 70128h # 8y + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-root + kind: ClusterIssuer + group: cert-manager.io + + .. important:: + + The ``spec.issueRef.name`` must match the name of the ``ClusterIssuer`` created when :ref:`setting up cert-manager `. + If you specified a different ``ClusterIssuer`` name or are using a different ``Issuer`` from the guide, modify the ``issuerRef`` to match your environment. + +3. Apply the resource: + + .. code-block:: shell + :class: copyable + + kubectl apply -f operator-ca-tls-secret.yaml + +Kubernetes creates a new secret with the name ``operator-ca-tls`` in the ``minio-operator`` namespace. + +.. important:: + + Make sure to trust this certificate in any applications that need to interact with the MinIO Operator. + + +2) Use the secret to create the ``Issuer`` +------------------------------------------ + +Use the ``operator-ca-tls`` secret to add an ``Issuer`` resource for the ``minio-operator`` namespace. + +1. Create a file called ``operator-ca-issuer.yaml`` with the following contents: + + .. code-block:: yaml + + # operator-ca-issuer.yaml + apiVersion: cert-manager.io/v1 + kind: Issuer + metadata: + name: minio-operator-ca-issuer + namespace: minio-operator + spec: + ca: + secretName: operator-ca-tls + + +2. Apply the resource: + + .. code-block:: shell + + kubectl apply -f operator-ca-issuer.yaml + +3) Create TLS certificate +------------------------- + +Now that the ``Issuer`` exists in the ``minio-operator`` namespace, cert-manager can add a certificate. + +The certificate from cert-manager must be valid for the following DNS domains: + +- ``sts`` +- ``sts.minio-operator.svc.`` +- ``sts.minio-operator.svc.`` + + .. important:: + + Replace ```` with the actual value for your MinIO tenant. + ``cluster domain`` is the internal root DNS domain assigned in your Kubernetes cluster. + Typically, this is ``cluster.local``, but confirm the value by checking your CoreDNS configuration for the correct value for your Kubernetes cluster. + + For example: + + .. code-block:: shell + :class: copyable + + kubectl get configmap coredns -n kube-system -o jsonpath="{.data}" + + Different Kubernetes providers manage the root domain differently. + Check with your Kubernetes provider for more information. + +1. Create a ``Certificate`` for the specified domains: + + Create a file named ``sts-tls-certificate.yaml`` with the following contents: + + .. code-block:: yaml + :class: copyable + :emphasize-lines: 7,12 + + # sts-tls-certificate.yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: sts-certmanager-cert + namespace: minio-operator + spec: + dnsNames: + - sts + - sts.minio-operator.svc + - sts.minio-operator.svc.cluster.local # Replace cluster.local with the value for your domain. + secretName: sts-tls + issuerRef: + name: minio-operator-ca-issuer + + .. important:: + + The ``spec.secretName`` is not optional. + + The secret name **must** be ``sts-tls``. + Confirm this by setting ``spec.secretName: sts-tls`` as highlighted in the certificate YAML. + +2. Apply the resource: + + .. code-block:: shell + :class: copyable + + kubectl apply -f sts-tls-certificate.yaml + +This creates a secret called ``sts-tls`` in the ``minio-operator`` namespace. + +.. warning:: + + The STS service will not start if the ``sts-tls`` secret, containing the TLS certificate, is missing or contains an invalid ``key-value`` pair. + +4) Install Operator with Auto TLS disabled +------------------------------------------ + +You can now :ref:`install the MinIO Operator `. + +When installing the Operator deployment, set the ``OPERATOR_STS_AUTO_TLS_ENABLED`` environment variable to ``off`` in the ``minio-operator`` container. + +Disabling this environment variable prevents the MinIO Operator from issuing the certificates. +Instead, Operator relies on cert-manager to issue the TLS certificate. + +There are various methods to define an environment variable depending on how you install the Operator. +The following steps define the variable with kustomize. + +1. Create a kustomization patch file called ``kustomization.yaml`` with the following contents: + + .. code-block:: yaml + :class: copyable + + # minio-operator/kustomization.yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization + + resources: + - github.com/minio/operator/resources + + patches: + - patch: |- + apiVersion: apps/v1 + kind: Deployment + metadata: + name: minio-operator + namespace: minio-operator + spec: + template: + spec: + containers: + - name: minio-operator + env: + - name: OPERATOR_STS_AUTO_TLS_ENABLED + value: "off" + - name: OPERATOR_STS_ENABLED + value: "on" + +2. Apply the kustomization resource to the cluster: + + .. code-block:: shell + :class: copyable + + kubectl apply -k minio-operator + +Migrate an existing MinIO Operator deployment to cert-manager +------------------------------------------------------------- + +To transition an existing MinIO Operator deployment from using AutoCert to cert-manager, complete the following steps: + +1. Complete the steps for :ref:`installing cert-manager `, including disabling auto-cert. +2. Complete steps 1-3 on this page to generate the certificate authority for the Operator. +3. When you get to the install step on this page, instead replace the existing Operator TLS certificate with the cert-manager issued certificate. +4. Create new cert-manager certificates for each tenant, similar to the steps described on the :ref:`cert-manager for Tenants ` page. +5. Replace the secrets in the MinIO Operator namespace for the tenants with secrets related to each tenant's cert-manager issued certificate. + +Next steps +---------- + +Set up :ref:`cert-manager for a MinIO Tenant `. \ No newline at end of file diff --git a/source/operations/cert-manager/cert-manager-tenants.rst b/source/operations/cert-manager/cert-manager-tenants.rst new file mode 100644 index 000000000..f5ef6d1bd --- /dev/null +++ b/source/operations/cert-manager/cert-manager-tenants.rst @@ -0,0 +1,272 @@ +.. _minio-certmanager-tenants: + +======================== +cert-manager for Tenants +======================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +The following procedures create and apply the resources necessary to use cert-manager for the TLS certificates within a tenant. + +.. note:: + + The procedures use ``tenant-1`` as the name of the tenant. + + Replace the string ``tenant-1`` throughout the procedures to reflect the name of your tenant. + +Prerequisites +------------- + +- `kustomize `__ installed +- ``kubectl`` access to your ``k8s`` cluster +- Completed the steps to :ref:`set up cert-manager ` +- The MinIO Operator installed and :ref:`set up for cert-manager `. + +1) Create the tenant namespace CA Issuer +---------------------------------------- + +Before deploying a new tenant, create a Certificate Authority and Issuer for the tenant's namespace. + +1. If necessary, create the tenant's namespace. + + .. code-block:: shell + :class: copyable + + kubectl create ns tenant-1 + + This much match the value of the ``metadata.namespace`` field in the tenant's YAML. + +2. Request a Certificate for a new Certificate Authority with ``spec.isCA`` set to ``true``. + + Create a file called ``tenant-1-ca-certificate.yaml`` with the following contents: + + .. code-block:: yaml + :class: copyable + :emphasize-lines: 7,8 + + # tenant-1-ca-certificate.yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: tenant-1-ca-certificate + namespace: tenant-1 + spec: + isCA: true + commonName: tenant-1-ca + secretName: tenant-1-ca-tls + duration: 70128h # 8y + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: selfsigned-root + kind: ClusterIssuer + group: cert-manager.io + + .. important:: + + The ``spec.issueRef.name`` must match the name of the ``ClusterIssuer`` created when :ref:`setting up cert-manager `. + If you specified a different ``ClusterIssuer`` name or are using a different ``Issuer`` from the guide, modify the ``issuerRef`` to match your environment. + + +3. Apply the resource: + + .. code-block:: shell + :class: copyable + + kubectl apply -f tenant-1-ca-certificate.yaml + +2) Create the ``Issuer`` +------------------------ + +The ``Issuer`` issues the certificates within the tenant namespace. + +1. Generate a resource definition for an ``Issuer``. + + Create a file called ``tenant-1-ca-issuer.yaml`` with the following contents: + + .. code-block:: yaml + :class: copyable + + # tenant-1-ca-issuer.yaml + apiVersion: cert-manager.io/v1 + kind: Issuer + metadata: + name: tenant-1-ca-issuer + namespace: tenant-1 + spec: + ca: + secretName: tenant-1-ca-tls + +2. Apply the ``Issuer`` resource definition: + + .. code-block:: shell + :class: copyable + + kubectl apply -f tenant-1-ca-issuer.yaml + +3) Create a certificate for the tenant +-------------------------------------- + +Request that cert-manager issue a new TLS server certificate for MinIO. +The certificate must be valid for the following DNS domains: + +- ``minio.`` +- ``minio..svc`` +- ``minio..svc.`` +- ``*.-hl..svc.`` +- ``*..svc.`` +- ``*..minio..svc.'`` + +.. important:: + + Replace the the placeholder text (marked with the ``<`` and ``>`` characters) with values for your tenant: + + - ```` is the internal root DNS domain assigned in your Kubernetes cluster. + Typically, this is ``cluster.local``, but confirm the value by checking your CoreDNS configuration for the correct value for your Kubernetes cluster. + + For example: + + .. code-block:: shell + :class: copyable + + kubectl get configmap coredns -n kube-system -o jsonpath="{.data}" + + Different Kubernetes providers manage the root domain differently. + Check with your Kubernetes provider for more information. + + - ``tenant-name`` is the name provided to your tenant in the ``metadata.name`` of the Tenant YAML. + For this example it is ``myminio``. + + - ``namespace`` is the value created earlier where the tenant will be installed. + In the tenant YAML, it is defined in the the ``metadata.namespace`` field. + For this example it is ``tenant-1``. + +1. Request a ``Certificate`` for the specified domains + + Create a file called ``tenant-1-minio-certificate.yaml``. + The contents of the file should resemble the following, modified to reflect your cluster and tenant configurations: + + .. code-block:: yaml + :class: copyable + + # tenant-1-minio-certificate.yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: tenant-certmanager-cert + namespace: tenant-1 + spec: + dnsNames: + - "minio.tenant-1" + - "minio.tenant-1.svc" + - 'minio.tenant-1.svc.cluster.local' + - '*.minio.tenant-1.svc.cluster.local' + - '*.myminio-hl.tenant-1.svc.cluster.local' + - '*.myminio.minio.tenant-1.svc.cluster.local' + secretName: myminio-tls + issuerRef: + name: tenant-1-ca-issuer + + .. tip:: + + For this example, the Tenant name is ``myminio``. + We recommend naming the secret in the field ``spec.secretName`` as ``-tls`` as a naming convention. + +2. Apply the certificate resource: + + .. code-block:: shell + :class: copyable + + kubectl apply -f tenant-1-minio-certificate.yaml + +3. Validate the changes took effect: + + .. code-block:: shell + :class: copyable + + kubectl describe secret/myminio-tls -n tenant-1 + + .. note:: + + - Replace ``tenant-1`` with the namespace for your tenant. + - Replace ``myminio-tls`` with the name of your secret, if different. + +4) Deploy the tenant using cert-manager for TLS certificate management +---------------------------------------------------------------------- + +When deploying a Tenant, you must set the TLS configuration such that: + +- The Tenant does not automatically generate its own certificates (``spec.requestAutoCert: false``) *and* +- The Tenant has a valid cert-manager reference (``spec.externalCertSecret``) + +This directs the Operator to deploy the Tenant using the cert-manager certificates exclusively. + +The following YAML ``spec`` provides a baseline configuration meeting these requirements: + +.. code-block:: yaml + :emphasize-lines: 6,9,11 + + apiVersion: minio.min.io/v2 + kind: Tenant + metadata: + name: myminio + namespace: tenant-1 + spec: + ... + ## Disable default tls certificates. + requestAutoCert: false + ## Use certificates generated by cert-manager. + externalCertSecret: + - name: myminio-tls + type: cert-manager.io/v1 + ... + +5) Trust the tenant's CA in MinIO Operator +------------------------------------------ + +The MinIO Operator does not trust the tenant's CA by default. +To trust the tenant's CA, you must pass the certificate to the Operator as a secret. + +To do this, create a secret with the prefix ``operator-ca-tls-`` followed by a unique identifier in the `minio-operator` namespace. + +MinIO Operator mounts and trusts **all** certificates issued by the provided Certificate Authorities. +This is required because the MinIO Operator performs health checks using the ``/minio/health/cluster`` endpoint. + +Create ``operator-ca-tls-tenant-1`` secret +++++++++++++++++++++++++++++++++++++++++++ + +Copy the tenant's cert-manager generated CA public key (``ca.crt``) into the `minio-operator` namespace. +This allows Operator to trust the cert-manager issued CA and all certificates derived from it. + +1. Create a ``ca.crt`` file containing the CA: + + .. code-block:: shell + :class: copyable + + kubectl get secrets -n tenant-1 tenant-1-ca-tls -o=jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt + +2. Create the secret: + + .. code-block:: shell + :class: copyable + + kubectl create secret generic operator-ca-tls-tenant-1 --from-file=ca.crt -n minio-operator + +.. tip:: + + In this example we chose a secret name of ``operator-ca-tls-tenant-1``. + We used the tenant namespace ``tenant-1`` as a suffix for easy identification of which namespace the CA comes from. + Use the name of your tenant namespace for easier linking secrets to the related resources. + +6) Deploy the tenant +-------------------- + +With the Certificate Authority and ``Issuer`` in place for the tenant's namespace, you can now :ref:`deploy the object store tenant `. + +Use the modified baseline tenant YAML to disable AutoCert and reference the secret you generated. + diff --git a/source/operations/monitoring/healthcheck-probe.rst b/source/operations/monitoring/healthcheck-probe.rst index 60a8ebfe9..db59d8ba0 100644 --- a/source/operations/monitoring/healthcheck-probe.rst +++ b/source/operations/monitoring/healthcheck-probe.rst @@ -39,6 +39,8 @@ a Prometheus :ref:`alert ` using the ``minio_cluster_nodes_offline_total`` metric to detect whether one or more MinIO nodes are offline. +.. _minio-cluster-write-quorum: + Cluster Write Quorum -------------------- diff --git a/source/operations/network-encryption.rst b/source/operations/network-encryption.rst index 9a1bfe06a..101c5fee4 100644 --- a/source/operations/network-encryption.rst +++ b/source/operations/network-encryption.rst @@ -64,6 +64,12 @@ Enabling TLS If you have a custom Subject Alternative Name (SAN) certificate that is *not* also a wildcard cert, the TLS certificate SAN **must** apply to the hostname for its parent node. Without a wildcard, the SAN must match exactly to be able to connect to the tenant. + Certificate Management with cert-manager + ---------------------------------------- + + The MinIO Operator supports using `cert-manager `__ as a full replacement for its built-in automatic certificate management *or* user-driven manual certificate management. + For instructions for deploying the MinIO Operator and tenants using cert-manager, refer to the :ref:`cert-manager page `. + .. cond:: linux