From d1791f50fe1b703f3526345352dd3bdba49c13e7 Mon Sep 17 00:00:00 2001 From: ravindk89 Date: Thu, 19 Aug 2021 12:36:59 -0400 Subject: [PATCH] Improving docs around Console config --- source/conf.py | 3 +- source/console/minio-console.rst | 65 ++++++++++++++----- .../installation/deploy-minio-distributed.rst | 10 ++- .../installation/deploy-minio-standalone.rst | 18 ++++- 4 files changed, 78 insertions(+), 18 deletions(-) diff --git a/source/conf.py b/source/conf.py index 3c5331cc..77a59296 100644 --- a/source/conf.py +++ b/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',''), } diff --git a/source/console/minio-console.rst b/source/console/minio-console.rst index 535862f3..cc0bb1ce 100644 --- a/source/console/minio-console.rst +++ b/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 MinIO Console by default uses the local hostname (i.e. ``$HOSTNAME``) - as the address for the MinIO server. You may need to set this variable - in the following scenarios: + - The URL hostname the MinIO Console uses for connecting to the MinIO + Server. The hostname *must* be resolveable and reachable for the + Console to function correctly. - - The MinIO server TLS certificates do not cover the local hostname - (i.e. in IP or DNS :abbr:`SAN (Subject Alternative Name)`) such that - the Console cannot validate the TLS certificates. - - Specify a hostname contained in the TLS certificate to allow the MinIO + 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 ` (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 - requests. Specify the load balancer URL corresponding to the - MinIO deployment. + - 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 @@ -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. \ No newline at end of file +MinIO SUBNET. diff --git a/source/installation/deploy-minio-distributed.rst b/source/installation/deploy-minio-distributed.rst index 03787068..78bf9525 100644 --- a/source/installation/deploy-minio-distributed.rst +++ b/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 `. + 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 - \ No newline at end of file + diff --git a/source/installation/deploy-minio-standalone.rst b/source/installation/deploy-minio-standalone.rst index a23e42b0..ad6a1a21 100644 --- a/source/installation/deploy-minio-standalone.rst +++ b/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 `. + 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 `. + 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. \ No newline at end of file +operations against the MinIO server.