mirror of
https://github.com/minio/docs.git
synced 2025-07-30 07:03:26 +03:00
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>
This commit is contained in:
Ravind Kumar
GitHub
@ -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
|
||||
--------------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
@ -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.
|
||||
2. Modify configuration options using the :mc:`mc admin config` command or the :guilabel:`Administrator > Settings` page of the :ref:`MinIO Console <minio-console>`.
|
||||
|
||||
.. important::
|
||||
|
||||
Settings defined by an environment variable override similar settings defined as configurations with :mc:`mc admin config` or the MinIO Console.
|
||||
.. include:: /includes/common-mc-admin-config.rst
|
||||
:start-after: start-minio-settings-test-before-prod
|
||||
:end-before: end-minio-settings-test-before-prod
|
||||
|
||||
Additional settings include those to customize:
|
||||
|
||||
|
||||
@ -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
|
||||
----------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
|
||||
@ -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
|
||||
--------
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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
|
||||
-----------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
@ -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
|
||||
------------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
----------------------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
@ -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
|
||||
----------------------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
@ -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
|
||||
--------------------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
----------------------
|
||||
|
||||
|
||||
@ -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
|
||||
--------------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
@ -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
|
||||
---------
|
||||
|
||||
|
||||
@ -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
|
||||
---------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user