Improving docs around Console config

source/conf.py

@@ -67,7 +67,8 @@ extlinks = {
     'legacy'          : ('https://docs.min.io/docs/%s',''),
     'docs-k8s'        : ('https://docs.min.io/minio/k8s/%s',''),
     'prometheus-docs' : ('https://prometheus.io/docs/%s',''),
-    'podman-docs'     : ('http://docs.podman.io/en/latest/%s',''),
+    'podman-docs'     : ('https://docs.podman.io/en/latest/%s',''),
+    'rfc'             : ('https://datatracker.ietf.org/doc/html/%s',''),
 
 }
 

source/console/minio-console.rst

@@ -64,25 +64,31 @@ the MinIO Console:
        configuring Prometheus to collect metrics from MinIO.
 
    * - :envvar:`MINIO_SERVER_URL`
-     - The URL hostname for the MinIO Server. 
+     - The URL hostname the MinIO Console uses for connecting to the MinIO 
-       
+       Server. The hostname *must* be resolveable and reachable for the
-       The MinIO Console by default uses the local hostname (i.e. ``$HOSTNAME``)
+       Console to function correctly.
-       as the address for the MinIO server. You may need to set this variable
-       in the following scenarios:
 
-       - The MinIO server TLS certificates do not cover the local hostname
+       The MinIO Console connects to the MinIO Server using an IP 
-         (i.e. in IP or DNS :abbr:`SAN (Subject Alternative Name)`) such that
+       address by default. For example, when the MinIO Server starts up, 
-         the Console cannot validate the TLS certificates.
+       the server logs include a line 
-         
+       ``API: https://<IP ADDRESS 1> https://<IP ADDRESS 2>``.
-         Specify a hostname contained in the TLS certificate to allow the MinIO
+       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 <rfc5280#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 hostname is not reachable by the MinIO
+       - The MinIO server's local IP address is not reachable by the MinIO
          Console. Specify a resolveable hostname for the MinIO Server.
 
-       - The MinIO deployment uses a load balancer for managing incoming
+       - A load balancer or reverse proxy controls traffic to the MinIO server,
-         requests. Specify the load balancer URL corresponding to the
+         such that the MinIO Console cannot reach the server without going
-         MinIO deployment.
+         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 
@@ -95,6 +101,35 @@ the MinIO Console:
        public internet. Specify an externally reachable hostname that resolves
        to the MinIO Console.
 
+Static vs Dynamic Port Assignment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MinIO by default selects a random port for the MinIO Console on each server
+startup. Browser clients accessing the MinIO Server are automatically 
+redirected to the MinIO Console on its dynamically selected port. 
+This behavior emulates the legacy web browser behavior while reducing the
+the risk of a port collision on systems which were running MinIO *before* the 
+embedded Console update.
+
+You can select an explicit static port by passing the 
+:mc-cmd-option:`minio server console-address` commandline option when starting 
+each MinIO Server in the deployment. 
+
+For example, the following command starts a distributed MinIO deployment using
+a static port assignment of ``9001`` for the MinIO Console. This deployment
+would respond to S3 API operations on the default MinIO server port ``:9000``
+and browser access on the MinIO Console port ``:9001``.
+
+.. code-block:: shell
+   :class: copyable
+
+   minio server https://minio-{1...4}.example.net/mnt/disk-{1...4} \
+         --console-address ":9001"
+
+Deployments behind network routing components which require static ports for 
+routing rules may require setting a static MinIO Console port. For example,
+load balancers, reverse proxies, or Kubernetes ingress may by default block
+or exhibit unexpected behavior with the the dynamic redirection behavior.
 
 Dashboard
 ---------
@@ -406,4 +441,4 @@ diagnostic report for supporting `MinIO SUBNET
 The Diagnostic file contains configuration information about the deployment
 and may therefore include private or confidential information about your
 infrastructure. Do **not** share this information outside of
-MinIO SUBNET. 
+MinIO SUBNET. 

source/installation/deploy-minio-distributed.rst

@@ -197,6 +197,7 @@ following example assumes that:
 
    export MINIO_ROOT_USER=minio-admin
    export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
+   #export MINIO_SERVER_URL=https://minio.example.net
    #export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
 
    minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data --console-address ":9001"
@@ -220,6 +221,13 @@ The example command breaks down as follows:
        Specify the *same* unique, random, and long string for all
        nodes in the deployment.
 
+   * - :envvar:`MINIO_SERVER_URL`
+     - The URL hostname the MinIO Console uses for connecting to the MinIO 
+       server. This variable is *required* if specifying TLS certificates
+       which **do not** contain the IP address of the MinIO Server host
+       as a :rfc:`Subject Alternative Name <rfc5280#section-4.2.1.6>`. 
+       Specify a hostname covered by one of the TLS certificate SAN entries.
+
    * - :envvar:`MINIO_KMS_SECRET_KEY`
      - The key to use for encrypting the MinIO backend (users, groups,
        policies, and server configuration). Single-key backend encryption
@@ -477,4 +485,4 @@ host:
 
    * - More than 1 Pebibyte (Pi)
      - 128GiB
-       
+       

source/installation/deploy-minio-standalone.rst

@@ -107,6 +107,7 @@ command:
 
    export MINIO_ROOT_USER=minio-admin
    export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
+   #export MINIO_SERVER_URL=https://minio.example.net
    #export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
 
    minio server /data --console-address ":9001"
@@ -128,6 +129,13 @@ The example command breaks down as follows:
 
        Replace this value with a unique, random, and long string.
 
+   * - :envvar:`MINIO_SERVER_URL`
+     - The URL hostname the MinIO Console uses for connecting to the MinIO 
+       server. This variable is *required* if specifying TLS certificates
+       which **do not** contain the IP address of the MinIO Server host
+       as a :rfc:`Subject Alternative Name <rfc5280#section-4.2.1.6>`. 
+       Specify a hostname covered by one of the TLS certificate SAN entries.
+
    * - :envvar:`MINIO_KMS_SECRET_KEY`
      - The key to use for encrypting the MinIO backend (users, groups,
        policies, and server configuration). Single-key backend encryption
@@ -248,6 +256,7 @@ following environment variables:
 
    export MINIO_ROOT_USER=minio-admin
    export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
+   #export MINIO_SERVER_URL=https://minio.example.net
    #export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
 
 Create the Podman secret using the ``config.env`` file:
@@ -274,6 +283,13 @@ The following table details each environment variable set in ``config.env``:
 
        Replace this value with a unique, random, and long string.
 
+   * - :envvar:`MINIO_SERVER_URL`
+     - The URL hostname the MinIO Console uses for connecting to the MinIO 
+       server. This variable is *required* if specifying TLS certificates
+       which **do not** contain the IP address of the MinIO Server host
+       as a :rfc:`Subject Alternative Name <rfc5280#section-4.2.1.6>`. 
+       Specify a hostname covered by one of the TLS certificate SAN entries.
+
    * - :envvar:`MINIO_KMS_SECRET_KEY`
      - The key to use for encrypting the MinIO backend (users, groups,
        policies, and server configuration). Single-key backend encryption
@@ -416,4 +432,4 @@ Server Configuration. Each MinIO server includes its own embedded MinIO
 Console.
 
 Applications should use the ``https://HOST-ADDRESS:9000`` to perform S3
-operations against the MinIO server.
+operations against the MinIO server.