Completion of SSE-KMS doc rewrite (#539)

source/includes/linux/steps-configure-minio-kes-hashicorp.rst

@@ -1,53 +1,15 @@
-This procedure assumes a single local host machine running the MinIO and KES processes.
-As part of this procedure, you will:
+Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault for Production
+-------------------------------------------------------------------------------------
 
-- Deploy a |KES| server configured to use `Hashicorp Vault <https://www.vaultproject.io/>`__ as the root |KMS|.
-
-- Create a new |EK| on Vault for use with |SSE|.
-
-- Deploy a MinIO server configured to use the |KES| container for supporting |SSE|.
-
-- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
-
-For production environments, this procedure provides general guidance on deploying and configuring KES at scale.
-Defer to the :ref:`Deploy Distributed MinIO <minio-mnmd>` tutorial for guidance on production-ready MinIO deployments.
-
-For production orchestrated environments, use the MinIO Kubernetes Operator to deploy a tenant with |SSE| enabled and configured for use with Hashicorp Vault.
-
-.. important::
-
-   .. include:: /includes/common/common-minio-kes.rst
-      :start-after: start-kes-encrypted-backend-desc
-      :end-before: end-kes-encrypted-backend-desc
-
-Prerequisites
--------------
-
-.. _minio-sse-vault-prereq-vault:
-
-Deploy or Ensure Access to a Hashicorp Vault Service
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/common/common-minio-kes-hashicorp.rst
-   :start-after: start-kes-prereq-hashicorp-vault-desc
-   :end-before: end-kes-prereq-hashicorp-vault-desc
-
-Deploy or Ensure Access to a MinIO Deployment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/common/common-minio-kes.rst
-   :start-after: start-kes-new-existing-minio-deployment-desc
-   :end-before: end-kes-new-existing-minio-deployment-desc
-
-Deploy MinIO and KES to Enable Server-Side Encryption with Hashicorp Vault
---------------------------------------------------------------------------
-
-Prior to starting these steps, create the following folders:
+Prior to starting these steps, create the following folders if they do not already exist:
 
 .. code-block:: shell
    :class: copyable
+   :substitutions:
 
-   mkdir -P ~/minio-kes-vault/certs ~/minio-kes-vault/minio ~/minio-kes-vault/config
+   mkdir -P |kescertpath|
+   mkdir -P |kesconfigpath|
+   mkdir -P |miniocertpath|
 
 1) Download KES and Create the Service File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -67,38 +29,53 @@ b. Create the Service File
 2) Generate TLS Certificates for KES and MinIO
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. include:: /includes/common/common-minio-kes.rst
-   :start-after: start-kes-generate-kes-certs-desc
-   :end-before: end-kes-generate-kes-certs-desc
+.. include:: /includes/linux/common-minio-kes.rst
+   :start-after: start-kes-generate-kes-certs-prod-desc
+   :end-before: end-kes-generate-kes-certs-prod-desc
+
+Depending on your Vault configuration, you may also need to specify the CA used to sign the KES certificates to the Vault server.
+See the `Hashicorp Vault Configuration Docs <https://www.vaultproject.io/docs/configuration/listener/tcp#tls_client_ca_file>`__ for more information.
+Defer to the client documentation for instructions on trusting a third-party CA.
 
 3) Create the KES and MinIO Configurations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 a. Create the KES Configuration File
 
+   Create the configuration file using your preferred text editor.
+   The following example uses ``nano``:
+
+   .. code-block:: shell
+      :substitutions:
+
+      nano /etc/kes/config.yaml
+
    .. include:: /includes/common/common-minio-kes-hashicorp.rst
       :start-after: start-kes-configuration-hashicorp-vault-desc
       :end-before: end-kes-configuration-hashicorp-vault-desc
 
-   Save the configuration file as ``~/minio-kes-vault/config/kes-config.yaml``. 
-
    - Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
 
       The following command computes the necessary hash:
 
       .. code-block:: shell
          :class: copyable
+         :substitutions:
 
-         kes tool identity of ~/minio-kes-vault/certs/minio-kes.cert
+         kes tool identity of |miniocertpath|/minio-kes.cert
 
    - Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
 
    - Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
 
+b. Configure the MinIO Environment File
 
-b. Create the MinIO Environment File
+   Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
 
-   .. include:: /includes/common/common-minio-kes.rst
+   MinIO defaults to expecting this file at ``/etc/default/minio``.
+   If you modified your deployment to use a different location for the environment file, modify the file at that location.
+
+   .. include:: /includes/linux/common-minio-kes.rst
       :start-after: start-kes-configuration-minio-desc
       :end-before: end-kes-configuration-minio-desc
 
@@ -108,7 +85,9 @@ b. Create the MinIO Environment File
 You must start KES *before* starting MinIO. 
 The MinIO deployment requires access to KES as part of its startup.
 
-a. Start the KES Server
+This step uses ``systemd`` for starting and managing both the KES and MinIO server processes:
+
+a. Start the KES Service on All Hosts
 
    .. include:: /includes/linux/common-minio-kes.rst
       :start-after: start-kes-start-service-desc
@@ -123,7 +102,7 @@ b. Start the MinIO Server
 5) Generate a New Encryption Key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. include:: /includes/common/common-minio-kes.rst
+.. include:: /includes/linux/common-minio-kes.rst
    :start-after: start-kes-generate-key-desc
    :end-before: end-kes-generate-key-desc