Improve documentation on MINIO_DOMAIN (#1131)

# Summary

As per a recent customer issue, our guidance on `MINIO_DOMAIN` and
path/virtual bucket lookups needs some attention.

There are two main areas to address:

1. We need to guide users to avoid namespace collision within the
`MINIO_DOMAIN` , as this causes bucket lookup issues with certain MinIO
services/features
2. We need to generally improve docs on setting `MINIO_DOMAIN` correctly

There is also a side objective from Engineering to ensure we have a
simple admonition to direct users to test wherever possible changes to
config settings before applying to production.

---------

Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com>

source/administration/object-management.rst

@@ -55,6 +55,37 @@ Clients and administrators should not create these prefixes manually.
 
 Neither clients nor administrators would manually create the intermediate prefixes, as MinIO automatically infers them from the object name.
 
+.. _minio-object-management-path-virtual-access:
+
+Path vs Virtual Host Bucket Access
+----------------------------------
+
+MinIO supports both :s3-docs:`path-style <VirtualHosting.html#path-style-access>` (default) or :s3-docs:`virtual-host bucket lookups <VirtualHosting.html>`.
+
+For example, consider a MinIO deployment with an assigned Fully Qualified Domain Name (FQDN) of ``minio.example.net``:
+
+- With path-style lookups, applications specify the full path to a bucket, such as ``minio.example.net/mybucket``.
+- With virtual-host lookups, applications specify the bucket as a subdomain, such as ``mybucket.minio.example.net/``.
+
+Some applications may require or expect virtual-host lookup support when performing S3 operations against MinIO.
+To enable virtual-host bucket lookup, you must set the :envvar:`MINIO_DOMAIN` environment variable to a :abbr:`FQDN(Fully Qualified Domain Name)` that resolves to the MinIO Deployment.
+
+If you configure ``MINIO_DOMAIN``, you **must** consider all subdomains of the specified FQDN as exclusively assigned for use as bucket names.
+Any MinIO services which conflict with those domains, such as replication targets, may exhibit unexpected or undesired behavior as a result of the collision. 
+
+For example, if setting ``MINIO_DOMAIN=minio.example.net``, you **cannot** assign any subdomains of ``minio.example.net`` (in the form of ``*.minio.example.net``) to any MinIO service or target. 
+This includes hostnames for use with :ref:`bucket <minio-bucket-replication>`, :ref:`batch <minio-batch-framework-replicate-job>`, or :ref:`site replication <minio-site-replication-overview>`.
+
+.. important::
+
+   For deployments with :ref:`TLS enabled <minio-tls>`, you **must** ensure your TLS certificate SANs cover all subdomains of the leftmost domain specified to :envvar:`MINIO_DOMAIN`.
+
+   For example, the example of ``MINIO_DOMAIN=minio.example.net`` requires a TLS SAN that covers the subdomains of ``minio.example.net``.
+   You can set an additional TLS SAN of ``*.minio.example.net`` to appropriately cover the subdomain namespace.
+
+   TLS Wildcard rules prevent chaining to additional subdomain levels, such that a TLS certificate with a wildcard SAN of ``*.example.net`` would **not** cover the virtual host lookups at ``*.minio.example.net``.
+
+
 Object Organization and Planning
 --------------------------------
 

source/includes/common-mc-admin-config.rst

@@ -107,4 +107,13 @@ If you define both an environment variable and the similar configuration setting
 
 Some settings have only an environment variable or a configuration setting, but not both.
 
-.. end-minio-settings-defined
+.. end-minio-settings-defined
+
+.. start-minio-settings-test-before-prod
+
+.. important::
+
+   Each configuration setting controls fundamental MinIO behavior and functionality.
+   MinIO **strongly recommends** testing configuration changes in a lower environment, such as DEV or QA, before applying to production.
+
+.. end-minio-settings-test-before-prod

source/reference/minio-server/settings.rst

@@ -19,16 +19,15 @@ The :mc:`minio server` process stores its configuration in the storage backend :
 MinIO Settings
 --------------
 
-MinIO settings define runtime behavior of the MinIO :mc:`server <minio server>` process:
+MinIO settings define runtime behavior of the MinIO :mc:`server <minio server>` process.
 
-You can define many MinIO Server settings in one of two ways:
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-defined
+   :end-before: end-minio-settings-defined
 
-1. Set :ref:`environment variables <minio-environment-variables>` in the host system prior to launching or restarting the server process.
+.. include:: /includes/common-mc-admin-config.rst
-2. Modify configuration options using the :mc:`mc admin config` command or the :guilabel:`Administrator > Settings` page of the :ref:`MinIO Console <minio-console>`.
+   :start-after: start-minio-settings-test-before-prod
-
+   :end-before: end-minio-settings-test-before-prod
-.. important::
-
-   Settings defined by an environment variable override similar settings defined as configurations with :mc:`mc admin config` or the MinIO Console.
 
 Additional settings include those to customize:
 

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

@@ -16,6 +16,10 @@ This page covers settings that manage access and behavior for the MinIO Console.
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Browser Settings
 ----------------
 

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

@@ -16,6 +16,10 @@ This page covers settings that control core behavior of the MinIO process.
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Common Settings
 ---------------
 
@@ -87,11 +91,23 @@ Domain
 
       .. envvar:: MINIO_DOMAIN
 
-         Set to the Fully Qualified Domain Name (FQDN) MinIO accepts Bucket DNS (Virtual Host)-style requests on.
+         Enables Virtual Host-style requests to the MinIO deployment.
+         Set the value to the Fully Qualified Domain Name (FQDN) for MinIO to accept incoming virtual host requests.
 
-         For example, setting ``MINIO_DOMAIN=minio.example.net`` directs MinIO to accept an incoming connection request to the ``data`` bucket at ``data.minio.example.net``.
+         Omitting this setting directs MinIO to only accept the default path-style requests.
 
-         If this setting is omitted, the default is to only accept path-style requests. For example, ``minio.example.net/data``.
+         For example, consider a MinIO deployment with an assigned FQDN of ``minio.example.net``.
+
+         - With path-style lookups, applications can access the bucket using it's full path as ``minio.example.net/mybucket``.
+         - With virtual-host lookups, application can access the bucket as a virtual host as ``mybucket.minio.example.net/``.
+
+         .. important::
+
+            If you configure ``MINIO_DOMAIN``, you **must** consider all subdomains of the specified FQDN as exclusively assigned for use as bucket names.
+            Any MinIO services which conflict with those domains, such as replication targets, may exhibit unexpected or undesired behavior as a result of the collision. 
+
+            For example, if setting ``MINIO_DOMAIN=minio.example.net``, you **cannot** assign any subdomains of ``minio.example.net`` (in the form of ``*.minio.example.net``) to any MinIO service or target. 
+            This includes hostnames for use with :ref:`bucket <minio-bucket-replication>`, :ref:`batch <minio-batch-framework-replicate-job>`, or :ref:`site replication <minio-site-replication-overview>`.
 
    .. tab-item:: Configuration Setting
 

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

@@ -19,6 +19,10 @@ Users should migrate to the recommended replacement at the earliest opportunity.
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Environment Variables
 ---------------------
 

source/reference/minio-server/settings/iam/ldap.rst

@@ -26,6 +26,14 @@ See :ref:`minio-authenticate-using-ad-ldap-generic` for a tutorial on using thes
 
 The ``identity_ldap`` configuration settings remains available for existing scripts and other tools.
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-defined
+   :end-before: end-minio-settings-defined
+
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Examples
 --------
 

source/reference/minio-server/settings/iam/minio-access-plugin.rst

@@ -13,6 +13,14 @@ MinIO Access Management Plugin Settings
 This page documents settings for enabling external authorization management using the MinIO Access Management Plugin.
 See :ref:`minio-external-access-management-plugin` for a tutorial on using these settings.
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-defined
+   :end-before: end-minio-settings-defined
+
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Examples
 --------
 

source/reference/minio-server/settings/iam/minio-identity-plugin.rst

@@ -13,6 +13,14 @@ MinIO Identity Management Plugin Settings
 This page documents settings for enabling external identity management using the MinIO Identity Management Plugin. 
 See :ref:`minio-external-identity-management-plugin` for a tutorial on using these settings.
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-defined
+   :end-before: end-minio-settings-defined
+
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Examples
 --------
 

source/reference/minio-server/settings/iam/openid.rst

@@ -14,6 +14,14 @@ OpenID Identity Management Settings
 This page documents settings for enabling external identity management using an OpenID Connect (OIDC)-compatible provider. 
 See :ref:`minio-external-identity-management-openid` for a tutorial on using these settings.
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-defined
+   :end-before: end-minio-settings-defined
+
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Examples
 --------
 

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

@@ -19,6 +19,10 @@ The following environment variables control how the MinIO Server interacts with
 Define any 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
+
 .. 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.

source/reference/minio-server/settings/metrics-and-logging.rst

@@ -20,6 +20,10 @@ See :ref:`minio-logging` for more complete documentation.
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 - :ref:`minio-server-envvar-logging-regular`
 - :ref:`minio-server-envvar-logging-audit`
 - :ref:`minio-server-envvar-logging-audit-kafka`

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

@@ -17,6 +17,10 @@ This page covers settings that control behavior related to :ref:`MinIO bucket no
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Sync Events
 -----------
 

source/reference/minio-server/settings/notifications/amqp.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-amqp` for a tutorial on using these
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple AMQP Targets
 ---------------------
 

source/reference/minio-server/settings/notifications/elasticsearch.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-elasticsearch` for a tutorial on us
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple Elasticsearch Targets
 ------------------------------
 

source/reference/minio-server/settings/notifications/kafka.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-kafka` for a tutorial on using thes
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple Kafka Targets
 ----------------------
 

source/reference/minio-server/settings/notifications/mqtt.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-mqtt` for a tutorial on using these
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple MQTT Targets
 ---------------------
 

source/reference/minio-server/settings/notifications/mysql.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-mysql` for a tutorial on using thes
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple MYSQL Targets
 ----------------------
 

source/reference/minio-server/settings/notifications/nats.rst

@@ -26,6 +26,10 @@ See :ref:`minio-bucket-notifications-publish-nats` for a tutorial on using these
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple NATS Targets
 ---------------------
 

source/reference/minio-server/settings/notifications/nsq.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-nsq` for a tutorial on using these
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple NSQ Targets
 --------------------
 

source/reference/minio-server/settings/notifications/postgresql.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-postgresql` for a tutorial on using
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple PostgreSQL Targets
 ---------------------------
 

source/reference/minio-server/settings/notifications/redis.rst

@@ -18,6 +18,10 @@ See :ref:`minio-bucket-notifications-publish-redis` for a tutorial on using thes
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple Redis Targets
 ----------------------
 

source/reference/minio-server/settings/notifications/webhook-service.rst

@@ -19,6 +19,10 @@ See :ref:`minio-bucket-notifications-publish-webhook` for a tutorial on using th
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Multiple Webhook Service Targets
 --------------------------------
 

source/reference/minio-server/settings/object-lambda.rst

@@ -24,6 +24,10 @@ For example, the following command sets two distinct Object Lambda webhook endpo
    export MINIO_LAMBDA_WEBHOOK_ENABLE_yourfunction="on"
    export MINIO_LAMBDA_WEBHOOK_ENDPOINT_yourfunction="http://webhook-2.example.net"
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Environment Variables
 ---------------------
 

source/reference/minio-server/settings/root-credentials.rst

@@ -17,6 +17,10 @@ The root user has complete access and permissions to perform operations on the M
    :start-after: start-minio-settings-defined
    :end-before: end-minio-settings-defined
 
+.. include:: /includes/common-mc-admin-config.rst
+   :start-after: start-minio-settings-test-before-prod
+   :end-before: end-minio-settings-test-before-prod
+
 Root User
 ---------
 

source/reference/minio-server/settings/storage-class.rst

@@ -26,6 +26,10 @@ This impacts how MinIO uses the space on the drive(s) and how MinIO can recover
 Define any 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
+
 Environment Variables
 ---------------------