mirror of
https://github.com/minio/docs.git
synced 2025-07-30 07:03:26 +03:00
DOCS-IA: Platformize SSE Docs. Hashicorp Pass (#518)
* Platformization of Data Encryption Docs: Hashicorp Pass * Platformization of Data Encryption Docs: Hashicorp Pass * Big pass, CR changes + K8s
This commit is contained in:
Ravind Kumar
GitHub
150
source/includes/windows/common-minio-kes.rst
Normal file
150
source/includes/windows/common-minio-kes.rst
Normal file
@ -0,0 +1,150 @@
|
||||
.. start-kes-generate-kes-certs-desc
|
||||
|
||||
The following commands creates two TLS certificates that expire within 30 days of creation:
|
||||
|
||||
- A TLS certificate for KES to secure communications between it and the Vault deployment
|
||||
- A TLS certificate for MinIO to perform mTLS authentication to KES.
|
||||
|
||||
.. admonition:: Use Caution in Production Environments
|
||||
:class: important
|
||||
|
||||
**DO NOT** use the TLS certificates generated as part of this procedure for
|
||||
any long-term development or production environments.
|
||||
|
||||
Defer to organization/industry best practices around TLS certificate
|
||||
generation and management. A complete guide to creating valid certificates
|
||||
(e.g. well-formed, current, and trusted) is beyond the scope of this
|
||||
procedure.
|
||||
|
||||
.. code-block:: powershell
|
||||
:class: copyable
|
||||
|
||||
C:\kes.exe tool identity new \
|
||||
--key C:\minio-kes-vault\certs\kes-server.key \
|
||||
--cert C:\minio-kes-vault\certs\kes-server.cert \
|
||||
--ip "127.0.0.1" \
|
||||
--dns localhost
|
||||
|
||||
C:\kes tool identity new \
|
||||
--key C:\minio-kes-vault\certs\minio-kes.key \
|
||||
--cert C:\minio-kes-vault\certs\minio-kes.cert \
|
||||
--ip "127.0.0.1" \
|
||||
--dns localhost
|
||||
|
||||
These commands output the keys to the ``C:\minio-kes-vault\certs`` directory on the host operating system.
|
||||
|
||||
The ``--ip`` and ``--dns`` parameters set the IP and DNS ``SubjectAlternativeName`` for the certificate.
|
||||
The above example assumes that all components (Vault, MinIO, and KES) deploy on the same local host machine accessible via ``localhost`` or ``127.0.0.1``.
|
||||
You can specify additional IP or Hostnames based on the network configuration of your local host.
|
||||
|
||||
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. See the `Hashicorp Server Configuration Documentation <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.
|
||||
|
||||
.. end-kes-generate-kes-certs-desc
|
||||
|
||||
.. start-kes-download-desc
|
||||
|
||||
Download the latest stable release (|kes-stable|) of KES from :minio-git:`github.com/minio/kes <kes/releases/latest>`.
|
||||
The following PowerShell command downloads the latest Windows-compatible binary and moves it to the system ``PATH``:
|
||||
|
||||
.. code-block:: powershell
|
||||
:class: copyable
|
||||
:substitutions:
|
||||
|
||||
Invoke-WebRequest -Uri "https://github.com/minio/kes/releases/download/v|kes-stable|/kes-linux-windows-amd64.exe" -OutFile "C:\kes.exe"
|
||||
|
||||
C:\kes.exe --version
|
||||
|
||||
.. end-kes-download-desc
|
||||
|
||||
.. start-kes-start-server-desc
|
||||
|
||||
Run the following command in a terminal or shell to start the KES server as a foreground process.
|
||||
|
||||
.. code-block:: powershell
|
||||
:class: copyable
|
||||
|
||||
C:\kes.exe server --auth --config=C:\minio-kes-vault\config\kes-server-config.yaml
|
||||
|
||||
Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background.
|
||||
|
||||
.. end-kes-start-server-desc
|
||||
|
||||
.. start-kes-minio-start-server-desc
|
||||
|
||||
Run the following command in a terminal or shell to start the MinIO server as a foreground process.
|
||||
|
||||
.. code-block:: powershell
|
||||
:class: copyable
|
||||
|
||||
export MINIO_CONFIG_ENV_FILE=C:\minio-kes-vault\config\minio
|
||||
C:\minio.exe server --console-address :9090
|
||||
|
||||
.. end-kes-minio-start-server-desc
|
||||
|
||||
.. start-kes-generate-key-desc
|
||||
|
||||
MinIO requires that the |EK| exist on the root KMS *before* performing |SSE| operations using that key.
|
||||
Use ``kes key create`` *or* :mc:`mc admin kms key create` to create a new |EK| for use with |SSE|.
|
||||
|
||||
The following command uses the ``kes key create`` command to create a new External Key (EK) stored on the root KMS server for use with encrypting the MinIO backend.
|
||||
|
||||
.. code-block:: powershell
|
||||
:class: copyable
|
||||
|
||||
export KES_SERVER=https://127.0.0.1:7373
|
||||
export KES_CLIENT_KEY=C:\minio-kes-vault\certs\minio-kes.key
|
||||
export KES_CLIENT_CERT=C:\minio-kes-vault\certs\minio-kes.cert
|
||||
|
||||
C:\kes.exe key create -k encrypted-bucket-key
|
||||
|
||||
.. end-kes-generate-key-desc
|
||||
|
||||
.. start-kes-new-existing-minio-deployment-desc
|
||||
|
||||
This procedure provides instructions for modifying the startup environment variables of a MinIO deployment to enable |SSE| via KES and the root KMS.
|
||||
For instructions on new creating a new deployment, reference the :ref:`Single-Node Single-Drive <minio-snsd>` tutorial.
|
||||
|
||||
When creating the environment file for the deployment, pause and switch back to this tutorial to include the necessary environment variables to support |SSE|.
|
||||
|
||||
For existing MinIO Deployments, you can modify the existing environment file and restart the deployment as instructed during this procedure.
|
||||
|
||||
.. end-kes-new-existing-minio-deployment-desc
|
||||
|
||||
.. start-kes-configuration-minio-desc
|
||||
|
||||
Add the following lines to the MinIO Environment file on the Windows host.
|
||||
See the tutorials for :ref:`minio-snsd` 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
|
||||
|
||||
# Add these environment variables to the existing environment file
|
||||
|
||||
MINIO_KMS_KES_ENDPOINT=https://HOSTNAME:7373
|
||||
MINIO_KMS_KES_CERT_FILE=C:\minio-kes-vault\certs\minio-kes.cert
|
||||
MINIO_KMS_KES_KEY_FILE=C:\minio-kes-vault\certs\minio-kes.key
|
||||
MINIO_KMS_KES_CAPATH=C:\minio-kes-vault\certs\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
|
||||
129
source/includes/windows/steps-configure-minio-kes-hashicorp.rst
Normal file
129
source/includes/windows/steps-configure-minio-kes-hashicorp.rst
Normal file
@ -0,0 +1,129 @@
|
||||
This procedure assumes a single local host machine running the MinIO and KES processes.
|
||||
As part of this procedure, you will:
|
||||
|
||||
- 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 baremetal environments, deploy MinIO onto Linux hosts and follow the corresponding documentation for this procedure.
|
||||
|
||||
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/windows/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:
|
||||
|
||||
.. code-block:: powershell
|
||||
:class: copyable
|
||||
|
||||
New-Item -Path "C:\minio-kes-vault" -ItemType "directory"
|
||||
New-Item -Path "C:\minio-kes-vault\certs" -ItemType "directory"
|
||||
New-Item -Path "C:\minio-kes-vault\minio" -ItemType "directory"
|
||||
New-Item -Path "C:\minio-kes-vault\config" -ItemType "directory"
|
||||
|
||||
1) Download KES for Windows
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/windows/common-minio-kes.rst
|
||||
:start-after: start-kes-download-desc
|
||||
:end-before: end-kes-download-desc
|
||||
|
||||
2) Generate TLS Certificates for KES and MinIO
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/windows/common-minio-kes.rst
|
||||
:start-after: start-kes-generate-kes-certs-desc
|
||||
:end-before: end-kes-generate-kes-certs-desc
|
||||
|
||||
3) Create the KES and MinIO Configurations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
a. Create the KES Configuration File
|
||||
|
||||
.. 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 ``C:\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
|
||||
|
||||
kes tool identity of C:\minio-kes-vault\certs\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. Create the MinIO Environment File
|
||||
|
||||
.. 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must start KES *before* starting MinIO.
|
||||
The MinIO deployment requires access to KES as part of its startup.
|
||||
|
||||
a. Start the KES Server
|
||||
|
||||
.. include:: /includes/windows/common-minio-kes.rst
|
||||
:start-after: start-kes-start-server-desc
|
||||
:end-before: end-kes-start-server-desc
|
||||
|
||||
b. Start the MinIO Server
|
||||
|
||||
.. include:: /includes/windows/common-minio-kes.rst
|
||||
:start-after: start-kes-minio-start-server-desc
|
||||
:end-before: end-kes-minio-start-server-desc
|
||||
|
||||
5) Generate a New Encryption Key
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/windows/common-minio-kes.rst
|
||||
:start-after: start-kes-generate-key-desc
|
||||
:end-before: end-kes-generate-key-desc
|
||||
|
||||
6) Enable SSE-KMS for a Bucket
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/common/common-minio-kes.rst
|
||||
:start-after: start-kes-enable-sse-kms-desc
|
||||
:end-before: end-kes-enable-sse-kms-desc
|
||||
Reference in New Issue
Block a user