1
0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00

DOCS-610: Update KES procedures for KES 0.21.0, minor cleanups for Vault (#612)

Closes #610 

Did a QA pass after reports of some issues with the vault setup.

Identified an issue where my local testing was done with 0.20.0,
resulting in some errors on 0.21.0 due to dropping --mlock.

Also did a few other general tune ups as I ran end-to-ends again using
Vault + Systemd instead of vault in dev mode.

Staging views in #minio-docs channel
This commit is contained in:
Ravind Kumar
2022-10-18 13:15:05 -04:00
committed by GitHub
parent 1963d67a64
commit 21797d127b
13 changed files with 318 additions and 217 deletions

View File

@ -11,14 +11,15 @@ The following example code downloads the latest Linux AMD64-compatible binary an
:class: copyable
:substitutions:
wget https://github.com/minio/kes/releases/download/|kes-stable|/kes-linux-amd64 -O /tmp/kes
curl --retry 10 https://github.com/minio/kes/releases/download/|kes-stable|/kes-linux-amd64 -o /tmp/kes
chmod +x /tmp/kes
sudo mv /tmp/kes /usr/local/bin
kes --version
For distributed KES topologies, repeat this step and all following KES-specific instructions for each host on which you want to deploy KES.
MinIO strongly recommends configuring a load balancer with a "Least Connections" configuration to manage connections to distributed KES hosts.
MinIO uses a round-robin approach by default for routing connections to multiple configured KES servers.
For more granular controls, deploy a dedicated load balancer to manage connections to distributed KES hosts.
.. end-kes-download-desc
@ -92,66 +93,39 @@ Depending on your Vault configuration, you may also need to create a dedicated s
Defer to your organizations best practices around generating production-ready TLS certificates.
Place the certificates and corresponding private keys an appropriate directory such that the MinIO and KES service users can access and read their contents.
This procedure assumes a structure similar to the following:
The following example structure uses the folder hierarchy suggested in the beginning of this procedure:
.. code-block:: shell
:substitutions:
.. tab-set::
# For the MinIO Hosts
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/minio-kes.cert
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/minio-kes.key
.. tab-item:: KES Hosts
# If KES certs are self-signed or use a non-global CA
# Include the CA certs as well
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/kes-server.cert
.. code-block:: shell
:substitutions:
# For the KES Hosts
-rw-r--r-- 1 kes:kes |kescertpath|/kes-server.cert
-rw-r--r-- 1 kes:kes |kescertpath|/kes-server.key
-rw-r--r-- 1 kes:kes |kescertpath|/kes-server.cert
-rw-r--r-- 1 kes:kes |kescertpath|/kes-server.key
If the KES certificates are self-signed *or* signed by Certificate Authority (CA) that is *not* globally trusted, you **must** add the CA certificate to the |miniocertpath| directory such that each MinIO server can properly validate the KES certificates.
# If the Vault certs are self-signed or use a non-global CA
# Include those CA certs as well
-rw-r--r-- 1 kes:kes |kescertpath|/vault-CA.cert
.. tab-item:: MinIO Hosts
.. code-block:: shell
:substitutions:
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/minio-kes.cert
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/minio-kes.key
# If KES certs are self-signed or use a non-global CA
# Include the CA certs as well
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/kes-server.cert
The general strategy for cert management is to ensure that each process (MinIO, KES, and Vault) have their own mTLS certificates *and* the Certificate Authority (CA) used to sign each client certificate.
.. end-kes-generate-kes-certs-prod-desc
.. start-kes-configuration-minio-desc
Add the following lines to the MinIO Environment file on each MinIO host.
See the tutorials for :ref:`minio-snsd`, :ref:`minio-snmd`, or :ref:`minio-mnmd` for more detailed descriptions of a base MinIO environment file.
This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server.cert`` certificates are accessible at the specified location:
.. code-block:: shell
:class: copyable
:substitutions:
# Add these environment variables to the existing environment file
MINIO_KMS_KES_ENDPOINT=https://HOSTNAME:7373
MINIO_KMS_KES_CERT_FILE=|miniocertpath|/minio-kes.cert
MINIO_KMS_KES_KEY_FILE=|miniocertpath|/minio-kes.key
MINIO_KMS_KES_CAPATH=|kescertpath|/kes-server.cert
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
minio server [ARGUMENTS]
Replace ``HOSTNAME`` with the IP address or hostname of the KES server.
If the MinIO server host machines cannot resolve or reach the specified ``HOSTNAME``, the deployment may return errors or fail to start.
- If using a single KES server host, specify the IP or hostname of that host
- If using multiple KES server hosts, specify the load balancer or reverse proxy managing connections to those hosts.
MinIO uses the :envvar:`MINIO_KMS_KES_KEY_NAME` key for the following cryptographic operations:
- Encrypting the MinIO backend (IAM, configuration, etc.)
- Encrypting objects using :ref:`SSE-KMS <minio-encryption-sse-kms>` if the request does not
include a specific |EK|.
- Encrypting objects using :ref:`SSE-S3 <minio-encryption-sse-s3>`.
The ``minio-kes`` certificates enable mTLS between the MinIO deployment and the KES server *only*.
They do not otherwise enable TLS for other client connections to MinIO.
.. end-kes-configuration-minio-desc
.. start-kes-generate-key-desc
MinIO requires that the |EK| exist on the root KMS *before* performing |SSE| operations using that key.

View File

@ -72,7 +72,7 @@ b. Configure the MinIO Environment File
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
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
@ -99,7 +99,7 @@ b. Start the MinIO Server
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc

View File

@ -71,7 +71,7 @@ b. Configure the MinIO Environment File
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
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
@ -98,7 +98,7 @@ b. Start the MinIO Server
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc

View File

@ -71,7 +71,7 @@ b. Configure the MinIO Environment File
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
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
@ -98,7 +98,7 @@ b. Start the MinIO Server
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc

View File

@ -1,17 +1,31 @@
Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault for Local Development
--------------------------------------------------------------------------------------------
Enable Server-Side Encryption using Hashicorp Vault for Local Development
-------------------------------------------------------------------------
Prior to starting these steps, create the following folders:
This procedure assumes deploying MinIO and KES onto the same host.
You can use and modify the information below to better suit your local development environment.
.. code-block:: shell
:class: copyable
:substitutions:
This procedure assumes the following:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
mkdir -P |minioconfigpath|
mkdir -P |miniodatapath|
- An existing Vault deployment
- A single host machine for deploying KES and MinIO
.. admonition:: Set Up Folder Hierarchy
:class: note
Create the following folders on the host machine if they do not already exist.
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
mkdir -P |minioconfigpath|
mkdir -P |miniodatapath|
This procedure uses these paths in the following steps.
If you use different paths, make the necessary modifications for each step to reflect those changes
1) Download the KES Server Binary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -34,65 +48,73 @@ 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
.. container:: procedure
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
a. Create the KES Configuration File
.. code-block:: shell
:substitutions:
nano |kesconfigpath|/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
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:class: copyable
:substitutions:
kes identity of |miniocertpath|/minio-kes.cert
nano |kesconfigpath|/kes-config.yaml
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
- Set the ``vault.engine`` and ``vault.version`` to the appropriate values for the Vault K/V Engine configuration
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
b. Create the MinIO Environment File
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
Create or modify the environment file for the MinIO deployment using your preferred text editor.
The following example uses ``nano``:
The following command computes the necessary hash:
.. code-block:: shell
:substitutions:
.. code-block:: shell
:class: copyable
:substitutions:
nano |minioconfigpath|/minio
kes identity of |miniocertpath|/minio-kes.cert
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
- Set the ``vault.engine`` and ``vault.version`` to the appropriate values for the Vault K/V Engine configuration
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
b. Create the MinIO Environment File
Create or modify the environment file for the MinIO deployment using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:substitutions:
nano |minioconfigpath|/minio
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-vault-seal-unseal-desc
:end-before: end-kes-vault-seal-unseal-desc
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
a. Start the KES Server
.. container:: procedure
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
a. Start the KES Server
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-start-server-desc
:end-before: end-kes-start-server-desc
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
b. Start the MinIO Server
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-minio-start-server-desc
:end-before: end-kes-minio-start-server-desc
Foreground processes depend on the shell or terminal in which they run.
Exiting or terminating the shell/terminal instance also kills the attached process.
@ -101,6 +123,10 @@ Defer to your operating system best practices for running processes in the backg
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-vault-seal-unseal-desc
:end-before: end-kes-vault-seal-unseal-desc
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc

