mirror of
https://github.com/minio/docs.git
synced 2025-07-28 19:42:10 +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
@ -107,3 +107,12 @@ The instructions include examples for both quay.io and DockerHub:
|
||||
If your local host firewall permits external access to the MinIO S3 API port, other hosts on the same network can access the MinIO deployment using the IP or hostname for your local host.
|
||||
|
||||
.. end-common-deploy-connect-to-minio-service
|
||||
|
||||
.. start-common-prereq-container-management-interface
|
||||
|
||||
This procedure assumes you have a working `Podman <https://podman.io/getting-started/installation.html>`_ installation configured to run in "Rootfull" mode.
|
||||
|
||||
"Rootless" modes may not provide sufficient permissions to run KES with the necessary security settings.
|
||||
See the relevant :podman-git:`"rootless" documentation <blob/main/docs/tutorials/rootless_tutorial.md>` for more information.
|
||||
|
||||
.. end-common-prereq-container-management-interface
|
||||
216
source/includes/container/common-minio-kes.rst
Normal file
216
source/includes/container/common-minio-kes.rst
Normal file
@ -0,0 +1,216 @@
|
||||
.. start-common-deploy-create-pod-and-containers
|
||||
|
||||
The commands in this section create the following resources:
|
||||
|
||||
- A Podman :podman-docs:`Pod <markdown/podman-pod.1.html>` to facilitate container communications
|
||||
- A Container for the KES Server configured to use Hashicorp Vault as the Root |KMS|.
|
||||
- A Container for a MinIO Server running in :ref:`Single-Node Single-Drive Mode <minio-snsd>`.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
:substitutions:
|
||||
|
||||
sudo podman pod create \
|
||||
-p 9000:9000 -p 9090:9090 -p 7373:7373 \
|
||||
-v ~/minio-kes-vault/certs:/certs \
|
||||
-v ~/minio-kes-vault/minio:/mnt/minio \
|
||||
-v ~/minio-kes-vault/config:/etc/default/ \
|
||||
-n minio-kes-vault
|
||||
|
||||
sudo podman run -dt \
|
||||
--cap-add IPC_LOCK \
|
||||
--name kes-server \
|
||||
--pod "minio-kes-vault" \
|
||||
-e KES_SERVER=https://127.0.0.1:7373 \
|
||||
-e KES_CLIENT_KEY=/certs/kes-server.key \
|
||||
-e KES_CLIENT_CERT=/certs/kes-server.cert \
|
||||
quay.io/minio/kes:|kes-stable| server \
|
||||
--mlock --auth \
|
||||
--config=/etc/default/kes-server-config.yaml \
|
||||
|
||||
sudo podman run -dt \
|
||||
--name minio-server \
|
||||
--pod "minio-kes-vault" \
|
||||
-e "MINIO_CONFIG_ENV_FILE=/etc/default/minio" \
|
||||
quay.io/minio/minio:|minio-latest| server \
|
||||
--console-address ":9090"
|
||||
|
||||
You can verify the status of the containers using the following commands:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
# Should show three pods - one for the Pod, one for KES, and one for MinIO
|
||||
sudo podman container ls
|
||||
|
||||
If all pods are operational, you can connect to the MinIO deployment by opening your browser to http://127.0.0.1:9000 and logging in with the root credentials specified in the MinIO environment file.
|
||||
|
||||
.. end-common-deploy-create-pod-and-containers
|
||||
|
||||
.. start-kes-generate-kes-certs-desc
|
||||
|
||||
The following commands create 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:: shell
|
||||
:class: copyable
|
||||
:substitutions:
|
||||
|
||||
podman run --rm \
|
||||
-v ~/minio-kes-vault/certs:/certs \
|
||||
quay.io/minio/kes:|kes-stable| identity new \
|
||||
--key /certs/kes-server.key \
|
||||
--cert /certs/kes-server.cert \
|
||||
kes-server
|
||||
|
||||
podman run --rm \
|
||||
-v ~/minio-kes-vault/certs:/certs \
|
||||
quay.io/minio/kes:|kes-stable| identity new \
|
||||
--key /certs/minio-kes.key \
|
||||
--cert /certs/minio-kes.cert \
|
||||
minio-server
|
||||
|
||||
These commands output the keys to the ``~/minio-kes-vault/certs`` directory on the host operating system.
|
||||
|
||||
Depending on your Vault configuration, you may need to pass the ``kes-server.cert`` as a trusted Certificate Authority. 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.
|
||||
|
||||
.. end-kes-generate-kes-certs-desc
|
||||
|
||||
|
||||
.. start-kes-configuration-minio-desc
|
||||
|
||||
Create the MinIO Environment file at ``~/minio-kes-vault/config/minio``.
|
||||
See the tutorial 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
|
||||
|
||||
MINIO_ROOT_USER=myminioadmin
|
||||
MINIO_ROOT_PASSWORD=minio-secret-key-change-me
|
||||
MINIO_VOLUMES="/mnt/data"
|
||||
|
||||
# KES Configurations
|
||||
|
||||
MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373
|
||||
MINIO_KMS_KES_CERT_FILE=~/minio-kes.cert
|
||||
MINIO_KMS_KES_KEY_FILE=~/minio-kes.key
|
||||
MINIO_KMS_KES_CAPATH=~/server.cert
|
||||
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
|
||||
|
||||
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 for mTLS between the MinIO deployment and the KES server *only*.
|
||||
They do not otherwise enable TLS for other client connections to MinIO.
|
||||
|
||||
KES automatically creates this key if it does not already exist on the root KMS.
|
||||
|
||||
.. end-kes-configuration-minio-desc
|
||||
|
||||
.. start-kes-run-server-vault-desc
|
||||
|
||||
The following commands do the following:
|
||||
|
||||
- Create a Pod for the MinIO and KES containers
|
||||
- Start the KES Container attached to the Pod
|
||||
- Start the MinIO Container attached to the Pod
|
||||
|
||||
The commands include setting an environment variable for the Vault :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
|
||||
These values automatically substitute into the configuration file when running the container.
|
||||
|
||||
All commands assume starting the container in "Rootfull" mode.
|
||||
"Rootless" configurations may work depending on your local host configuration.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
:substitutions:
|
||||
|
||||
# Creates the Pod named 'minio-kes-vault'
|
||||
# Exposes ports for MinIO, KES, and Vault for all containers attached to the pod
|
||||
# Attaches local host volumes to any container in the Pod at the specified paths
|
||||
|
||||
sudo podman pod create \
|
||||
-p 9000:9000 -p 9090:9090 -p 7373:7373 -p 8200:8200 \
|
||||
-v ~/pods/minio-sse-local/minio:/mnt/data \
|
||||
-v ~/pods/minio-sse-local/certs:/certs \
|
||||
-v ~/pods/minio-sse-local/keys:/keys \
|
||||
-v ~/pods/minio-sse-local/config:/etc/default \
|
||||
-n minio-kes-vault
|
||||
|
||||
# Runs the KES container attached to the `minio-kes-vault` Pod
|
||||
# Sets environment variables to allow accessing the KES server using the container KES client
|
||||
# Disables verification of TLS certificates to allow using self-signed client certs
|
||||
# Enables ``mlock`` system call for better security
|
||||
# Disables verification of client TLS certificates to support self-signed certs
|
||||
|
||||
sudo podman run -t \
|
||||
--cap-add IPC_LOCK \
|
||||
--name kes-server \
|
||||
--pod "minio-kes-vault" \
|
||||
-e KES_SERVER=https://127.0.0.1:7373 \
|
||||
-e KES_CLIENT_KEY=/certs/minio-kes.key \
|
||||
-e KES_CLIENT_CERT=/certs/minio-kes.cert \
|
||||
-e VAULTAPPID="vault-app-id" \
|
||||
-e VAULTAPPSECRET="vault-app-secret" \
|
||||
kes:|kes-stable| server \
|
||||
--mlock \
|
||||
--config=/etc/default/kes-server-config.yaml \
|
||||
--auth=off
|
||||
|
||||
# Runs the MinIO container attached to the `minio-kes-vault` Pod
|
||||
# Sets an environment variable pointing to the MinIO Environment file
|
||||
# Starts the server with a dedicated console port of ``9090``
|
||||
|
||||
sudo podman run -t \
|
||||
-e "MINIO_CONFIG_ENV_FILE=/etc/default/minio" \
|
||||
--name "minio" \
|
||||
--pod "minio-kes-vault" \
|
||||
minio:|minio-latest| server --console-address ":9090"
|
||||
|
||||
You can verify the installation by opening your Internet Browser and navigating to http://127.0.0.1:9090 and logging in with your MinIO Root Credentials.
|
||||
|
||||
.. end-kes-run-server-vault-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 add a new
|
||||
External Key (EK) stored on the root KMS server for use with encrypting
|
||||
the MinIO backend.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
:substitutions:
|
||||
|
||||
sudo podman run --rm \
|
||||
-e KES_SERVER=https://127.0.0.1:7373 \
|
||||
-e KES_CLIENT_KEY=~/minio-kes-vault/certs/minio-kes.key \
|
||||
-e KES_CLIENT_CERT=~/minio-kes-vault/certs/minio-kes.cert \
|
||||
kes:|kes-stable| key create -k my-new-encryption-key
|
||||
|
||||
You can specify any key name as appropriate for your use case, such as a bucket-specific key ``minio-mydata-key``.
|
||||
|
||||
.. end-kes-generate-key-desc
|
||||
@ -0,0 +1,149 @@
|
||||
This procedure assumes a single local host machine running the MinIO and KES processes as containers.
|
||||
As part of this procedure, you will:
|
||||
|
||||
- Deploy a |KES| container 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 container configured to use the |KES| container for supporting |SSE|.
|
||||
|
||||
- Configure automatic bucket-default :ref:`SSE-KMS <minio-encryption-sse-kms>`.
|
||||
|
||||
You can use the guidance in this tutorial for deploying MinIO with |SSE| enabled for other container-based topologies.
|
||||
|
||||
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
|
||||
|
||||
Install Podman or a Similar Container Management Interface
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/container/common-deploy.rst
|
||||
:start-after: start-common-prereq-container-management-interface
|
||||
:end-before: end-common-prereq-container-management-interface
|
||||
|
||||
Use Podman to Deploy MinIO and KES with Hashicorp Vault for SSE
|
||||
---------------------------------------------------------------
|
||||
|
||||
Prior to starting these steps, create the following folders:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mkdir -P ~/minio-kes-vault/certs ~/minio-kes-vault/minio ~/minio-kes-vault/config
|
||||
|
||||
For Windows hosts, substitute the paths with Windows-style paths, e.g. ``C:\minio-kes-vault\``.
|
||||
|
||||
|
||||
1) Generate TLS Certificates for KES and MinIO
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/container/common-minio-kes.rst
|
||||
:start-after: start-kes-generate-kes-certs-desc
|
||||
:end-before: end-kes-generate-kes-certs-desc
|
||||
|
||||
|
||||
2) 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 ``~/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:
|
||||
|
||||
podman run --rm \
|
||||
-v ~/minio-kes-vault/certs:/certs \
|
||||
kes:v|kes-stable| tool identity of /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/container/common-minio-kes.rst
|
||||
:start-after: start-kes-configuration-minio-desc
|
||||
:end-before: end-kes-configuration-minio-desc
|
||||
|
||||
3) Create Pod and Containers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/container/common-minio-kes.rst
|
||||
:start-after: start-common-deploy-create-pod-and-containers
|
||||
:end-before: end-common-deploy-create-pod-and-containers
|
||||
|
||||
4) Generate a New Encryption Key
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: /includes/container/common-minio-kes.rst
|
||||
:start-after: start-kes-generate-key-desc
|
||||
:end-before: end-kes-generate-key-desc
|
||||
|
||||
5) Enable SSE-KMS for a Bucket
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can use either the MinIO Console or the MinIO :mc:`mc` CLI to enable bucket-default SSE-KMS with the generated key:
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: MinIO Console
|
||||
|
||||
Open the MinIO Console by navigating to http://127.0.0.1:9090 in your preferred browser and logging in with the root credentials specified to the MinIO container.
|
||||
|
||||
Once logged in, create a new Bucket and name it to your preference.
|
||||
Select the Gear :octicon:`gear` icon to open the management view.
|
||||
|
||||
Select the pencil :octicon:`pencil` icon next to the :guilabel:`Encryption` field to open the modal for configuring a bucket default SSE scheme.
|
||||
|
||||
Select :guilabel:`SSE-KMS`, then enter the name of the key created in the previous step.
|
||||
|
||||
Once you save your changes, try to upload a file to the bucket.
|
||||
When viewing that file in the object browser, note that in the sidebar the metadata includes the SSE encryption scheme and information on the key used to encrypt that object.
|
||||
This indicates the successful encrypted state of the object.
|
||||
|
||||
.. tab-item:: MinIO CLI
|
||||
|
||||
The following commands:
|
||||
|
||||
- Create a new :ref:`alias <alias>` for the MinIO deployment
|
||||
- Create a new bucket for storing encrypted data
|
||||
- Enable SSE-KMS encryption on that bucket
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc alias set local http://127.0.0.1:9000 ROOTUSER ROOTPASSWORD
|
||||
|
||||
mc mb local/encryptedbucket
|
||||
mc encrypt set SSE-KMS encrypted-bucket-key ALIAS/encryptedbucket
|
||||
|
||||
Write a file to the bucket using :mc:`mc cp` or any S3-compatible SDK with a ``PutObject`` function.
|
||||
You can then run :mc:`mc stat` on the file to confirm the associated encryption metadata.
|
||||
@ -28,7 +28,7 @@ Select the container management interface of your choice for the relevant comman
|
||||
|
||||
podman run -dt \
|
||||
-p 9000:9000 -p 9090:9090 \
|
||||
-v PATH:/data/minio \
|
||||
-v PATH:/mnt/data \
|
||||
-v /etc/default/minio:/etc/config.env \
|
||||
-e "MINIO_CONFIG_ENV_FILE=/etc/config.env" \
|
||||
--name "minio_local" \
|
||||
@ -45,7 +45,7 @@ Select the container management interface of your choice for the relevant comman
|
||||
|
||||
docker run -dt \
|
||||
-p 9000:9000 -p 9090:9090 \
|
||||
-v PATH:/data/minio \
|
||||
-v PATH:/mnt/data \
|
||||
-v /etc/default/minio:/etc/config.env \
|
||||
-e "MINIO_CONFIG_ENV_FILE=/etc/config.env" \
|
||||
--name "minio_local" \
|
||||
|
||||
Reference in New Issue
Block a user