From e3e9caf593cc246d04fda9a149379b2594e68fb8 Mon Sep 17 00:00:00 2001 From: ravindk89 Date: Tue, 29 Sep 2020 18:57:09 -0400 Subject: [PATCH] Alpha Release Work --- source/_static/css-style.css | 74 +++- source/_static/js/main.js | 62 +-- source/_templates/navigation.html | 2 + source/_templates/searchbox.html | 11 + .../bare-metal/minio-baremetal-overview.rst | 363 ++++++++++++++++++ source/conf.py | 4 +- source/includes/minio-server-installation.rst | 96 +++++ source/index.rst | 8 +- source/introduction/buckets.rst | 75 ---- source/introduction/deployment-topologies.rst | 6 +- source/introduction/erasure-coding.rst | 2 + source/introduction/minio-overview.rst | 67 ++-- source/introduction/objects.rst | 15 - source/kubernetes/deploy-on-kubernetes.rst | 87 ----- source/kubernetes/enforce-security.rst | 113 ------ source/kubernetes/manage-on-kubernetes.rst | 77 ---- .../kubernetes/minio-kubernetes-overview.rst | 27 ++ source/kubernetes/minio-kubernetes.rst | 41 -- source/kubernetes/operator-kes.rst | 79 ---- source/kubernetes/operator-mcs.rst | 74 ---- source/kubernetes/operator-reference.rst | 133 ------- source/kubernetes/quickstart.rst | 229 ----------- source/meta/404.rst | 7 + source/minio-cli/minio-mc-admin.rst | 10 +- .../minio-mc-admin/mc-admin-bucket-quota.rst | 2 +- .../minio-mc-admin/mc-admin-bucket-remote.rst | 2 +- .../minio-mc-admin/mc-admin-console.rst | 2 +- .../minio-mc-admin/mc-admin-groups.rst | 2 +- .../minio-mc-admin/mc-admin-heal.rst | 2 +- .../minio-mc-admin/mc-admin-info.rst | 2 +- .../minio-cli/minio-mc-admin/mc-admin-kms.rst | 2 +- .../minio-cli/minio-mc-admin/mc-admin-obd.rst | 2 +- .../minio-mc-admin/mc-admin-policy.rst | 2 +- .../minio-mc-admin/mc-admin-profile.rst | 2 +- .../minio-mc-admin/mc-admin-prometheus.rst | 2 +- .../minio-mc-admin/mc-admin-service.rst | 2 +- .../minio-cli/minio-mc-admin/mc-admin-top.rst | 2 +- .../minio-mc-admin/mc-admin-trace.rst | 2 +- .../minio-mc-admin/mc-admin-update.rst | 2 +- .../minio-mc-admin/mc-admin-user.rst | 2 +- source/minio-cli/minio-mc.rst | 53 +-- source/minio-cli/minio-mc/mc-alias.rst | 122 +++--- source/minio-cli/minio-mc/mc-cat.rst | 2 +- source/minio-cli/minio-mc/mc-cp.rst | 2 +- source/minio-cli/minio-mc/mc-diff.rst | 2 +- source/minio-cli/minio-mc/mc-encrypt.rst | 2 +- source/minio-cli/minio-mc/mc-event.rst | 2 +- source/minio-cli/minio-mc/mc-find.rst | 2 +- source/minio-cli/minio-mc/mc-head.rst | 2 +- source/minio-cli/minio-mc/mc-ilm.rst | 2 +- source/minio-cli/minio-mc/mc-legalhold.rst | 2 +- source/minio-cli/minio-mc/mc-lock.rst | 2 +- source/minio-cli/minio-mc/mc-ls.rst | 2 +- source/minio-cli/minio-mc/mc-mb.rst | 2 +- source/minio-cli/minio-mc/mc-mirror.rst | 2 +- source/minio-cli/minio-mc/mc-mv.rst | 2 +- source/minio-cli/minio-mc/mc-policy.rst | 2 +- source/minio-cli/minio-mc/mc-rb.rst | 2 +- source/minio-cli/minio-mc/mc-retention.rst | 2 +- source/minio-cli/minio-mc/mc-rm.rst | 2 +- source/minio-cli/minio-mc/mc-share.rst | 2 +- source/minio-cli/minio-mc/mc-sql.rst | 2 +- source/minio-cli/minio-mc/mc-stat.rst | 2 +- source/minio-cli/minio-mc/mc-tag.rst | 2 +- source/minio-cli/minio-mc/mc-tree.rst | 2 +- source/minio-cli/minio-mc/mc-update.rst | 2 +- source/minio-cli/minio-mc/mc-version.rst | 2 +- source/minio-cli/minio-mc/mc-watch.rst | 2 +- source/minio-features/bucket-versioning.rst | 2 +- source/minio-server/minio-server.rst | 323 ++++++++++++++++ .../minio-authentication-authorization.rst | 6 +- .../minio-security-TLS-encryption.rst | 4 +- .../minio-security-security-token-service.rst | 2 +- .../minio-security-server-side-encryption.rst | 2 +- source/security/minio-security.rst | 2 +- sphinxext/minio.py | 5 +- 76 files changed, 1115 insertions(+), 1152 deletions(-) create mode 100644 source/_templates/navigation.html create mode 100644 source/_templates/searchbox.html create mode 100644 source/bare-metal/minio-baremetal-overview.rst create mode 100644 source/includes/minio-server-installation.rst delete mode 100644 source/introduction/buckets.rst delete mode 100644 source/introduction/objects.rst delete mode 100644 source/kubernetes/deploy-on-kubernetes.rst delete mode 100644 source/kubernetes/enforce-security.rst delete mode 100644 source/kubernetes/manage-on-kubernetes.rst create mode 100644 source/kubernetes/minio-kubernetes-overview.rst delete mode 100644 source/kubernetes/minio-kubernetes.rst delete mode 100644 source/kubernetes/operator-kes.rst delete mode 100644 source/kubernetes/operator-mcs.rst delete mode 100644 source/kubernetes/operator-reference.rst delete mode 100644 source/kubernetes/quickstart.rst create mode 100644 source/meta/404.rst create mode 100644 source/minio-server/minio-server.rst diff --git a/source/_static/css-style.css b/source/_static/css-style.css index 54b181a4..cd1b36c6 100644 --- a/source/_static/css-style.css +++ b/source/_static/css-style.css @@ -22,7 +22,7 @@ html { body { font-family: Mark, Helvetica, sans-serif; - font-size: 100%; + font-size: 15px; } div.flexwrapper { @@ -41,20 +41,32 @@ body :target { /* Left Column CSS */ body div.left { - width: 250px; + width: 300px; /* flex-shrink: 0; */ position: fixed; display: block; left: 0px; - top: 85px; + top: 90px; color: var(--minio-meridian); z-index: 5; - border-right: 1px solid var(--minio-glacier); + background: #f9f9f9 0% 0% no-repeat padding-box; + opacity: 1; + height: 100vh; +} + +body div.left a.active { + color: var(--minio-meridian); } body div.left li.toctree-l1 a { - color: var(--minio-meridian); + color: #1C1C1C; } + +body div.left li.toctree-l2 a { + color: #2b2b2b; + font-size: 14px; +} + body div.left div.sphinxsidebarwrapper { padding: 0 0 0 5px; margin-top: 15px; @@ -70,17 +82,15 @@ body div.left button.sphinxsidebarbutton { background: none; border: none; position: fixed; - left: 115px; - top: 75px; + left: 200px; + top: 90px; + color: gray; } body div.left div.sphinxsidebarwrapper a.current.reference.internal { color: var(--minio-red); font-weight: bold; position: relative; - border-left: 5px solid var(--minio-red); - padding-left: 5px; - margin-left: -10px; } @@ -93,7 +103,6 @@ body div.left div.sphinxsidebarwrapper li.toctree-l1 { margin-top: 10px; margin-bottom: 10px; padding-bottom: 5px; - border-bottom: 1px solid var(--table-border-color); list-style: none; } @@ -102,7 +111,17 @@ body div.left a.reference { border: none; } +body div.left li.toctree-l2 { + margin: 10px 0 10px 0; +} +body div.left div.searchformwrapper { + margin-top: 25px; +} + +#docs-search { + padding-left: 10px; +} /* Center Column CSS */ @@ -122,8 +141,8 @@ body div.center { flex-grow: 9; flex-shrink: 4; z-index: 0; - margin-left: 250px; - margin-top: 85px; + margin-left: 300px; + margin-top: 90px; scroll-margin-top: 85px; height: 100%; padding-left: 10px; @@ -194,8 +213,22 @@ body div.center table.docutils th { border-right: none; } -body div.center p { - padding-left: 10px; +body div.center dl dd { + margin-left: 15px; +} + +body div.center div.footer { + text-align: center; + width: auto; + /* + Future work: Force padding up so that H3s can still scroll within the + IntersectionObserver window. Useful for ensuring short sections at the + bottom of the page still get picked up. Might be useful for auto-hide of + l2 content. + + + padding-top: 100px; + */ } /* Right-Column CSS */ @@ -204,8 +237,9 @@ body div.right { flex: 3; flex-shrink: 0; margin-left: 10px; - margin-top: 85px; + margin-top: 90px; border-left: 1px solid var(--minio-glacier); + font-size: 13px; } body div.right div.topic { @@ -223,8 +257,6 @@ body div.right ul.simple { } body div.right ul li { - border-top: 1px solid var(--minio-glacier); - border-bottom: 1px solid var(--minio-glacier); padding-top: 5px; padding-bottom: 5px; } @@ -253,7 +285,7 @@ body div.right p.active-p { /* Collapse CSS */ body div.left.collapsed { - left: -300px; + left: -350px; } body div.left button.sphinxsidebarbutton.collapsed { @@ -278,9 +310,9 @@ nav.navigation { position: fixed; background-color: black; width: 100%; - height: 75px; + height: 90px; top: 0px; z-index: 1; } -/* Admonition CSS TODO*/ \ No newline at end of file +/* Admonition CSS TODO*/ diff --git a/source/_static/js/main.js b/source/_static/js/main.js index 8b5c3c82..b984cade 100644 --- a/source/_static/js/main.js +++ b/source/_static/js/main.js @@ -1,11 +1,11 @@ window.addEventListener('DOMContentLoaded', (event) => { console.log('DOM fully loaded and parsed'); - var topic = document.getElementById('on-this-page'); + var topic = document.getElementById('table-of-contents'); if (topic != null) { document.getElementById('localtoc').appendChild( - document.getElementById('on-this-page') + document.getElementById('table-of-contents') ); console.log("moving local toc"); @@ -17,45 +17,47 @@ window.addEventListener('DOMContentLoaded', (event) => { // this from working, especially if the 'section' is really long. Not sure // how to resolve that. - let options = { - rootMargin: '-85px 0px 0px 0px' - } + // Removing this from the logic flow until we have better / cleaner logic. - const observer = new IntersectionObserver(entries => { - entries.forEach(entry => { - const id = entry.target.getAttribute('id'); +// let options = { +// rootMargin: '-100px 0px 0px -100px' +// } + +// const observer = new IntersectionObserver(entries => { +// entries.forEach(entry => { +// const id = entry.target.getAttribute('id'); - if (id == document.querySelector('.section[id]').getAttribute('id')) - return 0 - if (entry.intersectionRatio > 0) { +// if (id == document.querySelector('.section[id]').getAttribute('id')) +// return 0 +// if (entry.intersectionRatio > 0) { - pElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement; - liElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement; +// pElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement; +// liElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement; - liElement.classList.add('active'); - pElement.classList.add('active-p'); +// liElement.classList.add('active'); +// pElement.classList.add('active-p'); - liElementParent = liElement.parentElement.parentElement +// liElementParent = liElement.parentElement.parentElement - if (liElementParent.tagName == "LI") { - //liElementParent.classList.remove("active") - // Need to re-visit this logic - } +// if (liElementParent.tagName == "LI") { +// //liElementParent.classList.remove("active") +// // Need to re-visit this logic +// } - } else { - document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement.classList.remove('active'); - document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.classList.remove('active-p'); - } - }); - },options); +// } else { +// document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement.classList.remove('active'); +// document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.classList.remove('active-p'); +// } +// }); +// },options); - // Track all sections that have an `id` applied - document.querySelectorAll('.section[id]').forEach((section) => { - observer.observe(section); - }); +// // Track all sections that have an `id` applied +// document.querySelectorAll('.section[id]').forEach((section) => { +// observer.observe(section); +// }); const leftcolumn = document.querySelector('.left'); const centercolumn = document.querySelector('.center'); diff --git a/source/_templates/navigation.html b/source/_templates/navigation.html new file mode 100644 index 00000000..4add54b9 --- /dev/null +++ b/source/_templates/navigation.html @@ -0,0 +1,2 @@ + +{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse) }} \ No newline at end of file diff --git a/source/_templates/searchbox.html b/source/_templates/searchbox.html new file mode 100644 index 00000000..27ea5974 --- /dev/null +++ b/source/_templates/searchbox.html @@ -0,0 +1,11 @@ +{%- if pagename != "search" and builder != "singlehtml" %} + + +{%- endif %} \ No newline at end of file diff --git a/source/bare-metal/minio-baremetal-overview.rst b/source/bare-metal/minio-baremetal-overview.rst new file mode 100644 index 00000000..7f289a7e --- /dev/null +++ b/source/bare-metal/minio-baremetal-overview.rst @@ -0,0 +1,363 @@ +.. _minio-baremetal: + +==================== +MinIO for Bare Metal +==================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +MinIO is a high performance distributed object storage server, designed for +large-scale private cloud infrastructure. MinIO fully supports deployment onto +bare-metal hardware with or without containerization for process management. + +Standalone Installation +----------------------- + +Standalone MinIO deployments consist of a single ``minio`` server process with +one or more disks. Standalone deployments are best suited for local development +environments. + +1) Install the ``minio`` Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install the :program:`minio` server onto the host machine. Select the tab that +corresponds to the host machine operating system or environment: + +.. include:: /includes/minio-server-installation.rst + +2) Add TLS/SSL Certificates (Optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enable TLS/SSL connectivity to the MinIO server by specifying a private key +(``.key``) and public certificate (``.crt``) to the MinIO ``certs`` directory: + +- For Linux/MacOS: ``${HOME}/.minio/certs`` + +- For Windows: ``%%USERPROFILE%%\.minio\certs`` + +The MinIO server automatically enables TLS/SSL connectivity if it detects +the required certificates in the ``certs`` directory. + +.. note:: + + The MinIO documentation makes a best-effort to provide generally applicable + and accurate information on TLS/SSL connectivity in the context of MinIO + products and services, and is not intended as a complete guide to the larger + topic of TLS/SSL certificate creation and management. + +3) Run the ``minio`` Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Issue the following command to start the :program:`minio` server. The following +example assumes the host machine has *at least* four disks, which is the minimum +required number of disks to enable :ref:`erasure coding `: + +.. code-block:: shell + :class: copyable + + export MINIO_ACCESS_KEY=minio-admin + export MINIO_SECRET_KEY=minio-secret-key-CHANGE-ME + minio server /mnt/disk{1...4}/data + +The example command breaks down as follows: + +.. list-table:: + :widths: 40 60 + :width: 100% + + * - :envvar:`MINIO_ACCESS_KEY` + - The access key for the :ref:`root ` user. + + Replace this value with a unique, random, and long string. + + * - :envvar:`MINIO_SECRET_KEY` + - The corresponding secret key to use for the + :ref:`root ` user. + + Replace this value with a unique, random, and long string. + + * - ``/mnt/disk{1...4}/data`` + - The path to each disk on the host machine. + + ``/data`` is an optional folder in which the ``minio`` server stores + all information related to the deployment. + + See :mc-cmd:`minio server DIRECTORIES` for more information on + configuring the backing storage for the :mc:`minio server` process. + +The command uses MinIO expansion notation ``{x...y}`` to denote a sequential +series. Specifically, ``/mnt/disk{1...4}/data`` expands to: + +- ``/mnt/disk1/data`` +- ``/mnt/disk2/data`` +- ``/mnt/disk3/data`` +- ``/mnt/disk4/data`` + +4) Connect to the Server +~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :mc-cmd:`mc alias set` command from a machine with connectivity to +the host running the ``minio`` server. See :ref:`mc-install` for documentation +on installing :program:`mc`. + +.. code-block:: shell + :class: copyable + + mc alias set mylocalminio 192.0.2.10:9000 minioadmin minio-secret-key-CHANGE-ME + +Replace the IP address and port with one of the ``minio`` servers endpoints. + +See :ref:`minio-mc-commands` for a list of commands you can run on the +MinIO server. + +Distributed Installation +------------------------ + +Distributed MinIO deployments consist of multiple ``minio`` servers with +one or more disks each. Distributed deployments are best suited for +staging and production environments. + +MinIO *requires* using sequentially-numbered hostnames to represent each +``minio`` server in the deployment. For example, the following hostnames support +a 4-node distributed deployment: + +- ``minio1.example.com`` +- ``minio2.example.com`` +- ``minio3.example.com`` +- ``minio4.example.com`` + +Create the necessary DNS hostname mappings *prior* to starting this +procedure. + +1) Install the ``minio`` Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install the :program:`minio` server onto each host machine in the deployment. +Select the tab that corresponds to the host machine operating system or +environment: + +.. include:: /includes/minio-server-installation.rst + +2) Add TLS/SSL Certificates (Optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enable TLS/SSL connectivity to the MinIO server by specifying a private key +(``.key``) and public certificate (``.crt``) to the MinIO ``certs`` directory: + +- For Linux/MacOS: ``${HOME}/.minio/certs`` + +- For Windows: ``%%USERPROFILE%%\.minio\certs`` + +The MinIO server automatically enables TLS/SSL connectivity if it detects +the required certificates in the ``certs`` directory. + +.. note:: + + The MinIO documentation makes a best-effort to provide generally applicable + and accurate information on TLS/SSL connectivity in the context of MinIO + products and services, and is not intended as a complete guide to the larger + topic of TLS/SSL certificate creation and management. + +3) Run the ``minio`` Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Issue the following command on each host machine in the deployment. The +following example assumes that: + +- The deployment has four host machines with sequential hostnames + (i.e. ``minio1.example.com``, ``minio2.example.com``). + +- Each host machine has *at least* four disks mounted at ``/data``. 4 disks is + the minimum required for :ref:`erasure coding + `. + +.. code-block:: shell + :class: copyable + + export MINIO_ACCESS_KEY=minio-admin + export MINIO_SECRET_KEY=minio-secret-key-CHANGE-ME + minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data + +The example command breaks down as follows: + +.. list-table:: + :widths: 40 60 + :width: 100% + + * - :envvar:`MINIO_ACCESS_KEY` + - The access key for the :ref:`root ` user. + + Replace this value with a unique, random, and long string. + + * - :envvar:`MINIO_SECRET_KEY` + - The corresponding secret key to use for the + :ref:`root ` user. + + Replace this value with a unique, random, and long string. + + * - ``https://minio{1...4}.example.com/`` + - The DNS hostname of each server in the distributed deployment. + + * - ``/mnt/disk{1...4}/data`` + - The path to each disk on the host machine. + + ``/data`` is an optional folder in which the ``minio`` server stores + all information related to the deployment. + + See :mc-cmd:`minio server DIRECTORIES` for more information on + configuring the backing storage for the :mc:`minio server` process. + +The command uses MinIO expansion notation ``{x...y}`` to denote a sequential +series. Specifically: + +- The hostname ``https://minio{1...4}.example.com`` expands to: + + - ``https://minio1.example.com`` + - ``https://minio2.example.com`` + - ``https://minio3.example.com`` + - ``https://minio4.example.com`` + +- ``/mnt/disk{1...4}/data`` expands to + + - ``/mnt/disk1/data`` + - ``/mnt/disk2/data`` + - ``/mnt/disk3/data`` + - ``/mnt/disk4/data`` + +4) Connect to the Server +~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :mc-cmd:`mc alias set` command from a machine with connectivity to any +hostname running the ``minio`` server. See :ref:`mc-install` for documentation +on installing :program:`mc`. + +.. code-block:: shell + :class: copyable + + mc alias set mylocalminio minio1.example.net minioadmin minio-secret-key-CHANGE-ME + +See :ref:`minio-mc-commands` for a list of commands you can run on the +MinIO server. + +Docker Installation +------------------- + +Stable MinIO +~~~~~~~~~~~~ + +The following ``docker`` command creates a container running the latest stable +version of the ``minio`` server process: + +.. code-block:: shell + :class: copyable + + docker run -p 9000:9000 \ + -e "MINIO_ACCESS_KEY=ROOT_ACCESS_KEY" \ + -e "MINIO_SECRET_KEY=SECRET_ACCESS_KEY_CHANGE_ME" \ + -v /mnt/disk1:/disk1 \ + -v /mnt/disk2:/disk2 \ + -v /mnt/disk3:/disk3 \ + -v /mnt/disk4:/disk4 \ + minio/minio server /disk{1...4} + +The command uses the following options: + +- ``-e MINIO_ACCESS_KEY`` and ``-e MINIO_SECRET_KEY`` for configuring the + :ref:`root ` user credentials. + +- ``-v /mnt/disk:/disk`` for configuring each disk the ``minio`` + server uses. + +Bleeding Edge MinIO +~~~~~~~~~~~~~~~~~~~ + +*Do not use bleeding-edge deployments of MinIO in production environments* + +The following ``docker`` command creates a container running the latest +bleeding-edge version of the ``minio`` server process: + +.. code-block:: shell + :class: copyable + + docker run -p 9000:9000 \ + -e "MINIO_ACCESS_KEY=ROOT_ACCESS_KEY" \ + -e "MINIO_SECRET_KEY=SECRET_ACCESS_KEY_CHANGE_ME" \ + -v /mnt/disk1:/disk1 \ + -v /mnt/disk2:/disk2 \ + -v /mnt/disk3:/disk3 \ + -v /mnt/disk4:/disk4 \ + minio/minio:edge server /disk{1...4} + +The command uses the following options: + +- ``MINIO_ACCESS_KEY`` and ``MINIO_SECRET_KEY`` for configuring the + :ref:`root ` user credentials. + +- ``-v /mnt/disk:/disk`` for configuring each disk the ``minio`` + server uses. + +Deployment Recommendations +-------------------------- + +Minimum Nodes per Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For all production deployments, MinIO recommends a *minimum* of 4 nodes per +cluster. MinIO deployments with *at least* 4 nodes can tolerate the loss of up +to half the nodes *or* half the disks in the deployment while maintaining +read and write availability. + +For example, assuming a 4-node deployment with 4 drives per node, the +cluster can tolerate the loss of: + +- Any two nodes, *or* +- Any 8 drives. + +The minimum recommendation reflects MinIO's experience with assisting enterprise +customers in deploying on a variety of IT infrastructures while +maintaining the desired SLA/SLO. While MinIO may run on less than the +minimum recommended topology, any potential cost savings come at the risk of +decreased reliability. + +Recommended Hardware +~~~~~~~~~~~~~~~~~~~~ + +For MinIO's recommended hardware, please see +`MinIO Reference Hardware `__. + +Bare Metal Infrastructure +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A distributed MinIO deployment can only provide as much availability as the +bare metal infrastructure on which it is deployed. In particular, consider the +following potential failure points which could result in cluster downtime +when configuring your bare metal infrastructure: + +- Shared networking resources (switches, routers, ISP). +- Shared power resources. +- Shared physical location (rack, datacenter, region). + +MinIO deployments using virtual machines or containerized environments should +also consider the following: + +- Shared physical hardware (CPU, Memory, Storage) +- Shared orchestration management layer (Kubernetes, Docker Swarm) + +FreeBSD +------- + +MinIO does not provide an official FreeBSD binary. FreeBSD maintains an +`upstream release `__ you can +install using `pkg `__: + +.. code-block:: shell + :class: copyable + + pkg install minio + sysrc minio_enable=yes + sysrc minio_disks=/path/to/disks + service minio start \ No newline at end of file diff --git a/source/conf.py b/source/conf.py index a87ec954..4f7964c6 100644 --- a/source/conf.py +++ b/source/conf.py @@ -85,14 +85,14 @@ html_favicon = '_static/favicon.png' html_sidebars = { '**' : [ - 'about.html', - 'navigation.html', 'searchbox.html', + 'navigation.html', ] } html_theme_options = { 'fixed_sidebar' : 'true', + 'show_relbars': 'true', } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/source/includes/minio-server-installation.rst b/source/includes/minio-server-installation.rst new file mode 100644 index 00000000..c563e3ae --- /dev/null +++ b/source/includes/minio-server-installation.rst @@ -0,0 +1,96 @@ +.. tabs:: + + .. tab:: Linux + + The following commands add a *temporary* extension to your system + PATH for running the ``minio`` utility. Defer to your operating system + instructions for making permanent modifications to your system PATH. + + Alternatively, execute ``minio`` by navigating to the download folder and + running ``./minio --help`` + + **64-bit Intel** + + .. code-block:: shell + :class: copyable + + curl https://dl.min.io/server/minio/release/linux-amd64/minio \ + --create-dirs \ + -o $HOME/minio-binaries/minio + + chmod +x $HOME/minio-binaries/minio + export PATH=$PATH:$HOME/minio-binaries/ + + minio --help + + **64-bit PPC** + + .. code-block:: shell + :class: copyable + + curl https://dl.min.io/server/minio/release/linux-ppc64le/minio \ + --create-dirs \ + -o $HOME/minio-binaries/minio + + chmod +x $HOME/minio-binaries/minio + export PATH=$PATH:$HOME/minio-binaries/ + + minio --help + + .. tab:: macOS + + + **Homebrew** + + .. code-block:: shell + :class: copyable + + brew install minio/stable/minio + minio --help + + **Binary Download** + + .. code-block:: shell + :class: copyable + + curl https://dl.min.io/server/minio/release/darwin-amd64/minio \ + --create-dirs \ + -o $HOME/minio-binaries/minio + + chmod +x $HOME/minio-binaries/minio + export PATH=$PATH:$HOME/minio-binaries/ + + + .. tab:: Windows + + Open the following file in a browser: + + https://dl.min.io/server/minio/release/windows-amd64/minio.exe + + Execute the file by double clicking on it, *or* by running the + following in the command prompt or powershell: + + .. code-block:: powershell + + \path\to\mc.exe --help + + .. tab:: Source + + Installation from source is intended for developers and advanced users + and requires a working Golang environment. See + `How to install Golang `__. + + Run the following commands in a terminal environment to install ``minio`` + from source: + + .. code-block:: shell + :class: copyable + + go get -d github.com/minio/minio + cd ${GOPATH}/src/github.com/minio/minio + make + + To update a source-based installation, use ``go get -u``. + :mc-cmd:`minio update` does not support source-based installations. + + diff --git a/source/index.rst b/source/index.rst index e61500cb..81f62885 100644 --- a/source/index.rst +++ b/source/index.rst @@ -12,15 +12,17 @@ First-time users of MinIO *or* object storage services should start with our :doc:`Introduction `. Users deploying onto a Kubernetes cluster should start with our -:doc:`Kubernetes-specific documentation `. +:doc:`Kubernetes documentation `. .. toctree:: :titlesonly: :hidden: /introduction/minio-overview - /minio-features/overview.rst - /kubernetes/minio-kubernetes + /minio-features/overview + /bare-metal/minio-baremetal-overview + /kubernetes/minio-kubernetes-overview /security/minio-security /minio-cli/minio-mc /minio-cli/minio-mc-admin + /minio-server/minio-server diff --git a/source/introduction/buckets.rst b/source/introduction/buckets.rst deleted file mode 100644 index c1cadb47..00000000 --- a/source/introduction/buckets.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _minio-bucket: - -======= -Buckets -======= - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - - -A :ref:`bucket ` is a folder or storage container that can hold an -arbitrary number of :ref:`objects `. Minio buckets provide the -same functionality as an Amazon Web Services (AWS) S3 Bucket. The MinIO API is -fully compatible with the Amazon S3 API, where applications can seamlessly -transition to using the MinIO deployment with minimal code changes. - -Bucket Notifications --------------------- - -MinIO Bucket Notifications allow you to automatically publish notifications -to one or more configured endpoints when specific events occur in a bucket. - -See :doc:`/minio-features/bucket-notifications` for more information. - -Push Notifications -~~~~~~~~~~~~~~~~~~ - -MinIO supports pushing events to the following targets: - -- AMQP -- MQTT -- Elasticsearch -- NSQ -- Redis -- NATS -- PostgreSQL -- MySQL -- Apache Kafka -- Webhooks - -Use the ``mc admin`` utility to configure the MinIO deployment to actively -push notifications to each configured target. For more complete documentation, -see - -Listener API -~~~~~~~~~~~~ - -MinIO provides two routes to listen for events for a given bucket: - -- The ``mc event`` command. -- The ``BucketNotification`` API. - -.. todo: Add more information here as its available. - -Write Once Read Many (WORM) ---------------------------- - -MinIO supports enabling Write-Once Read-Many (WORM) for specific objects -in a bucket *or* for all objects in the bucket. Objects with WORM applied -are immutable, and can only be deleted if the WORM configuration includes an -expiry. - -Configure WORM for Bucket -~~~~~~~~~~~~~~~~~~~~~~~~~ - -ToDo: Enable, Disable WORM - -Configure WORM for Specific Objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ToDo: Enable, Disable WORM per object - diff --git a/source/introduction/deployment-topologies.rst b/source/introduction/deployment-topologies.rst index 2122e1dc..f4d25afd 100644 --- a/source/introduction/deployment-topologies.rst +++ b/source/introduction/deployment-topologies.rst @@ -2,6 +2,8 @@ Deployment Topologies ===================== +.. default-domain:: minio + MinIO supports three deployment topologies: .. list-table:: @@ -25,7 +27,7 @@ MinIO supports three deployment topologies: * - :ref:`Active-Active ` - Multiple distributed deployments with intra-deployment - replication to synchronize :ref:`objects ` across + replication to synchronize :ref:`objects ` across deployments. Active-Active Distributed deployments are ideal for production @@ -43,6 +45,7 @@ TBD: - Link to deployment tutorials (kubernetes, bare-metal) .. _minio-deployment-distributed: +.. _minio-zones: Distributed Deployment ---------------------- @@ -51,6 +54,7 @@ TBD: - Add a diagram of a distributed deployment - List the drawbacks (if any) - Link to deployment tutorials (kubernetes, bare-metal) +- Discuss horizontal expansion / zones .. _minio-deployment-active-active: diff --git a/source/introduction/erasure-coding.rst b/source/introduction/erasure-coding.rst index 2b71e46a..67cdfe7b 100644 --- a/source/introduction/erasure-coding.rst +++ b/source/introduction/erasure-coding.rst @@ -4,6 +4,8 @@ Erasure Coding ============== +.. default-domain:: minio + MinIO protects data with per-object, inline erasure coding, which is written in assembly code to deliver the highest performance possible. MinIO uses Reed-Solomon code to stripe objects into `n/2` data and ``n/2`` parity blocks - diff --git a/source/introduction/minio-overview.rst b/source/introduction/minio-overview.rst index d280d41f..fe6867c6 100644 --- a/source/introduction/minio-overview.rst +++ b/source/introduction/minio-overview.rst @@ -2,6 +2,8 @@ Introduction ============ +.. default-domain:: minio + MinIO is a High Performance Object Storage released under Apache License v2.0. It is API compatible with Amazon S3 cloud storage service. Use MinIO to build high performance infrastructure for machine learning, analytics and application @@ -10,50 +12,55 @@ data workloads. What Is Object Storage? ----------------------- -Applications create, update, retrieve, and delete data as part of normal -operations. MinIO provides a complete solution for managing the storage -and access of that data as :ref:`objects `. Applications group -objects into one or more :ref:`buckets `. +.. _objects: -MinIO is fully compatible with the Amazon Web Services Simple Storage Service -(AWS S3) API. Applications using the AWS S3 API can seamlessly transition to -using a MinIO deployment for managing their application's object storage with -minimal code changes. +An :ref:`object ` is binary data, sometimes referred to as a Binary +Large OBject (BLOB). Blobs can be images, audio files, spreadsheets, or even +binary executable code. Object Storage platforms like MinIO provide dedicated +tools and capabilities for storing, retrieving, and searching for blobs. -Erasure Coding --------------- +.. _buckets: -MinIO Erasure Coding guarantees object retrieval as long as the deployment -has at least half of its drives operational. Specifically, the deployment -can lose `(n/2)-1` drives and still service create, retrieval, update, and -delete operations. +MinIO Object Storage uses :ref:`buckets ` to organize objects. +A bucket is similar to a folder or directory in a filesystem, where each +bucket can hold an arbitrary number of objects. MinIO buckets provide the +same functionality as AWS S3 buckets. -For example, consider a deployment with 12 data drives. MinIO splits the -12 drive set into 6 data drives and 6 parity drives. As long as *at least* 7 -drives are online, the MinIO server can guarantee retrieval of any stored -object. +For example, consider an application that hosts a web blog. The application +needs to store a variety of blobs, including rich multimedia like videos and +images. The structure of objects on the MinIO server might look similar to the +following: -For more information on MinIO Erasure Coding, see -:ref:`minio-erasure-coding`. +.. code-block:: shell -Bitrot Protection ------------------ + / #root + /images/ + 2020-01-02-blog-title.png + 2020-01-03-blog-title.png + /videos/ + 2020-01-03-blog-cool-video.mp4 + /blogs/ + 2020-01-02-blog.md + 2020-01-03-blog.md + /comments/ + 2020-01-02-blog-comments.json + 2020-01-02-blog-comments.json -MinIO Bitrot Protection heals objects that have degraded due to -disk corruption. When applications request a specific object, MinIO -automatically checks for corruption and applies a healing algorithm to -reconstruct the object. +Deploying MinIO +--------------- -For more information on MinIO Bitrot Protection, see -:ref:`minio-bitrot-protection`. +For Kubernetes clusters, use the MinIO Kubernetes Operator. +See :ref:`minio-kubernetes` for more information. +For bare-metal environments, including private cloud services +or containerized environments, install and run the :mc:`minio server` on +each host in the MinIO deployment. See :ref:`minio-baremetal` for more +information. .. toctree:: :hidden: :titlesonly: - /introduction/buckets.rst - /introduction/objects.rst /introduction/deployment-topologies.rst /introduction/erasure-coding.rst /introduction/bitrot-protection.rst \ No newline at end of file diff --git a/source/introduction/objects.rst b/source/introduction/objects.rst deleted file mode 100644 index 24735482..00000000 --- a/source/introduction/objects.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _minio-object: - -======= -Objects -======= - -An :ref:`object ` is any kind of data with no limit to its -size, format, or type. Examples of objects include digital images, -text documents, or video files. Applications can store, retrieve, and -delete objects from a MinIO deployment. - -MinIO objects provide the same core functionality as an Amazon Web Services (AWS) -S3 Object. The MinIO API is fully compatible with the Amazon S3 API, -where applications can seamlessly transition to using the MinIO deployment -with minimal code changes. \ No newline at end of file diff --git a/source/kubernetes/deploy-on-kubernetes.rst b/source/kubernetes/deploy-on-kubernetes.rst deleted file mode 100644 index f6997f19..00000000 --- a/source/kubernetes/deploy-on-kubernetes.rst +++ /dev/null @@ -1,87 +0,0 @@ -==================================== -Deploy MinIO on a Kubernetes Cluster -==================================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -Overview --------- - -This tutorial uses the MinIO Kubernetes Operator to deploy MinIO to your -Kubernetes cluster in a distributed configuration. Distributed MinIO deployments -are suitable for development, staging, and production environments. For -a tutorial on creating a more simple MinIO deployment for local development -and evaluation, see :doc:`/kubernetes/quickstart`. - -By default, this tutorial creates a distributed MinIO deployment with the -following components: - -- 4 MinIO server instances with TLS enabled. -- 4 x 1TB storage volumes per MinIO server instance. -- 1 MinIO KES key management instance. -- 1 MinIO Minio Console Service instance. -- 1 MinIO Operator instance. - -This tutorial includes instructions for modifying the deployment configuration -for your specific requirements. - -You should have basic familiarity with Kubernetes, its associated terminology, -and its command line tools prior to starting this tutorial. While the MinIO -documentation makes a best-effort to address Kubernetes-specific information, -you should review the official Kubernetes :kube-docs:`documentation <>` for more -complete coverage. - -.. _minio-kubernetes-deploy-minio-prerequisites: - -Prerequisites -------------- - -This tutorial requires the following resources: - -- The :minio-git:`minio-operator ` github repository. - -- A Kubernetes cluster with *at least* **four** - :kube-docs:`node` per MinIO server instance. Each node must have *at least* - **four** persistent volumes. - -- A host machine with ``kubectl`` installed. See - :kube-docs:`Install and Set Up kubectl ` - - The host machine should be configured such that ``kubectl`` can access the - Kubernetes cluster. See :kube-docs:`Access Applications in a Cluster - ` for more information. - -Considerations --------------- - -.. ToDo: - - - Document recommended resource allocation (CPU, RAM, etc.) - - Document recommended number of MinIO pods to Nodes - - Document recommended ratio of PV to Physical Disk - -Procedure ---------- - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - diff --git a/source/kubernetes/enforce-security.rst b/source/kubernetes/enforce-security.rst deleted file mode 100644 index aff64799..00000000 --- a/source/kubernetes/enforce-security.rst +++ /dev/null @@ -1,113 +0,0 @@ -======================================== -Enforce Security for MinIO in Kubernetes -======================================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -Overview --------- - -This page covers multiple procedures for configuring MinIO security features -using the MinIO Kubernetes Operator. - -You should have basic familiarity with Kubernetes, its associated terminology, -and its command line tools prior to starting any of the documented procedures. -While the MinIO documentation makes a best-effort to address Kubernetes-specific -information, you should review the official Kubernetes :kube-docs:`documentation -<>` for more complete coverage. - -.. _minio-kubernetes-enforce-security-prerequisites: - -Prerequisites -------------- - -This tutorial requires the following resources: - -- The :minio-git:`minio-operator ` github repository. - -- A Kubernetes cluster with *at least* **four** - :kube-docs:`node` per MinIO server instance. Each node must have *at least* - **four** persistent volumes. - -- A host machine with ``kubectl`` installed. See - :kube-docs:`Install and Set Up kubectl ` - - The host machine should be configured such that ``kubectl`` can access the - Kubernetes cluster. See :kube-docs:`Access Applications in a Cluster - ` for more information. - -Considerations --------------- - -.. ToDo: - - - Document recommended resource allocation (CPU, RAM, etc.) - - Document recommended number of MinIO pods to Nodes - - Document recommended ratio of PV to Physical Disk - -Enable TLS ----------- - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -Configure Root Access to MinIO Servers --------------------------------------- - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -Another Deployment-Level Security Feature ------------------------------------------ - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` diff --git a/source/kubernetes/manage-on-kubernetes.rst b/source/kubernetes/manage-on-kubernetes.rst deleted file mode 100644 index 0e26b261..00000000 --- a/source/kubernetes/manage-on-kubernetes.rst +++ /dev/null @@ -1,77 +0,0 @@ -==================================== -Expand MinIO in a Kubernetes Cluster -==================================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -Overview --------- - -This tutorial uses the MinIO Kubernetes Operator to expand an existing -distributed MinIO deployment in your Kubernetes cluster. Specifically, -this tutorial covers: - -- Adding additional MinIO server instances to the deployment, *and* -- Adding additional drives to a MinIO server instance. - -This tutorial includes instructions for modifying the deployment configuration -for your specific requirements. - -You should have basic familiarity with Kubernetes, its associated terminology, -and its command line tools prior to starting this tutorial. While the MinIO -documentation makes a best-effort to address Kubernetes-specific information, -you should review the official Kubernetes :kube-docs:`documentation <>` for more -complete coverage. - -.. _minio-kubernetes-expand-minio-prerequisites: - -Prerequisites -------------- - -This tutorial requires the following resources: - -- The :minio-git:`minio-operator ` github repository. - -- An existing Kubernetes cluster with a distributed MinIO deployment. - -- A host machine with ``kubectl`` installed. See - :kube-docs:`Install and Set Up kubectl ` - - The host machine should be configured such that ``kubectl`` can access the - Kubernetes cluster. See :kube-docs:`Access Applications in a Cluster - ` for more information. - -Considerations --------------- - -.. ToDo: - - - Document recommended resource allocation (CPU, RAM, etc.) - - Document recommended number of MinIO pods to Nodes - - Document recommended ratio of PV to Physical Disk - -Procedure ---------- - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - diff --git a/source/kubernetes/minio-kubernetes-overview.rst b/source/kubernetes/minio-kubernetes-overview.rst new file mode 100644 index 00000000..cf04dc9b --- /dev/null +++ b/source/kubernetes/minio-kubernetes-overview.rst @@ -0,0 +1,27 @@ +.. _minio-kubernetes: + +===================== +MinIO for Kuberenetes +===================== + +.. default-domain:: minio + +MinIO is a high performance distributed object storage server, designed for +large-scale private cloud infrastructure. MinIO is designed in a cloud-native +manner to scale sustainably in multi-tenant environments. + +Orchestration platforms like Kubernetes provide perfect cloud-native environment +to deploy and scale MinIO. The :minio-git:`MinIO Kubernetes Operator +` brings native MinIO support to Kubernetes. + +.. image:: /images/Kubernetes-Minio.svg + :align: center + :width: 90% + :class: no-scaled-link + :alt: Kubernetes Orchestration with the MinIO Operator facilitates automated deployment of MinIO clusters. + + + +More complete documentation for the MinIO Kubernetes Operator is in progress. +See the :minio-git:`MinIO Kubernetes Operator ` Github +Repository for the most up-to-date progress on the project. diff --git a/source/kubernetes/minio-kubernetes.rst b/source/kubernetes/minio-kubernetes.rst deleted file mode 100644 index 69ed9397..00000000 --- a/source/kubernetes/minio-kubernetes.rst +++ /dev/null @@ -1,41 +0,0 @@ -===================== -MinIO for Kuberenetes -===================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -MinIO is a high performance distributed object storage server, designed for -large-scale private cloud infrastructure. MinIO is designed in a cloud-native -manner to scale sustainably in multi-tenant environments. Orchestration -platforms like Kubernetes provide perfect cloud-native environment to deploy and -scale MinIO. The :minio-git:`MinIO Kubernetes Operator ` brings -native MinIO support to Kubernetes. - -.. image:: /images/Kubernetes-Minio.svg - :align: center - :width: 90% - :class: no-scaled-link - :alt: Kubernetes Orchestration with the MinIO Operator facilitates automated deployment of MinIO clusters. - - - -.. versionchanged:: VERSION.VERSION - - This feature was added in VERSION, upgrade to VERSION - - -.. toctree:: - :titlesonly: - :hidden: - - /kubernetes/quickstart - /kubernetes/deploy-on-kubernetes - /kubernetes/manage-on-kubernetes - /kubernetes/enforce-security - /kubernetes/operator-kes - /kubernetes/operator-mcs - /kubernetes/operator-reference diff --git a/source/kubernetes/operator-kes.rst b/source/kubernetes/operator-kes.rst deleted file mode 100644 index 98e4ce1f..00000000 --- a/source/kubernetes/operator-kes.rst +++ /dev/null @@ -1,79 +0,0 @@ -======================================== -Deploy MinIO KES on a Kubernetes Cluster -======================================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -MinIO KES is a stateless and distributed key-management system for -high-performance applications. KES provides a bridge between applications -running in containerized deployments, like Kubernetes, and centralized Key -Mannagement Systems (KMS) like Hashicorp Vault or Amazon Web Services (AWS) KMS. This -tutorial covers the information necessary for using the MinIO Kubernetes -Operator (``minio-operator``) to deploy MinIO KES instances on a Kubernetes -Cluster. - -You should have basic familiarity with the Kubernetes ecosystem and your -preferred KMS backend prior to starting this tutorial. Defer to the official -documentation for :kube-docs:`Kubernetes` and your preferred KMS backend for -more complete learning resource. While the MinIO docs make a best-effort -to cover third-party concepts and configurations, you should not depend on -this tutorial as the only source of information on third-party products. - -For more complete documentation on MinIO KES, see . - -Prerequisites -------------- - -This tutorial requires the following resources: - -Kubernetes Cluster - You should have access to a running Kubernetes cluster. - - The Kubernetes cluster - -- The Kubernetes cluster must have at least one running - :minio-git:`minio-operator ` instance. See - for installation instructions. - - The Kubernetes cluster should have *at least* **one** node with enough - resources to launch additional pods. - -- The ``minio-operator`` has TLS configured and enabled. See - for configuration instructions. - -- An x.509 Certificate and corresponding private key for MinIO KES to use - for mTLS authentication and authorization. - -- A supported Key Management System backend. MinIO KES supports the following KMS providers: - - - `Hashicorp Vault `__ - - `Amazon Web Services KMS `__ - - `Gemalto SafeNet KeySecure `__ - -Procedure ---------- - -Procedure ---------- - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` diff --git a/source/kubernetes/operator-mcs.rst b/source/kubernetes/operator-mcs.rst deleted file mode 100644 index 7ed357cc..00000000 --- a/source/kubernetes/operator-mcs.rst +++ /dev/null @@ -1,74 +0,0 @@ -=================================================== -Deploy MinIO Console Server on a Kubernetes Cluster -=================================================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -MinIO Console Server (MCS) is a graphical user interface for administrating -MinIO servers. This tutorial covers the information necessary for using the -MinIO Kubernetes Operator (``minio-operator``) to deploy MinIO MCS instances on -a Kubernetes Cluster. - -You should have basic familiarity with the Kubernetes ecosystem prior to -starting this tutorial. Defer to the official documentation for -:kube-docs:`Kubernetes` for more complete learning resources. While the MinIO -docs make a best-effort to cover third-party concepts and configurations, you -should not depend on this tutorial as the only source of information on -third-party products. - -For more complete documentation on MinIO MCS, see . - -Prerequisites -------------- - -This tutorial requires the following resources: - -Kubernetes Cluster - You should have access to a running Kubernetes cluster. - - The Kubernetes cluster should have *at least* **one** node with enough - resources to launch additional pods. - -MinIO Kubernetes Operator - The Kubernetes cluster must have at least one running - :minio-git:`minio-operator ` instance. See for installation instructions. - - The MinIO operator *must* have TLS configured and enabled. See for configuration instructions. - -MinIO Deployment - For a tutorial on deploying MinIO on Kubernetes, see - :doc:`/kubernetes/deploy-on-kubernetes`. - - For a shorter tutorial for local development only, see - :doc:`/kubernetes/quickstart`. - - The MinIO deployment must have at least one MinIO user with administrative - privileges for the MCS instance to use for authentication and authorization. - See for more information on configuring MinIO users. - -Procedure ---------- - -1) First Step Header -~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` - -2) Second Step Header -~~~~~~~~~~~~~~~~~~~~~ - -a) First Substep -```````````````` - -b) Second Substep -````````````````` diff --git a/source/kubernetes/operator-reference.rst b/source/kubernetes/operator-reference.rst deleted file mode 100644 index f86a938c..00000000 --- a/source/kubernetes/operator-reference.rst +++ /dev/null @@ -1,133 +0,0 @@ -======================== -MinIO Operator Reference -======================== - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 2 - -This document explains the various fields supported by MinIO Operator and its -CRD's and how to use these fields to deploy and access MinIO server clusters. - -MinIO Operator creates native Kubernetes resources within the cluster. The -operator uses the name of the created MinIO Instance as a prefix for -all resources created by the operator. For example, if deploying a -MinIO instance named ``minioinstance``, the operator creates the following -resources with their associated names: - -- Headless Service: ``minioinstance-hl-svc`` -- StatefulSet: ``minioinstance`` -- Secret: ``minioinstance-tls`` (If :kubeconf:`spec.requestAutoCert` is enabled) -- CertificateSigningRequest: ``minioinstance-csr`` (If :kubeconf:`spec.requestAutoCert` is enabled) - -The MinIO Kubernetes Operator is under active development. The contents of -this page may change at any time. - -Configuration File Overview ---------------------------- - -The following example shows all possible MinIO Kubernetes Operator configuration -options. - -.. code-block:: yaml - :class: copyable - - apiVerison: operator.min.io/v1 - kind: "MinIOInstance" - metadata: - scheduler: - spec: - metadata: - image: - zones: - volumesPerServer: - imagePullSecret: - credsSecret: - replicas: - podManagementPolicy: - mountPath: - subPath: - volumeClaimTemplate: - env: - requestAutoCert: - certConfig: - externalCertSecret: - resources: - liveness: - nodeSelector: - tolerations: - securityContext: - serviceAccountName: - mcs: - image: - replicas: - mcsSecret: - metadata: - kes: - replicas: - image: - configSecret: - metadata: - -Configuration Options ---------------------- - -.. kubeconf:: kind - - *Type*: String - - Specify ``MinIOInstance``. - -.. kubeconf:: metadata - - *Type*: Object - - Metadata related to the ``MinIOInstance``. For example, the - following sets the ``label`` for the ``MinIOInstance`` object: - - .. code-block:: yaml - - metadata: - labels: minio - - See :kube-api:`#objectmeta-v1-meta` for more complete documentation on - supported metadata options. - -.. kubeconf:: spec - - *Type*: Object - - The specifications used by the MinIO Operator to deploy the MinIO - server cluster. - - Options marked as **Required** must be included in the configuration - document. - -.. kubeconf:: spec.metadata - - *Type* : Object - - Metadata related to all pods launched by the MinIO operator. For example, the - following sets the ``label`` for all pods launched by the MinIO instance - - .. code-block:: yaml - - metadata: - labels: minio - - See :kube-api:`metadata reference documentation <#objectmeta-v1-meta>` for - more complete documentation on supported metadata options. - -.. kubeconf:: spec.requestAutoCert - - *Type*: Boolean - - *Defaults*: ``false`` - - Specify ``true`` to enable automatic TLS certificate generation for each - resource created by the MinIO Operator. The operator uses the root - Certificate Authority (CA) configured for the Kubernetes cluster to generate - the required Certificate Signing Requests (CSR). - diff --git a/source/kubernetes/quickstart.rst b/source/kubernetes/quickstart.rst deleted file mode 100644 index d0e5b977..00000000 --- a/source/kubernetes/quickstart.rst +++ /dev/null @@ -1,229 +0,0 @@ -============================================ -Quickstart: Deploy a Standalone MinIO Server -============================================ - -.. default-domain:: minio - -.. contents:: On This Page - :local: - :depth: 1 - -Overview --------- - -This tutorial uses the MinIO Operator to create a standalone MinIO server on a -local Kubernetes cluster. Standalone MinIO deployments are best suited for local -development of applications using MinIO for object storage. For a tutorial on -creating a production-grade MinIO deployment on a Kubernetes cluster, see -:doc:`/kubernetes/deploy-on-kubernetes`. - -By default, this tutorial creates a standalone MinIO deployment with the -following components: - -- 1 MinIO server instance with TLS enabled. -- 4 x 100MB storage volumes -- 1 MinIO Minio Console Service instance. -- 1 MinIO Operator instance. - -You should have basic familiarity with Kubernetes, its associated terminology, -and its command line tools prior to starting this tutorial. While the MinIO -documentation makes a best-effort to address Kubernetes-specific information, -you should review the official Kubernetes :kube-docs:`documentation <>` for more -complete coverage. - -.. _minio-kubernetes-quickstart-prerequisites: - -Prerequisites -------------- - -This tutorial requires the following resources: - -- The :minio-git:`minio-operator ` github repository. - -- The `kind `__ Kubernetes cluster deployment tool. - Defer to the ``kind`` - `Quick Start `__ for - installation instructions and related dependencies. - -- A host machine where you have rights to install and run software. The - host machine **must** have *at least* the following available resources: - - - 10GB of free storage space. - - 2GB of free system memory (RAM) - - 2 or more physical CPUs. - -Procedure ---------- - -1) Download and Configure Prerequisites -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -a\) Clone the ``minio-operator`` github repository - Issue the following command in a terminal or shell on the host machine - to clone the :minio-git:`minio-operator ` github repository. - - .. include:: /includes/minio-kubernetes-operator.rst - - The github repository contains the MinIO Kubernetes Operator and the example - configuration files used as part of this tutorial. - -b\) Install and configure ``kind`` - Follow the instructions on the ``kind`` - `Quick Start `__ guide. - - Once installed, use the following ``kind`` cluster configuration file to - create a Kubernetes cluster that can support a standalone MinIO server: - - .. code-block:: yaml - :class: copyable - - kind: Cluster - apiVersion: kind.x-k8s.io/v1alpha4 - nodes: - - role: control-plane - - role: worker - - Issue the following command in a terminal or shell on the host machine to - create the local Kubernetes cluster: - - .. code-block:: shell - :class: copyable - - kind create cluster --name minio-local --config.yaml - - To confirm the cluster is available, run the following command: - - .. code-block:: shell - :class: copyable - - kubectl --cluster-info --context kind-minio-local - - Take note of the hostnames assigned to each component in the Kubernetes - cluster. - -2) Start the MinIO Kubernetes Operator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Issue the following command in a terminal or shell on the host machine to -start the MinIO Kubernetes Operator. - -.. code-block:: shell - :class: copyable - - kubectl apply -f ~/minio-kubernetes/git/minio-operator/minio-operator.yaml - -The ``minio-operator.yaml`` configuration file creates a -``minio-operator`` deployment in the Kubernetes cluster. - -3) Configure the Storage Layer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The example MinIO server configuration used in this tutorial requires four -:kube-docs:`persistent volumes ` to start -successfully. This configuration enables features such as :ref:`erasure coding -`. - -Create four Kubernetes persistent volumes for use by the MinIO server instance. -MinIO recommends creating :kube-docs:`local ` persistent -volumes. The following template provides all required fields for creating the -required persistent volumes: - -.. code-block:: yaml - :class: copyable - - apiVersion: v1 - kind: PersistentVolume - metadata: - name: minioexample-pv1 - spec: - capacity: - storage: 10Gi # specify the maximum size of the storage device - volumeMode: Filesystem - accessModes: - - ReadWriteOnce - persistentVolumeReclaimPolicy: Retain - storageClassName: local-storage-class - local: - path: /var/export1 # specify path to local volume on host - nodeAffinity: - required: - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname - operator: In - values: - - minio-local-worker #specify hostname prefix of preferred node - -Change the following configuration options as appropriate for the host -machine configuration: - -- ``spec.capacity.storage`` ( :kube-docs:`reference `) -- ``spec.local.path`` ( :kube-api:`reference <#localvolumesource-v1-core>`) -- ``spec.nodeAffinity.required.matchExpressions.key.values`` (:kube-api:`reference <#nodeselectorrequirement-v1-core>`) - -Issue the following command against each persistent volume configuration file -to create the associated resources. Replace ```` with the name -of each persistent volume configuration file. - -.. code-block:: shell - - kubectl apply -f ~/minio-kubernetes/.yaml - -Issue the following command to check the state of the persistent volumes: - -.. code-block:: shell - :class: copyable - - kubectl get pv - -The output should include the four created persistent volumes. - -4) Create the MinIO Server -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Issue the following command in a terminal or shell to create the MinIO -standalone instance using the MinIO Kubernetes Operator: - -.. code-block:: shell - - kubectl apply -f ~/minio-kubernetes/minio-operator/examples/minioinstance-standalone.yaml - -Issue the following command to check the state of the minio instance: - -.. code-block:: shell - - kubectl get pods - -The output should include a pod running the MinIO server. - -5) Connect to the MinIO Server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``minioinstance-standalone.yaml`` configuration file also creates a -Kubernetes Service to manage communications to and from pods running the MinIO -service. Issue the following command to get the IP address of the service: - -.. code-block:: shell - - kubectl get services - -The default access key is ``minio-admin`` and the default secret key is -``minio-admin``. - -You must use the IP address of the ``minio-service`` to access the MinIO -server. For example, if the IP address is ``192.51.100.21``, enter the URL -``http://192.51.100.21:9000`` into your browser to access the MinIO server. - -To connect using the ``mc`` client, issue the following command on in a -terminal or shell: - -.. code-block:: shell - - mc config host add minio http://192.51.100.21 minio-admin minio-admin - -Next Steps -~~~~~~~~~~ - -- Perform CRUD operations on a MinIO Server (ToDo) -- - diff --git a/source/meta/404.rst b/source/meta/404.rst new file mode 100644 index 00000000..a2ec7437 --- /dev/null +++ b/source/meta/404.rst @@ -0,0 +1,7 @@ +:orphan: + +============== +Page Not Found +============== + +The page you are looking for has moved, been deleted, or does not exist. \ No newline at end of file diff --git a/source/minio-cli/minio-mc-admin.rst b/source/minio-cli/minio-mc-admin.rst index b750aefa..931770fd 100644 --- a/source/minio-cli/minio-mc-admin.rst +++ b/source/minio-cli/minio-mc-admin.rst @@ -4,7 +4,7 @@ MinIO Admin (``mc admin``) .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 @@ -62,8 +62,8 @@ Ensure that the host machine has :command:`mc` security best practices for your operating system for inputting sensitive information on the command line. -Use the :subcommand:`mc alias add` command to add the -deployment to the :command:`mc` configuration. +Use the :mc-cmd:`mc alias set` command to add the +deployment to the :program:`mc` configuration. .. code-block:: shell :class: copyable @@ -111,7 +111,7 @@ The command has the following syntax: If the specified ```` corresponds to a distributed MinIO deployment, the command returns information for each MinIO server in the deployment. Use -:subcommand:`mc alias add` to list the currently configured aliases and their +:subcommand:`mc alias set` to list the currently configured aliases and their corresponding endpoints. *Display MinIO Server Information* @@ -148,7 +148,7 @@ The command has the following syntax: If the specified ```` corresponds to a distributed MinIO deployment, the command adds the policy to each MinIO server in the deployment. Use -:subcommand:`mc alias add` to list the currently configured aliases and their +:subcommand:`mc alias set` to list the currently configured aliases and their corresponding endpoints. MinIO servers include the following canned policies: diff --git a/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst b/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst index 39f03009..8795ce23 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst b/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst index ef378f7d..3926dd2d 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-console.rst b/source/minio-cli/minio-mc-admin/mc-admin-console.rst index dc993594..8c5c2df8 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-console.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-console.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-groups.rst b/source/minio-cli/minio-mc-admin/mc-admin-groups.rst index cfdb7133..c38bd5a4 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-groups.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-groups.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-heal.rst b/source/minio-cli/minio-mc-admin/mc-admin-heal.rst index d1d76059..84f9af8d 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-heal.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-heal.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-info.rst b/source/minio-cli/minio-mc-admin/mc-admin-info.rst index 38189b13..3fac1686 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-info.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-info.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-kms.rst b/source/minio-cli/minio-mc-admin/mc-admin-kms.rst index 230f4b27..3df451a6 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-kms.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-kms.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-obd.rst b/source/minio-cli/minio-mc-admin/mc-admin-obd.rst index 98785701..9cec6039 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-obd.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-obd.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-policy.rst b/source/minio-cli/minio-mc-admin/mc-admin-policy.rst index 8bed1db0..f240c8d8 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-policy.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-policy.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-profile.rst b/source/minio-cli/minio-mc-admin/mc-admin-profile.rst index 76aa1b15..a3859b28 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-profile.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-profile.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst b/source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst index 2f599bd2..d241bb82 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-service.rst b/source/minio-cli/minio-mc-admin/mc-admin-service.rst index 7ae9fe72..0071f00d 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-service.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-service.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-top.rst b/source/minio-cli/minio-mc-admin/mc-admin-top.rst index 7f5d3640..0c59662b 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-top.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-top.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-trace.rst b/source/minio-cli/minio-mc-admin/mc-admin-trace.rst index 83a13cfa..84ac0156 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-trace.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-trace.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-update.rst b/source/minio-cli/minio-mc-admin/mc-admin-update.rst index 3b23861e..f45e130c 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-update.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-update.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-user.rst b/source/minio-cli/minio-mc-admin/mc-admin-user.rst index 769cebb9..969cd669 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-user.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-user.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc.rst b/source/minio-cli/minio-mc.rst index 62ccc502..8ec533b2 100644 --- a/source/minio-cli/minio-mc.rst +++ b/source/minio-cli/minio-mc.rst @@ -1,10 +1,10 @@ -================= -MinIO Client (mc) -================= +===================== +MinIO Client (``mc``) +===================== .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 @@ -21,14 +21,16 @@ support for both filesystems and Amazon S3-compatible cloud storage services mc [FLAGS] COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] ALIAS +.. _mc-install: + Quickstart ---------- 1) Install ``mc`` ~~~~~~~~~~~~~~~~~ -Ensure that the host machine has :mc-cmd:`mc` -:ref:`installed ` prior to starting this procedure: +Install the :program:`mc` command line tool onto the host machine. Click +the tab that corresponds to the host machine operating system or environment: .. include:: /includes/minio-mc-installation.rst @@ -43,27 +45,25 @@ Ensure that the host machine has :mc-cmd:`mc` security best practices for your operating system for inputting sensitive information on the command line. -Use the :mc-cmd:`mc alias add` command to add an Amazon S3-compatible host +Use the :mc-cmd:`mc alias set` command to add an Amazon S3-compatible service to the :mc-cmd:`mc` :ref:`configuration `. .. code-block:: shell :class: copyable bash +o history - mc alias add ALIAS ENDPOINT ACCESS_KEY SECRET_KEY --api [S3v2|S3v4] + mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY bash -o history - Replace ``ALIAS`` with a name to associate to the S3 service. :mc-cmd:`mc` commands typically require ``ALIAS`` as an argument for identifying which S3 service to execute against. -- Replace ``ENDPOINT`` with the URL endpoint of the S3 service. +- Replace ``HOSTNAME`` with the URL endpoint or IP address of the S3 service. - Replace ``ACCESS_KEY`` and ``SECRET_KEY`` with the access and secret keys for a user on the S3 service. -- The ``--api`` flag is optional and defaults to ``S3v4`` if ommitted. - Replace each argument with the required values. Specifying only the ``mc config host add`` command starts an input prompt for entering the required values. @@ -77,21 +77,21 @@ Each of the following tabs contains a provider-specific example: .. code-block:: shell :class: copyable - mc alias add myminio https://minioserver.example.net ACCESS_KEY SECRET KEY + mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET KEY .. tab:: AWS S3 Storage .. code-block:: shell :class: copyable - mc alias add myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY + mc alias set myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY .. tab:: Google Cloud Storage .. code-block:: shell :class: copyable - mc alias add myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY + mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY 3) Test the Connection ~~~~~~~~~~~~~~~~~~~~~~ @@ -118,6 +118,8 @@ unsuccessful, check each of the following: for more information on user access permissions. For other S3-compatible services, defer to the documentation for that service. +.. _minio-mc-commands: + Command Quick Reference ----------------------- @@ -294,27 +296,6 @@ The following list describes each possible file path location in the order You can use the ``--config-dir`` -.. _mc-install: - -Installation ------------- - -.. include:: /includes/minio-mc-installation.rst - -:mc:`mc` includes a default :mc-cmd:`alias ` for the -https://play.min.io MinIO deployment. If the host machine has internet access, -you can use the ``play`` alias for testing and development purposes. For -example, the following lists all buckets on ``https://play.min.io``: - -.. code-block:: shell - :class: copyable - - mc ls play - -The ``play`` MinIO deployment provides a simple sandbox for testing core S3 -functionality. Any S3-compatible tool can view and interact with data on -``play``. Any data stored on ``play`` is public-facing and modifyable. - .. _minio-mc-global-options: Global Options @@ -322,6 +303,8 @@ Global Options .. program:: mc +All :ref:`commands ` support the following global options: + .. option:: --debug Enables verbose output to the console. diff --git a/source/minio-cli/minio-mc/mc-alias.rst b/source/minio-cli/minio-mc/mc-alias.rst index 2d5472b9..6f9164fe 100644 --- a/source/minio-cli/minio-mc/mc-alias.rst +++ b/source/minio-cli/minio-mc/mc-alias.rst @@ -4,9 +4,9 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: - :depth: 1 + :depth: 2 .. mc:: mc alias @@ -28,43 +28,77 @@ Using :mc-cmd:`mc alias` to add or remove an S3-compatible host is equivalent to manually editing entries in the :program:`mc` :ref:`configuration file `. -.. important:: +S3 Access Control and Limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :mc-cmd:`mc alias` requires specifying an access key and corresponding - secret key for a user on the S3-compatible host. :program:`mc` can - only perform operations on that host for which the user has explicit - permission. If the specified user cannot perform an action or access - a resource on the S3 host, :program:`mc` inherits those restrictions. +:mc-cmd:`mc alias` requires specifying an access key and corresponding secret +key for a user on the S3-compatible host. :program:`mc` can only perform +operations on that host for which the user has explicit permission. If the +specified user cannot perform an action or access a resource on the S3 host, +:program:`mc` inherits those restrictions. -Quick Reference ---------------- +For more information on MinIO Access Control, see +:ref:`minio-auth-authz-overview`. -:mc-cmd:`mc alias add ALIAS HOSTNAME ACCESSKEY SECRETKEY ` - Adds the specified S3-compatible host to the - :program:`mc` :ref:`configuration file `. - :program:`mc` commands can access the host using the - specified ``ALIAS``. +For more complete documentation on S3 Access Control, see +:s3-docs:`Amazon S3 Security `. -:mc-cmd:`mc alias remove ALIAS ` - Removes the S3-compatible host associated to the specified alias from the - :program:`mc` :ref:`configuration file `. +For all other S3-compatible services, defer to the documentation for that +service. + +Common Operations +----------------- + +Add an S3-Compatible Service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc alias set` to add an S3-compatible service for use with +:program:`mc`: + +.. code-block:: shell + :class: copyable + + mc alias set ALIAS HOSTNAME ACCESSKEY SECRETKEY + +- Replace ``ALIAS`` with the name of the alias to associate to the S3-compatible service. + +- Replace ``HOSTNAME`` with the hostname or IP address of the S3-compatible service. + +- Replace ``ACCESSKEY`` and ``SECRETKEY`` with the access and secret key for a + user on the S3-compatible service. + +Remove a Configured S3-Compatible Service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc alias remove` to remove an S3-compatible alias from the +:program:`mc` configuration: + +.. code-block:: shell + :class: copyable + + mc alias remove ALIAS + +- Replace ``ALIAS`` with the name of the S3-compatible service to remove. + +Use :mc-cmd:`mc alias list` to list the currently configured S3-compatible +services. + +List Configured S3-Compatible Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc alias list` to list all configured S3-compatible aliases: + +.. code-block:: shell + :class: copyable + + mc alias list -:mc-cmd:`mc alias list ` - Lists all S3-compatible hosts and aliases in the :program:`mc` - :ref:`configuration file `. Syntax ------ -:mc-cmd:`~mc alias` has the following syntax: - -.. code-block:: shell - - mc alias COMMAND [COMMAND FLAGS | -h ] [ARGUMENTS] - -:mc-cmd:`~mc alias` supports the following commands: - -.. mc-cmd:: add, a +.. mc-cmd:: set, s + :fullpath: Adds a new S3-compatible host to the configuration file. The command has the following syntax: @@ -72,9 +106,9 @@ Syntax .. code-block:: shell :class: copyable - mc alias add ALIAS HOSTNAME ACCESS_KEY SECRET_KEY --api [S3v2|S3v4] + mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY --api [S3v2|S3v4] - :mc-cmd:`mc alias add` supports the following arguments: + :mc-cmd:`mc alias set` supports the following arguments: .. mc-cmd:: ALIAS @@ -111,6 +145,7 @@ Syntax .. mc-cmd:: remove, rm + :fullpath: Removes a host entry from the configuration file. The command has the following syntax: @@ -121,6 +156,7 @@ Syntax mc alias remove ALIAS .. mc-cmd:: list, ls + :fullpath: Lists all hosts in the configuration file. The command has the following syntax: @@ -130,9 +166,6 @@ Syntax mc alias list -Behavior --------- - Examples -------- @@ -142,21 +175,4 @@ Add a New S3 Service Alias .. code-block:: shell :class: copyable - mc alias add myminio https://myminio.example.net myminioaccesskey myminiosecretkey - -Remove an Existing S3 Service Alias -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: shell - :class: copyable - - mc alias remove myminio - - -List All Configured S3 Service Aliases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: shell - :class: copyable - - mc alias list \ No newline at end of file + mc alias set myminio https://myminio.example.net myminioaccesskey myminiosecretkey diff --git a/source/minio-cli/minio-mc/mc-cat.rst b/source/minio-cli/minio-mc/mc-cat.rst index 32a386dd..c4daa363 100644 --- a/source/minio-cli/minio-mc/mc-cat.rst +++ b/source/minio-cli/minio-mc/mc-cat.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-cp.rst b/source/minio-cli/minio-mc/mc-cp.rst index f048192e..5dec9fc2 100644 --- a/source/minio-cli/minio-mc/mc-cp.rst +++ b/source/minio-cli/minio-mc/mc-cp.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-diff.rst b/source/minio-cli/minio-mc/mc-diff.rst index 385c1cf4..30bde2a9 100644 --- a/source/minio-cli/minio-mc/mc-diff.rst +++ b/source/minio-cli/minio-mc/mc-diff.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-encrypt.rst b/source/minio-cli/minio-mc/mc-encrypt.rst index 2f1ff428..75439af9 100644 --- a/source/minio-cli/minio-mc/mc-encrypt.rst +++ b/source/minio-cli/minio-mc/mc-encrypt.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-event.rst b/source/minio-cli/minio-mc/mc-event.rst index 5c50e419..cf731d4a 100644 --- a/source/minio-cli/minio-mc/mc-event.rst +++ b/source/minio-cli/minio-mc/mc-event.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-find.rst b/source/minio-cli/minio-mc/mc-find.rst index 79c1715c..49fd99c1 100644 --- a/source/minio-cli/minio-mc/mc-find.rst +++ b/source/minio-cli/minio-mc/mc-find.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-head.rst b/source/minio-cli/minio-mc/mc-head.rst index 0ab317e1..32c1b2ed 100644 --- a/source/minio-cli/minio-mc/mc-head.rst +++ b/source/minio-cli/minio-mc/mc-head.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-ilm.rst b/source/minio-cli/minio-mc/mc-ilm.rst index bceb3c72..3a8cadd6 100644 --- a/source/minio-cli/minio-mc/mc-ilm.rst +++ b/source/minio-cli/minio-mc/mc-ilm.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-legalhold.rst b/source/minio-cli/minio-mc/mc-legalhold.rst index 50abbee6..68540013 100644 --- a/source/minio-cli/minio-mc/mc-legalhold.rst +++ b/source/minio-cli/minio-mc/mc-legalhold.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc/mc-lock.rst b/source/minio-cli/minio-mc/mc-lock.rst index f6f108cf..25df1e3c 100644 --- a/source/minio-cli/minio-mc/mc-lock.rst +++ b/source/minio-cli/minio-mc/mc-lock.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-ls.rst b/source/minio-cli/minio-mc/mc-ls.rst index 8270a1c4..7a561ee6 100644 --- a/source/minio-cli/minio-mc/mc-ls.rst +++ b/source/minio-cli/minio-mc/mc-ls.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-mb.rst b/source/minio-cli/minio-mc/mc-mb.rst index 00d9bac2..abd0cdaf 100644 --- a/source/minio-cli/minio-mc/mc-mb.rst +++ b/source/minio-cli/minio-mc/mc-mb.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-mirror.rst b/source/minio-cli/minio-mc/mc-mirror.rst index 4d5bea35..0551e08f 100644 --- a/source/minio-cli/minio-mc/mc-mirror.rst +++ b/source/minio-cli/minio-mc/mc-mirror.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-mv.rst b/source/minio-cli/minio-mc/mc-mv.rst index 91410628..09f51a15 100644 --- a/source/minio-cli/minio-mc/mc-mv.rst +++ b/source/minio-cli/minio-mc/mc-mv.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-policy.rst b/source/minio-cli/minio-mc/mc-policy.rst index 5e7e05d7..0f0d9256 100644 --- a/source/minio-cli/minio-mc/mc-policy.rst +++ b/source/minio-cli/minio-mc/mc-policy.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-rb.rst b/source/minio-cli/minio-mc/mc-rb.rst index 11b2400c..3466ffe4 100644 --- a/source/minio-cli/minio-mc/mc-rb.rst +++ b/source/minio-cli/minio-mc/mc-rb.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-retention.rst b/source/minio-cli/minio-mc/mc-retention.rst index 7305f4a5..8d459bec 100644 --- a/source/minio-cli/minio-mc/mc-retention.rst +++ b/source/minio-cli/minio-mc/mc-retention.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc/mc-rm.rst b/source/minio-cli/minio-mc/mc-rm.rst index 8e011159..9d2d8c1c 100644 --- a/source/minio-cli/minio-mc/mc-rm.rst +++ b/source/minio-cli/minio-mc/mc-rm.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-share.rst b/source/minio-cli/minio-mc/mc-share.rst index 8fbae28e..3aff5eac 100644 --- a/source/minio-cli/minio-mc/mc-share.rst +++ b/source/minio-cli/minio-mc/mc-share.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-sql.rst b/source/minio-cli/minio-mc/mc-sql.rst index 4c74f0aa..7b6dd148 100644 --- a/source/minio-cli/minio-mc/mc-sql.rst +++ b/source/minio-cli/minio-mc/mc-sql.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-stat.rst b/source/minio-cli/minio-mc/mc-stat.rst index 88047522..ad995d9a 100644 --- a/source/minio-cli/minio-mc/mc-stat.rst +++ b/source/minio-cli/minio-mc/mc-stat.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-tag.rst b/source/minio-cli/minio-mc/mc-tag.rst index 2705de2e..c78ad1d0 100644 --- a/source/minio-cli/minio-mc/mc-tag.rst +++ b/source/minio-cli/minio-mc/mc-tag.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc/mc-tree.rst b/source/minio-cli/minio-mc/mc-tree.rst index 4e7b5a1a..d6b13d40 100644 --- a/source/minio-cli/minio-mc/mc-tree.rst +++ b/source/minio-cli/minio-mc/mc-tree.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-update.rst b/source/minio-cli/minio-mc/mc-update.rst index 236ee213..1513ca7c 100644 --- a/source/minio-cli/minio-mc/mc-update.rst +++ b/source/minio-cli/minio-mc/mc-update.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-cli/minio-mc/mc-version.rst b/source/minio-cli/minio-mc/mc-version.rst index 7ad89b2d..fe5e6f18 100644 --- a/source/minio-cli/minio-mc/mc-version.rst +++ b/source/minio-cli/minio-mc/mc-version.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-cli/minio-mc/mc-watch.rst b/source/minio-cli/minio-mc/mc-watch.rst index a227dd36..c707467e 100644 --- a/source/minio-cli/minio-mc/mc-watch.rst +++ b/source/minio-cli/minio-mc/mc-watch.rst @@ -4,7 +4,7 @@ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/minio-features/bucket-versioning.rst b/source/minio-features/bucket-versioning.rst index 0fd82beb..0523923b 100644 --- a/source/minio-features/bucket-versioning.rst +++ b/source/minio-features/bucket-versioning.rst @@ -6,7 +6,7 @@ Bucket Versioning .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 diff --git a/source/minio-server/minio-server.rst b/source/minio-server/minio-server.rst new file mode 100644 index 00000000..94bfcf46 --- /dev/null +++ b/source/minio-server/minio-server.rst @@ -0,0 +1,323 @@ +======================== +MinIO Server (``minio``) +======================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: minio + +The :mc:`minio` command line executable starts either the MinIO Object Storage +process *or* the MinIO Gateway process. + +MinIO Server +------------ + +The :mc:`minio server` command starts the MinIO server process: + +.. code-block:: shell + :class: copyable + + minio server /mnt/disk{1...4} + +For examples of deploying :mc:`minio server` on a bare metal environment, +see :ref:`minio-baremetal`. + +For examples of deploying :mc:`minio server` on a Kubernetes environment, +see :ref:`minio-kubernetes`. + +Configuration Settings +~~~~~~~~~~~~~~~~~~~~~~ + +The :mc:`minio server` process stores its configuration in the storage +backend :mc-cmd:`directory `. You can modify +configuration options using the +:mc-cmd:`mc admin config` command. + +Syntax +~~~~~~~ + +.. mc:: minio server + +Starts the ``minio`` server process. + +The command has the following syntax: + +.. code-block:: shell + :class: copyable + + minio server [FLAGS] HOSTNAME/DIRECTORIES [HOSTNAME/DIRECTORIES..] + +The command accepts the following arguments: + +.. mc-cmd:: HOSTNAME + + The hostname of a :mc:`minio server` process. + + For standalone deployments, this field is *optional*. You can start a + standalone :mc:`minio ` process with only the + :mc-cmd:`~minio server DIRECTORIES` argument. + + For distributed deployments, specify the hostname of each + :mc:`minio ` in the deployment. + + :mc-cmd:`~minio server HOSTNAME` supports MinIO expansion notation + ``{x...y}`` to denote a sequential series of hostnames. For example, + ``https://minio{1...4}.example.net`` expands to: + + - ``https://minio1.example.net`` + - ``https://minio2.example.net`` + - ``https://minio3.example.net`` + - ``https://minio4.example.net`` + + The set of :mc:`minio server` processes in :mc-cmd:`~minio server HOSTNAME` + define a single :ref:`zone `. MinIO *requires* sequential + hostnames to identify each :mc:`minio server` process in the zone. + + Each additional ``HOSTNAME/DIRECTORIES`` pair denotes an additional zone for + the purpose of horizontal expansion of the MinIO deployment. For more + information on zones, see :ref:`minio-zones`. + +.. mc-cmd:: DIRECTORIES + + The directories or disks the :mc:`minio server` process uses as the + storage backend. + + :mc-cmd:`~minio server DIRECTORIES` supports MinIO expansion notation + ``{x...y}`` to denote a sequential series of folders or disks. For example, + ``/mnt/disk{1...4}`` expands to: + + - ``/mnt/disk1`` + - ``/mnt/disk2`` + - ``/mnt/disk3`` + - ``/mnt/disk4`` + + The :mc-cmd:`~minio server DIRECTORIES` path(s) *must* be empty when first + starting the :mc:`minio ` process. + + The :mc:`minio server` process requires *at least* 4 disks or directories + to enable :ref:`erasure coding `. + + .. important:: + + MinIO recommends locally-attached disks, where the + :mc-cmd:`~minio server DIRECTORIES` path points to each disk on the + host machine. + + For development or evaluation, you can specify multiple logical + directories or partitions on a single physical volume to enable erasure + coding on the deployment. + + For production environments, MinIO does **not recommend** using multiple + logical directories or partitions on a single physical disk. While MinIO + supports those configurations, the potential cost savings come at the risk + of decreased reliability. + + +.. mc-cmd:: address + :option: + + *Optional* Binds the :mc:`minio ` server process to a + specific network address and port number. Specify the address and port as + ``ADDRESS:PORT``, where ``ADDRESS`` is an IP address or hostname and + ``PORT`` is a valid and open port on the host system. + + To change the port number for all IP addresses or hostnames configured + on the host machine, specify ``:PORT`` where ``PORT`` is a valid + and open port on the host. + + If omitted, :mc:`minio ` binds to port ``9000`` on all + configured IP addresses or hostnames on the host machine. + +.. mc-cmd:: certs-dir, -S + :option: + + *Optional* Specifies the path to the folder containing certificates the + :mc:`minio` process uses for configuring TLS/SSL connectivity. + + Omit to use the default directory paths: + + - Linux/OSX: ``${HOME}/.minio/certs`` + - Windows: ``%%USERPROFILE%%\.minio\certs``. + + See :ref:`minio-TLS` for more information on TLS/SSL connectivity. + +.. mc-cmd:: quiet + :option: + + *Optional* Disables startup information. + +.. mc-cmd:: anonymous + :option: + + *Optional* Hides sensitive information from logging. + +.. mc-cmd:: json + :option: + + *Optional* Outputs server logs and startup information in ``JSON`` + format. + +MinIO Gateway +------------- + +Syntax +~~~~~~ + +.. mc:: minio gateway + +Starts the MinIO Gateway process. + +The command has the following syntax: + +.. code-block:: shell + :class: copyable + + minio gateway [FLAGS] SUBCOMMAND [ARGUMENTS] + +:mc:`minio gateway` supports the following flags: + +.. mc-cmd:: address + :option: + + *Optional* Binds the MinIO Gateway to a specific network address and port + number. Specify the address and port as ``ADDRESS:PORT``, where ``ADDRESS`` + is an IP address or hostname and ``PORT`` is a valid and open port on the + host system. + + To change the port number for all IP addresses or hostnames configured + on the host machine, specify ``:PORT`` where ``PORT`` is a valid + and open port on the host. + +.. mc-cmd:: certs-dir, -S + :option: + + *Optional* Specifies the path to the folder containing certificates the + MinIO Gateway process uses for configuring TLS/SSL connectivity. + + Omit to use the default directory paths: + + - Linux/OSX: ``${HOME}/.minio/certs`` + - Windows: ``%%USERPROFILE%%\.minio\certs``. + + See :ref:`minio-TLS` for more information on TLS/SSL connectivity. + +.. mc-cmd:: quiet + :option: + + *Optional* Disables startup information. + +.. mc-cmd:: anonymous + :option: + + *Optional* Hides sensitive information from logging. + +.. mc-cmd:: json + :option: + + *Optional* Outputs server logs and startup information in ``JSON`` + format. + +:mc:`minio gateway` supports the following subcommands: + +.. mc-cmd:: nas + :fullpath: + + Creates a MinIO Gateway process configured for Network-Attached Storage + (NAS). + +.. mc-cmd:: azure + :fullpath: + + Creates a MinIO Gateway process configured for Microsoft Azure Blob Storage. + +.. mc-cmd:: s3 + :fullpath: + + Creates a MinIO Gateway process configured for Amazon Simple Storage Service + (S3). + +.. mc-cmd:: hdfs + :fullpath: + + Creates a MinIO Gateway process configured for Hadoop Distributed File + System (HDFS). + +.. mc-cmd:: gcs + :fullpath: + + Creates a MinIO Gateway process configured for Google Cloud Storage. + +Environment Variables +--------------------- + +The :mc:`minio server` and :mc:`minio gateway` processes can use the following +environment variables when creating its configuration settings: + +Root Credentials +~~~~~~~~~~~~~~~~ + +.. envvar:: MINIO_ACCESS_KEY + + The access key for the :ref:`root ` user. + + .. warning:: + + If :envvar:`MINIO_ACCESS_KEY` is unset, + :mc:`minio` defaults to ``minioadmin``. + + **NEVER** use the default credentials in production environments. + MinIO strongly recommends specifying a unique, long, and random + :envvar:`MINIO_ACCESS_KEY` value for all environments. + +.. envvar:: MINIO_SECRET_KEY + + The secret key for the :ref:`root ` user. + + .. warning:: + + If :envvar:`MINIO_SECRET_KEY` is unset, + :mc:`minio` defaults to ``minioadmin``. + + **NEVER** use the default credentials in production environments. + MinIO strongly recommends specifying a unique, long, and random + :envvar:`MINIO_ACCESS_KEY` value for all environments. + +.. envvar:: MINIO_ACCESS_KEY_OLD + + Used for rotating the :ref:`root ` user access + key. + + Restart the :mc:`minio server` process with *all* of the following + environment variables to rotate the root credentials: + + - :envvar:`MINIO_ACCESS_KEY_OLD` set to the old access key. + - :envvar:`MINIO_ACCESS_KEY` set to the new access key. + - :envvar:`MINIO_SECRET_KEY_OLD` set to the old secret key. + - :envvar:`MINIO_SECRET_KEY` set to the new secret key. + + The :mc:`minio server` process automatically detects and re-encrypts + the server configuration with the new credentials. After the process + restarts successfully, you can restart it without + :envvar:`MINIO_ACCESS_KEY_OLD`. + +.. envvar:: MINIO_SECRET_KEY_OLD + + Used for rotating the :ref:`root ` user secret + key. + + Restart the :mc:`minio server` process with *all* of the following + environment variables to rotate the root credentials: + + - :envvar:`MINIO_ACCESS_KEY_OLD` set to the old access key. + - :envvar:`MINIO_ACCESS_KEY` set to the new access key. + - :envvar:`MINIO_SECRET_KEY_OLD` set to the old secret key. + - :envvar:`MINIO_SECRET_KEY` set to the new secret key. + + The :mc:`minio server` process automatically detects and re-encrypts + the server configuration with the new credentials. After the process + restarts successfully, you can restart it without + :envvar:`SECRET_KEY_OLD`. diff --git a/source/security/minio-authentication-authorization.rst b/source/security/minio-authentication-authorization.rst index 37228775..fc707127 100644 --- a/source/security/minio-authentication-authorization.rst +++ b/source/security/minio-authentication-authorization.rst @@ -1,10 +1,12 @@ +.. _minio-auth-authz-overview: + ================================ Authentication and Authorization ================================ .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 2 @@ -105,6 +107,8 @@ their assigned groups. :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account `. +.. _minio-auth-authz-root: + ``root`` User ~~~~~~~~~~~~~ diff --git a/source/security/minio-security-TLS-encryption.rst b/source/security/minio-security-TLS-encryption.rst index bb154c22..4b84a96e 100644 --- a/source/security/minio-security-TLS-encryption.rst +++ b/source/security/minio-security-TLS-encryption.rst @@ -1,10 +1,12 @@ +.. _minio-TLS: + ============================== MinIO Transport Layer Security ============================== .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/security/minio-security-security-token-service.rst b/source/security/minio-security-security-token-service.rst index d574eaa5..b9ba3af2 100644 --- a/source/security/minio-security-security-token-service.rst +++ b/source/security/minio-security-security-token-service.rst @@ -6,7 +6,7 @@ MinIO Security Token Service .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/security/minio-security-server-side-encryption.rst b/source/security/minio-security-server-side-encryption.rst index 3f2ed217..fcb7f242 100644 --- a/source/security/minio-security-server-side-encryption.rst +++ b/source/security/minio-security-server-side-encryption.rst @@ -4,7 +4,7 @@ Server-Side Object Encryption .. default-domain:: minio -.. contents:: On This Page +.. contents:: Table of Contents :local: :depth: 1 diff --git a/source/security/minio-security.rst b/source/security/minio-security.rst index 465306c4..c2ed00b5 100644 --- a/source/security/minio-security.rst +++ b/source/security/minio-security.rst @@ -41,7 +41,7 @@ MinIO provides support for the following security features: :titlesonly: :hidden: - /security/minio-authentication-authorization-review + /security/minio-authentication-authorization /security/minio-security-TLS-encryption /security/minio-security-server-side-encryption /security/minio-security-security-token-service diff --git a/sphinxext/minio.py b/sphinxext/minio.py index bbfbee6d..6e17448a 100644 --- a/sphinxext/minio.py +++ b/sphinxext/minio.py @@ -533,6 +533,7 @@ class MinIODomain(Domain): 'mc-cmd': ObjType(_('mc-cmd'), 'mc-cmd'), 'mc-cmd-option': ObjType(_('mc-cmd-option'), 'mc-cmd-option'), 'policy-action': ObjType(_('policy-action'), 'policy-action'), + 'envvar': ObjType(_('envvar'), 'envvar') } directives = { 'data': MinioObject, @@ -543,7 +544,8 @@ class MinIODomain(Domain): 'flag': MinioObject, 'mc': MinioMCCommand, 'mc-cmd': MinioMCObject, - 'policy-action': MinioObject + 'policy-action': MinioObject, + 'envvar': MinioObject } roles = { 'data': MinioXRefRole(), @@ -556,6 +558,7 @@ class MinIODomain(Domain): 'mc-cmd': MinioXRefRole(), 'mc-cmd-option': MinioCMDOptionXRefRole(), 'policy-action': MinioXRefRole(), + 'envvar': MinioXRefRole(), } initial_data = {