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

@@ -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 <https://en.wikipedia.org/wiki/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://<IP ADDRESS 1> https://<IP ADDRESS 2>``.
- The MinIO Console defaults to connecting using ``<IP ADDRESS 1>``.
-
- 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 

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:https://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:https://minio.example.net"
-
 Include any other environment variables as required for your local deployment.
 .. end-common-deploy-create-environment-file-multi-drive
 

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/``)

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
 <minio-server-environment-variables>` or server commandline options as required
 by your deployment. All MinIO nodes in the deployment should include the same

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
 <minio-server-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

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
 ~~~~~~~~~~~~~
 

source/reference/minio-server/settings/kes.rst

@@ -12,34 +12,63 @@ 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.
+ 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
+
+ The name of an external key on the Key Management system (KMS) configured on the KES server and used for performing en/decryption operations. 
+ MinIO uses this key for the following:
+
+ - Encrypting backend data (:ref:`IAM <minio-authentication-and-identity-management>`, server configuration).
+
+ - The default encryption key for Server-Side Encryption with :ref:`SSE-KMS <minio-encryption-sse-kms>`.
+
+ - The encryption key for Server-Side Encryption with :ref:`SSE-S3 <minio-encryption-sse-s3>`.
+
+ .. important::
+
+ .. include:: /includes/common/common-minio-kes.rst
+ :start-after: start-kes-encrypted-backend-desc
+ :end-before: end-kes-encrypted-backend-desc
+
+.. envvar:: MINIO_KMS_KES_API_KEY
+
+ Preferred method for authenticating with the encryption service using the KES API key obtained from the :kes-docs:`kes identity new <cli/kes-identity/new/>` command.
+
+ 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 <kes/wiki/Configuration#policy-configuration>` for more complete documentation on KES access control.'
-
-.. envvar:: MINIO_KMS_KES_CAPATH
+ See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>` for more complete documentation on KES access control.
 
- 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.
+ 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
 
@@ -51,27 +80,54 @@ Refer to your operating system's documentation for how to define an environment
 
  See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>` for more complete documentation on KES access control.
 
-.. envvar:: MINIO_KMS_KES_KEY_NAME
+ You must also set the :envvar:`MINIO_KMS_KES_KEY_FILE`.
+ This variable is mutually exclusive with :envvar:`MINIO_KMS_KES_API_KEY`.
 
- The name of an external key on the Key Management system (KMS) configured on the KES server and used for performing en/decryption operations. 
- MinIO uses this key for the following:
+.. envvar:: MINIO_KMS_KES_CAPATH
+ :optional:
 
- - Encrypting backend data (:ref:`IAM <minio-authentication-and-identity-management>`, server configuration).
+ 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.
 
- - The default encryption key for Server-Side Encryption with :ref:`SSE-KMS <minio-encryption-sse-kms>`.
+ This variable is not required if you use a public certificate authority.
 
- - The encryption key for Server-Side Encryption with :ref:`SSE-S3 <minio-encryption-sse-s3>`.
+.. envvar:: MINIO_KMS_KES_KEY_PASSWORD
+ :optional:
 
- .. important::
+ The password used to encrypt and decrypt the TLS private key, if used.
 
- .. include:: /includes/common/common-minio-kes.rst
- :start-after: start-kes-encrypted-backend-desc
- :end-before: end-kes-encrypted-backend-desc
+MinIO Key Management Server (KMS)
+---------------------------------
+
+Define the following variables to use `MinIO KMS <https://min.io/product/enterprise/key-management-server?ref=docs>`__ 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
 
-.. envvar:: MINIO_KMS_KES_ENCLAVE
+ The base64 form of the static KMS key in the form ``<key-name>:<base64-32byte-key>``. 
+ Implements a subset of KMS APIs.
 
- 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.
+.. envvar:: MINIO_KMS_SECRET_KEY_FILE
 
- If not set, MinIO does not send enclave information.
- For a stateful KES server, this results in using the default enclave.
+ Path to the file to read the static KMS key from.