From 52e66839f15e60bb5deafdc2539b7de3e6f0e7f1 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Thu, 6 Jun 2024 17:33:02 -0400 Subject: [PATCH] Updates for MinIO Server 2024-05-10 release (#1234) Updates for MinIO Server RELEASE.2024-05-10T01-41-38Z - Removes references to `MINIO_SERVER_URL` envvar. - Updates KMS and KES related envvar settings to add KMS as an option. - Also differentiates KMS and KES related envvar into three groups, which are mutually exclusive. Closes #1214 --- source/administration/minio-console.rst | 25 ---- source/includes/common/common-deploy.rst | 14 --- .../setup-nginx-proxy-with-minio.rst | 2 - .../deploy-minio-multi-node-multi-drive.rst | 6 - .../expand-minio-deployment.rst | 8 +- .../minio-server/settings/console.rst | 25 ---- .../reference/minio-server/settings/kes.rst | 116 +++++++++++++----- 7 files changed, 87 insertions(+), 109 deletions(-) diff --git a/source/administration/minio-console.rst b/source/administration/minio-console.rst index 6690c02f..bc1572b9 100644 --- a/source/administration/minio-console.rst +++ b/source/administration/minio-console.rst @@ -73,31 +73,6 @@ the MinIO Console: See :ref:`minio-metrics-collect-using-prometheus` for a tutorial on configuring Prometheus to collect metrics from MinIO. - * - :envvar:`MINIO_SERVER_URL` - - The `fully qualified domain name `__ (FQDN) the MinIO Console uses for connecting to the MinIO Server. - For the Console to function correctly, the MinIO server URL *must* be the FQDN of the host, resolveable, and reachable. - - The MinIO Console connects to the MinIO Server using an IP - address by default. For example, when the MinIO Server starts up, - the server logs include a line - ``API: https:// https://``. - The MinIO Console defaults to connecting using ````. - - The MinIO Console may require setting this variable in the following scenarios: - - - The MinIO server TLS certificates do not include the local IP address - as a :rfc:`Subject Alternative Name <5280#section-4.2.1.6>` (SAN). - Specify a hostname contained in the TLS certificate to allow the MinIO - Console to validate the TLS connection. - - - The MinIO server's local IP address is not reachable by the MinIO - Console. Specify a resolveable hostname for the MinIO Server. - - - A load balancer or reverse proxy controls traffic to the MinIO server, - such that the MinIO Console cannot reach the server without going - through the load balancer/proxy. Specify the load balancer/proxy - URL for the MinIO server. - * - :envvar:`MINIO_BROWSER_REDIRECT_URL` - The externally resolvable hostname for the MinIO Console used by the configured :ref:`external identity manager diff --git a/source/includes/common/common-deploy.rst b/source/includes/common/common-deploy.rst index e267db9b..d45add6c 100644 --- a/source/includes/common/common-deploy.rst +++ b/source/includes/common/common-deploy.rst @@ -25,13 +25,6 @@ The following example provides a starting environment file: # For example, `--console-address :9001` sets the MinIO Console listen port MINIO_OPTS="--console-address :9001" - # MINIO_SERVER_URL sets the hostname of the local machine for use with the MinIO Server - # MinIO assumes your network control plane can correctly resolve this hostname to the local machine - - # Uncomment the following line and replace the value with the correct hostname for the local machine and port for the MinIO server (9000 by default). - - #MINIO_SERVER_URL="http://minio.example.net:9000" - Include any other environment variables as required for your deployment. .. end-common-deploy-create-environment-file-single-drive @@ -89,13 +82,6 @@ The following example provides a starting environment file: # For example, `--console-address :9001` sets the MinIO Console listen port MINIO_OPTS="--console-address :9001" - # MINIO_SERVER_URL sets the hostname of the local machine for use with the MinIO Server. - # MinIO assumes your network control plane can correctly resolve this hostname to the local machine. - - # Uncomment the following line and replace the value with the correct hostname for the local machine. - - #MINIO_SERVER_URL="http://minio.example.net" - Include any other environment variables as required for your local deployment. .. end-common-deploy-create-environment-file-multi-drive diff --git a/source/integrations/setup-nginx-proxy-with-minio.rst b/source/integrations/setup-nginx-proxy-with-minio.rst index 7d7c94ac..458908d3 100644 --- a/source/integrations/setup-nginx-proxy-with-minio.rst +++ b/source/integrations/setup-nginx-proxy-with-minio.rst @@ -118,7 +118,6 @@ There are two models for proxying requests to the MinIO Server API and the MinIO You must also set the following environment variables for the MinIO deployment: - - Set :envvar:`MINIO_SERVER_URL` to the proxy host FQDN of the MinIO Server (``https://minio.example.net``) - Set the :envvar:`MINIO_BROWSER_REDIRECT_URL` to the proxy host FQDN of the MinIO Console (``https://example.net/minio/ui``) .. tab-item:: Subdomain @@ -224,5 +223,4 @@ There are two models for proxying requests to the MinIO Server API and the MinIO You must also set the following environment variables for the MinIO deployment: - - Set :envvar:`MINIO_SERVER_URL` to the proxy host FQDN of the MinIO Server (``https://minio.example.net``) - Set the :envvar:`MINIO_BROWSER_REDIRECT_URL` to the proxy host FQDN of the MinIO Console (``https://console.example.net/``) diff --git a/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst b/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst index 3fe94f22..ac146673 100644 --- a/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst +++ b/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst @@ -289,12 +289,6 @@ Modify the example to reflect your deployment topology: MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME - # Set to the URL of the load balancer for the MinIO deployment - # This value *must* match across all MinIO servers. If you do - # not have a load balancer, set this value to to any *one* of the - # MinIO hosts in the deployment as a temporary measure. - MINIO_SERVER_URL="https://minio.example.net:9000" - You may specify other :ref:`environment variables ` or server commandline options as required by your deployment. All MinIO nodes in the deployment should include the same diff --git a/source/operations/install-deploy-manage/expand-minio-deployment.rst b/source/operations/install-deploy-manage/expand-minio-deployment.rst index a7194712..c70fc3bf 100644 --- a/source/operations/install-deploy-manage/expand-minio-deployment.rst +++ b/source/operations/install-deploy-manage/expand-minio-deployment.rst @@ -342,18 +342,12 @@ Modify the example to reflect your deployment topology: MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME - # Set to the URL of the load balancer for the MinIO deployment - # This value *must* match across all MinIO servers. If you do - # not have a load balancer, set this value to to any *one* of the - # MinIO hosts in the deployment as a temporary measure. - MINIO_SERVER_URL="https://minio.example.net:9000" - You may specify other :ref:`environment variables ` or server commandline options as required by your deployment. All MinIO nodes in the deployment should include the same environment variables with the matching values. -5) Restart the MinIO Deployment with Expanded Configuration +1) Restart the MinIO Deployment with Expanded Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Issue the following commands on each node **simultaneously** in the deployment diff --git a/source/reference/minio-server/settings/console.rst b/source/reference/minio-server/settings/console.rst index 9bce2fde..cef6e827 100644 --- a/source/reference/minio-server/settings/console.rst +++ b/source/reference/minio-server/settings/console.rst @@ -138,31 +138,6 @@ Session Duration This setting does not have a configuration variable setting. Use the Environment Variable instead. -Server URL -~~~~~~~~~~ - -*Optional* - -.. tab-set:: - - .. tab-item:: Environment Variable - - .. envvar:: MINIO_SERVER_URL - - Specify the Fully Qualified Domain Name (FQDN) the MinIO Console must use for connecting to the MinIO Server. - The Console also uses this value for setting the root hostname when generating presigned URLs. - - This setting may be required if: - - - The MinIO Server uses a TLS certificate that does not include the host local IP(s) in the certificate Subject Alternative Name (SAN) *or* - - - The Console must use a specific hostname to connect or reference the MinIO Server, e.g. due to a reverse proxy or similar configuration. - - .. tab-item:: Configuration Setting - - This setting does not have a configuration variable setting. - Use the Environment Variable instead. - Log Query URL ~~~~~~~~~~~~~ diff --git a/source/reference/minio-server/settings/kes.rst b/source/reference/minio-server/settings/kes.rst index 79a1cdb7..3b6bd0e6 100644 --- a/source/reference/minio-server/settings/kes.rst +++ b/source/reference/minio-server/settings/kes.rst @@ -12,44 +12,30 @@ Key Encryption Service Settings .. |SSE| replace:: :abbr:`SSE (Server-Side Encryption)` -The following environment variables control how the MinIO Server interacts with the Key Encryption Service (KES) when managing encryption and keys. +MinIO Server includes three groups of environment variables to manage how the MinIO Server interacts with the Key Encryption Service (KES), Key Management Service (KMS), or static key files. +You may only define one of the three sets. +If more than one type of environment variable sets is defined, MinIO returns an error. .. note:: These settings do not have configuration setting options for use with :mc:`mc admin config set`. -Define any of these environment variables in the host system prior to starting or restarting the MinIO process. +Define any one set of these environment variables in the host system prior to starting or restarting the MinIO process. Refer to your operating system's documentation for how to define an environment variable. .. include:: /includes/common-mc-admin-config.rst :start-after: start-minio-settings-test-before-prod :end-before: end-minio-settings-test-before-prod +Key Encryption Service +---------------------- + +Define the following variables to use the Key Encryption Service (KES) to connect to a :kes-docs:`supported 3rd party Key Management Service provider <#supported-kms-targets>`. + .. envvar:: MINIO_KMS_KES_ENDPOINT - The endpoint for the MinIO Key Encryption Service (KES) process to use for supporting SSE-S3 and MinIO backend encryption operations. - -.. envvar:: MINIO_KMS_KES_KEY_FILE - - The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE` x.509 certificate to use when authenticating to the KES server. - The KES server requires clients to present their certificate for performing mutual TLS (mTLS). - - See the :minio-git:`KES wiki ` for more complete documentation on KES access control.' - -.. envvar:: MINIO_KMS_KES_CAPATH - - Allows validation of the KES Server Certificate for a Self-Signed or Third-Party :abbr:`CA `. - Specify the path to the location of the :abbr:`CA ` certificate for your KES deployment. - -.. envvar:: MINIO_KMS_KES_CERT_FILE - - The x.509 certificate to present to the KES server. - The KES server requires clients to present their certificate for performing mutual TLS (mTLS). - - The KES server computes an :minio-git:`identity ` from the certificate and compares it to its configured policies. - The KES server grants the :mc:`minio` server access to only those operations explicitly granted by the policy. - - See the :minio-git:`KES wiki ` for more complete documentation on KES access control. + The endpoint(s) for the MinIO Key Encryption Service (KES) process to use for supporting SSE-S3 and MinIO backend encryption operations. + Separate multiple KES endpoints with a ``,``. .. envvar:: MINIO_KMS_KES_KEY_NAME @@ -68,10 +54,80 @@ Refer to your operating system's documentation for how to define an environment :start-after: start-kes-encrypted-backend-desc :end-before: end-kes-encrypted-backend-desc -.. envvar:: MINIO_KMS_KES_ENCLAVE +.. envvar:: MINIO_KMS_KES_API_KEY - Use this optional environment variable to define the name of a KES enclave. - A KES enclave provides an isolated space for its associated keys separate from other enclaves on a stateful KES server. + Preferred method for authenticating with the encryption service using the KES API key obtained from the :kes-docs:`kes identity new ` command. - If not set, MinIO does not send enclave information. - For a stateful KES server, this results in using the default enclave. + This environment variable is mutually exclusive with the :envvar:`MINIO_KMS_KES_KEY_FILE` and :envvar:`MINIO_KMS_KES_CERT_FILE` environment variables. + +.. envvar:: MINIO_KMS_KES_KEY_FILE + + The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE` x.509 certificate to use when authenticating to the KES server. + The KES server requires clients to present their certificate for performing mutual TLS (mTLS). + + See the :minio-git:`KES wiki ` for more complete documentation on KES access control. + + You must also set the :envvar:`MINIO_KMS_KES_CERT_FILE`. + This variable is mutually exclusive with :envvar:`MINIO_KMS_KES_API_KEY`. + +.. envvar:: MINIO_KMS_KES_CERT_FILE + + The x.509 certificate to present to the KES server. + The KES server requires clients to present their certificate for performing mutual TLS (mTLS). + + The KES server computes an :minio-git:`identity ` from the certificate and compares it to its configured policies. + The KES server grants the :mc:`minio` server access to only those operations explicitly granted by the policy. + + See the :minio-git:`KES wiki ` for more complete documentation on KES access control. + + You must also set the :envvar:`MINIO_KMS_KES_KEY_FILE`. + This variable is mutually exclusive with :envvar:`MINIO_KMS_KES_API_KEY`. + +.. envvar:: MINIO_KMS_KES_CAPATH + :optional: + + Allows validation of the KES Server Certificate for a Self-Signed or Third-Party :abbr:`CA (Certificate Authority)`. + Specify the path to the location of the :abbr:`CA (Certificate Authority)` certificate for your KES deployment. + + This variable is not required if you use a public certificate authority. + +.. envvar:: MINIO_KMS_KES_KEY_PASSWORD + :optional: + + The password used to encrypt and decrypt the TLS private key, if used. + +MinIO Key Management Server (KMS) +--------------------------------- + +Define the following variables to use `MinIO KMS `__ to manage keys. + +.. envvar:: MINIO_KMS_SERVER + + The endpoint(s) for the MinIO Key Management Service (KMS) process to use for supporting SSE-S3 and MinIO backend encryption operations. + Separate multiple KMS endpoints with a ``,``. + +.. envvar:: MINIO_KMS_ENCLAVE + + The MinIO KMS Enclave where the key and identity exist. + +.. envvar:: MINIO_KMS_SSE_KEY + + The default key to use for SSE-S3 encryption when a call does not specify a key identity. + +.. envvar:: MINIO_KMS_API_KEY + + The credential used to authenticate with the MinIO KMS service. + +Static Key Files +---------------- + +Provide a static KMS key or key file to use for encryption. + +.. envvar:: MINIO_KMS_SECRET_KEY + + The base64 form of the static KMS key in the form ``:``. + Implements a subset of KMS APIs. + +.. envvar:: MINIO_KMS_SECRET_KEY_FILE + + Path to the file to read the static KMS key from.