copy and edit include content for single-drive deploy on linux

add moar include content

fix numbering AGAIN, list syntax for include and copied-into-parent

Updating encryption pages for KES API (#1333)

Our preferred method for authenticating from MinIO to KES is with an API
identity. This PR updates encryption docs to reflect this.

Closes #1280

Add cert-manager documentation (#1317)

Adds cert-manager docs for Kubernetes outputs.

Closes #1245

Partially addresses #1273

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=<API-key-identity-string-from-KES> # 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 <concepts/#authorization>` 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 <tutorials/kes-for-minio/#kes-server-setup>` 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 <concepts/#authorization>` 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. 

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=<API-key-identity-string-from-KES> # 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

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 <tutorials/getting-started/>` 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 <minio-disable-root-access>`
 

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=<API-key-identity-string-from-KES> # 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.)

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/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 <https://www.freedesktop.org/wiki/Software/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 <https://www.man7.org/linux/man-pages/man5/systemd.unit.5.html>`__ 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 <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 <minio-server-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 <tutorials/getting-started/>` 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 <minio-disable-root-access>`
+
+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) <https://en.wikipedia.org/wiki/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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

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=<API-key-identity-string-from-KES>
    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.)

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