View File

@ -1,30 +1,56 @@
Deploy MinIO and KES with Server-Side Encryption using Hashicorp Vault for Production
-------------------------------------------------------------------------------------
Enable Server-Side Encryption using Hashicorp Vault in Production Environments
------------------------------------------------------------------------------
Prior to starting these steps, create the following folders if they do not already exist:
This procedure provides instructions for configuring and enabling Server-Side Encryption using Hashicorp Vault in production environments.
Specifically, this procedure assumes the following:
.. code-block:: shell
:class: copyable
:substitutions:
- An existing production-grade Vault deployment
- One or more hosts for deploying KES
- One or more hosts for a new or existing MinIO deployment
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
mkdir -P |miniocertpath|
.. admonition:: Set Up Folder Hierarchy
:class: note
Create the following folders on the KES and MinIO host machines if they do not already exist:
.. tab-set::
.. tab-item:: KES Hosts
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |kescertpath|
mkdir -P |kesconfigpath|
.. tab-item:: MinIO Hosts
.. code-block:: shell
:class: copyable
:substitutions:
mkdir -P |miniocertpath|
This procedure uses these paths in the following steps.
If you use different paths, make the necessary modifications for each step to reflect those changes
1) Download KES and Create the Service File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. Download KES
.. container:: procedure
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
a. Download KES
b. Create the Service File
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-download-desc
:end-before: end-kes-download-desc
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-service-file-desc
:end-before: end-kes-service-file-desc
b. Create the Service File
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-service-file-desc
:end-before: end-kes-service-file-desc
2) Generate TLS Certificates for KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -40,48 +66,58 @@ 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
.. container:: procedure
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
a. Create the KES Configuration File
.. code-block:: shell
:substitutions:
nano /opt/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
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
The following command computes the necessary hash:
Create the configuration file using your preferred text editor.
The following example uses ``nano``:
.. code-block:: shell
:class: copyable
:substitutions:
kes identity of |miniocertpath|/minio-kes.cert
nano /opt/kes/config.yaml
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc
:end-before: end-kes-configuration-hashicorp-vault-desc
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
- Set ``MINIO_IDENTITY_HASH`` to the identity hash of the MinIO mTLS certificate.
b. Configure the MinIO Environment File
The following command computes the necessary hash:
Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
.. code-block:: shell
:class: copyable
:substitutions:
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.
kes identity of |miniocertpath|/minio-kes.cert
.. include:: /includes/linux/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
- Replace the ``keystore.vault.endpoint`` with the hostname of the Vault server(s).
- Replace ``keystore.vault.engine`` and ``keystore.vault.version`` with the path and version of the KV engine used for storing secrets.
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
- Modify the ``keystore.vault.tls.ca`` value to correspond to the path to the Vault :abbr:`CA (Certificate Authority)` certificate used to sign the Vault TLS keys.
b. Configure the MinIO Environment File
Modify the MinIO Server environment file for all hosts in the target deployment to include the following environment variables.
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/common/common-minio-kes.rst
:start-after: start-kes-configuration-minio-desc
:end-before: end-kes-configuration-minio-desc
4) Start KES and MinIO
~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-vault-seal-unseal-desc
:end-before: end-kes-vault-seal-unseal-desc
You must start KES *before* starting MinIO.
The MinIO deployment requires access to KES as part of its startup.
@ -102,7 +138,11 @@ b. Start the MinIO Server
5) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/linux/common-minio-kes.rst
.. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-vault-seal-unseal-desc
:end-before: end-kes-vault-seal-unseal-desc
.. include:: /includes/common/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc