minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-30 07:03:26 +03:00
Code Activity

Add new KMS encryption feature, deprecate MINIO_ACCESS_KEY and MINIO_SECRET_KEY

Browse Source
This commit is contained in:
ravindk89
2021-04-29 18:44:27 -04:00
committed by Ravind Kumar
parent abc1e567fe
commit 85dbf58bd9
8 changed files with 358 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
source/conf.py
View File

@ -53,17 +53,18 @@ extensions = [
# Helpful for sites we tend to make lots of references to.
extlinks = {
'kube-docs' : ('https://kubernetes.io/docs/%s', ''),
'minio-git' : ('https://github.com/minio/%s',''),
'github' : ('https://github.com/%s',''),
'kube-api' : ('https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/%s',''),
'aws-docs' : ('https://docs.aws.amazon.com/%s',''),
's3-docs' : ('https://docs.aws.amazon.com/AmazonS3/latest/userguide/%s',''),
's3-api' : ('https://docs.aws.amazon.com/AmazonS3/latest/API/%s',''),
'iam-docs' : ('https://docs.aws.amazon.com/IAM/latest/UserGuide/%s',''),
'release' : ('https://github.com/minio/mc/releases/tag/%s',''),
'legacy' : ('https://docs.min.io/docs/%s',''),
'docs-k8s' : ('https://docs.min.io/minio/k8s/%s',''),
'kube-docs' : ('https://kubernetes.io/docs/%s', ''),
'minio-git' : ('https://github.com/minio/%s',''),
'github' : ('https://github.com/%s',''),
'kube-api' : ('https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/%s',''),
'aws-docs' : ('https://docs.aws.amazon.com/%s',''),
's3-docs' : ('https://docs.aws.amazon.com/AmazonS3/latest/userguide/%s',''),
's3-api' : ('https://docs.aws.amazon.com/AmazonS3/latest/API/%s',''),
'iam-docs' : ('https://docs.aws.amazon.com/IAM/latest/UserGuide/%s',''),
'minio-release' : ('https://github.com/minio/minio/releases/tag/%s',''),
'mc-release' : ('https://github.com/minio/mc/releases/tag/%s',''),
'legacy' : ('https://docs.min.io/docs/%s',''),
'docs-k8s' : ('https://docs.min.io/minio/k8s/%s',''),
}

22
source/extra/examples/ConsoleAdmin.json Normal file
View File

@ -0,0 +1,22 @@
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"admin:*"
],
"Effect": "Allow",
"Sid": ""
},
{
"Action": [
"s3:*"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::*"
],
"Sid": ""
}
]
}

121
source/index.rst
View File

@ -8,11 +8,124 @@ Welcome to the MinIO Documentation! MinIO is a high performance object storage
solution with native support for Kubernetes deployments. MinIO provides an
Amazon Web Services S3-compatible API and supports all core S3 features.
First-time users of MinIO *or* object storage services should start with
our :doc:`Introduction </introduction/minio-overview>`.
You can get started exploring MinIO features using our ``play`` server at
https://play.min.io. ``play`` is a *public* MinIO cluster running the latest
stable MinIO server. Any file uploaded to ``play`` should be considered public
and non-protected.
Users deploying onto a Kubernetes cluster should start with our
:docs-k8s:`Kubernetes documentation <>`.
The MinIO Client :mc:`mc` commandline interface includes an
:mc-cmd:`alias <mc alias>` for the ``play`` server. After
`Downloading the MinIO Client <https://min.io/downloads>`__, use the
``play`` alias to perform S3-compatible object storage operations:
.. code-block:: shell
:class: copyable
mc alias list play
mc mb --with-lock play/mynewbucket
mc cp ~/data/mytestdata play/mynewbucket
See the :doc:`MinIO Client Complete Reference </reference/minio-cli/minio-mc>`
for complete documentation on the available :mc:`mc` commands.
- First-time users of MinIO *or* object storage services should start with
our :doc:`Introduction </introduction/minio-overview>`.
- Users deploying onto a Kubernetes cluster should start with our
:docs-k8s:`Kubernetes documentation <>`.
Quickstart
----------
The following steps deploys MinIO in filesystem mode with a single folder or
disk on the local host. This deployment is best used for initial evaluation of
MinIO S3-compatible object storage. Filesystem mode does not support features
such as versioning and replication.
1\) Create a Data Folder
Create a folder on the local drive for MinIO to use for object storag
operations. For example:
.. code-block:: shell
:class: copyable
mkdir /mnt/data
sudo chmod -R 775 /mnt/data
2\) Download MinIO Server and Commandline Tools
Visit `https://min.io/downloads <https://min.io/downloads?ref=docs>`__ and
following the instructions for your host operating system to download and
configure the :mc:`minio` and :mc:`mc` binaries. Consider adding the
``minio`` and ``mc`` binaries to the operating system PATH for simplified
operations.
Follow the instructions on the download site to start the :mc:`minio server`
process. For example, the following command starts the
:mc:`minio server` using the created directory:
.. code-block:: shell
:class: copyable
export MINIO_ROOT_USER_FILE=myminioaccesskey
export MINIO_ROOT_PASSWORD_FILE=myminiosecretkey
export MINIO_KMS_SECRET_KEY=myminioencryptionkey
minio server /mnt/data
MinIO by default listens on port ``9000``. Applications running on the
same host can connect and perform S3 operations on the MinIO server
using the ``http://localhost:9000`` url.
You can also use the :mc:`mc` commandline tool to perform operations on the
MinIO server. Use :mc:`mc alias set` to update the ``myminio`` alias with
the access key and secret key set on the MinIO server.
For complete documentation on the environment variables specified above, see
the corresponding reference documentation:
- :envvar:`MINIO_ROOT_USER_FILE`
- :envvar:`MINIO_ROOT_PASSWORD_FILE`
- :envvar:`MINIO_KMS_SECRET_KEY`
3\) Configure Console User for MinIO
Create a a :ref:`policy <minio-policy>` and :ref:`user <minio-users>` for
supporting the :minio-git:`MinIO Console <console>`. The Console provides a
rich graphical user interface for interacting with the MinIO server.
The following command downloads the JSON policy file, creates the appropriate
policy, and assigns that policy to a user:
.. code-block:: shell
:class: copyable
wget -O - https://docs.min.io/minio/baremetal/examples/ConsoleAdmin.json | \
mc admin policy add myminio ConsoleAdminPolicy /dev/stdin
mc admin user add myminio consoleAdmin LongRandomSecretKey
mc admin policy set Alpha ConsoleAdminPolicy user=consoleAdmin
4\) Install and run the MinIO Console
Download the :minio-git:`Latest Stable <console/releases/latest>` version
of MinIO Console for the host operating system.
Set the ``CONSOLE_MINIO_SERVER`` environment variable with the
URL of the MinIO server:
.. code-block:: shell
:class: copyable
export CONSOLE_MINIO_SERVER=http://localhost:9000
Run the Console:
.. code-block:: shell
:class: copyable
./console server
5\) Open the MinIO Console
Open your browser and navigate to ``http://localhost:9090`` to access the
MinIO Console. Log in with the ``consoleAdmin`` access key and secret key to
begin interacting with the MinIO Tenant.
.. toctree::
:titlesonly:

6
source/reference/minio-cli/minio-mc.rst
View File

@ -19,7 +19,9 @@ support for both filesystems and Amazon S3-compatible cloud storage services
.. code-block:: shell
mc [FLAGS] COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] ALIAS
mc [FLAGS] COMMAND [ARGUMENTS...] [COMMAND FLAGS | -h]
See :ref:`minio-mc-commands` for a list of supported commands:
.. _mc-install:
@ -185,7 +187,7 @@ The following table lists :mc-cmd:`mc` commands:
* - :mc:`mc lock`
- Deprecated since
:release:`RELEASE.2020-09-18T00-13-21Z`. Use :mc:`mc retention`.
:mc-release:`RELEASE.2020-09-18T00-13-21Z`. Use :mc:`mc retention`.
* - :mc:`mc ls`
- .. include:: /reference/minio-cli/minio-mc/mc-ls.rst

2
source/reference/minio-cli/minio-mc/mc-lock.rst
View File

@ -20,7 +20,7 @@ object retention for a configurable period of time.
.. admonition:: DEPRECATED
:class: important
:mc:`mc lock` was deprecated in :release:`RELEASE.2020-09-18T00-13-21Z`. Use
:mc:`mc lock` was deprecated in :mc-release:`RELEASE.2020-09-18T00-13-21Z`. Use
:mc:`mc retention` to set, retrieve, or clear the bucket default object lock
configuration.

8
source/reference/minio-cli/minio-mc/mc-retention.rst
View File

@ -24,7 +24,7 @@ object lock settings inherit the bucket default.
.. note::
Starting in version :release:`RELEASE.2020-09-18T00-13-21Z`,
Starting in version :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc:`mc retention` fully replaces :mc:`mc lock` for setting the default
object lock settings for a bucket.
@ -385,7 +385,7 @@ Syntax
If specifying :mc-cmd-option:`~mc retention set default`,
:mc-cmd:`mc retention set` ignores all other flags.
Starting in :release:`RELEASE.2020-09-18T00-13-21Z`,
Starting in :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc-cmd-option:`mc retention set default` replaces the functionality of
the deprecated :mc-cmd:`mc lock` command.
@ -482,7 +482,7 @@ Syntax
If specifying :mc-cmd-option:`~mc retention info default`,
:mc-cmd:`mc retention info` ignores all other flags.
Starting in :release:`RELEASE.2020-09-18T00-13-21Z`,
Starting in :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc-cmd-option:`mc retention info default` replaces the functionality of
the deprecated :mc-cmd:`mc lock` command.
@ -576,7 +576,7 @@ Syntax
If specifying :mc-cmd-option:`~mc retention clear default`,
:mc-cmd:`mc retention clear` ignores all other flags.
Starting in :release:`RELEASE.2020-09-18T00-13-21Z`,
Starting in :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc-cmd-option:`mc retention clear default` replaces the functionality of
the deprecated :mc-cmd:`mc lock` command.

123
source/reference/minio-server/minio-server.rst
View File

@ -175,10 +175,41 @@ environment variables during startup to set configuration settings.
Root Credentials
~~~~~~~~~~~~~~~~
.. envvar:: MINIO_ACCESS_KEY
.. envvar:: MINIO_ROOT_USER_FILE
The access key for the :ref:`root <minio-users-root>` user.
.. warning::
If :envvar:`MINIO_ROOT_USER_FILE` 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_ROOT_USER_FILE` value for all environments.
.. envvar:: MINIO_ROOT_PASSWORD_FILE
The access key for the :ref:`root <minio-users-root>` user.
.. warning::
If :envvar:`MINIO_ROOT_PASSWORD_FILE` 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_ROOT_PASSWORD_FILE` value for all environments.
.. envvar:: MINIO_ACCESS_KEY
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
The access key for the :ref:`root <minio-users-root>` user.
This environment variable is *deprecated* in favor of the
:envvar:`MINIO_ROOT_USER_FILE` environment variable.
.. warning::
If :envvar:`MINIO_ACCESS_KEY` is unset,
@ -190,8 +221,13 @@ Root Credentials
.. envvar:: MINIO_SECRET_KEY
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
The secret key for the :ref:`root <minio-users-root>` user.
This environment variable is *deprecated* in favor of the
:envvar:`MINIO_ROOT_PASSWORD_FILE` environment variable.
.. warning::
If :envvar:`MINIO_SECRET_KEY` is unset,
@ -203,39 +239,72 @@ Root Credentials
.. envvar:: MINIO_ACCESS_KEY_OLD
Used for rotating the :ref:`root <minio-users-root>` user access
key.
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
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`.
To perform root credential rotation, modify the
:envvar:`MINIO_ROOT_USER_FILE` and `MINIO_ROOT_PASSWORD_FILE` environment
variables.
.. envvar:: MINIO_SECRET_KEY_OLD
Used for rotating the :ref:`root <minio-users-root>` user secret
key.
.. deprecated:: RELEASE.2021-04-22T15-44-28Z
Restart the :mc:`minio server` process with *all* of the following
environment variables to rotate the root credentials:
To perform root credential rotation, modify the
:envvar:`MINIO_ROOT_USER_FILE` and `MINIO_ROOT_PASSWORD_FILE` environment
variables.
- :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.
Key Management Service and Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. envvar:: MINIO_KMS_SECRET_KEY
.. versionadded:: RELEASE.2021-04-22T15-44-28Z
The client-provided encryption key to use for encrypting the
MinIO backend (users, groups, policies, and server configuration).
See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Prior to :minio-release:`RELEASE.2021-04-22T15-44-28Z`, MinIO used the
:ref:`root <minio-users-root>` user credentials for encrypting the backend.
.. envvar:: MINIO_KMS_KES_ENDPOINT
The endpoint for the MinIO Key Encryption Service (KES) process to use
for supporting SSE-S3 and MinIO backend encryption operations.
.. envvar:: MINIO_KMS_KES_KEY_FILE
The private key associated to the the :envvar:`MINIO_KMS_KES_CERT_FILE`
x.509 certificate to use when authenticating to the KES server.
The KES server requires clients to present both their certificate and
private key for performing mutual TLS (mTLS).
See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>`
for more complete documentation on KES access control.
.. envvar:: MINIO_KMS_KES_CERT_FILE
The x.509 certificate to present to the KES server.
The KES server requires clients to present both their certificate and
private key for performing mutual TLS (mTLS).
The KES server computes an
:minio-git:`identity <kes/wiki/Configuration#policy-configuration>`
from the certificate and compares it to its configured
policies. The KES server grants the
:mc:`minio` server access to only those operations explicitly granted by the
policy.
See the :minio-git:`KES wiki <kes/wiki/Configuration#policy-configuration>`
for more complete documentation on KES access control.
.. envvar:: MINIO_KMS_KES_KEY_NAME
The name of an external ke to retrieve from the Key Management System (KMS)
configured on the KES server. MinIO uses this key for supporting
server-side encryption of objects (SSE-S3) and MinIO backend encryption.
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_SECRET_KEY_OLD`.
Storage Class
~~~~~~~~~~~~~

125
source/tutorials/minio-installation.rst
View File

@ -58,7 +58,21 @@ procedure.
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
3\) Generate an Encryption Key for the MinIO Backend
Starting in the :minio-release:`RELEASE.2021-04-22T15-44-28Z` release, MinIO
requires a user-specified encryption key or Key Management System (KMS) for
encrypting the backend (users, groups, policies, and server configuration).
Generate a 256-bit encryption key and encode it as a base64 string:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Copy the value for use in the next step.
4\) Run the ``minio`` Server
Issue the following command on each host machine in the deployment. The
following example assumes that:
@ -71,8 +85,9 @@ procedure.
.. code-block:: shell
:class: copyable
export MINIO_ACCESS_KEY=minio-admin
export MINIO_SECRET_KEY=minio-secret-key-CHANGE-ME
export MINIO_ROOT_USER_FILE=minio-admin
export MINIO_ROOT_PASSWORD_FILE=minio-secret-key-CHANGE-ME
export MINIO_KMS_SECRET_KEY=base64encoded256bitkey
minio server https://minio{1...4}.example.com/mnt/disk{1...4}/data
The example command breaks down as follows:
@ -81,17 +96,21 @@ procedure.
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ACCESS_KEY`
* - :envvar:`MINIO_ROOT_USER_FILE`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_SECRET_KEY`
* - :envvar:`MINIO_ROOT_PASSWORD_FILE`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration).
* - ``https://minio{1...4}.example.com/``
- The DNS hostname of each server in the distributed deployment.
@ -147,8 +166,9 @@ version of the ``minio`` server process:
:class: copyable
docker run -p 9000:9000 \
-e "MINIO_ACCESS_KEY=ROOT_ACCESS_KEY" \
-e "MINIO_SECRET_KEY=SECRET_ACCESS_KEY_CHANGE_ME" \
-e "MINIO_ROOT_USER_FILE=ROOT_ACCESS_KEY" \
-e "MINIO_ROOT_PASSWORD_FILE=SECRET_ACCESS_KEY_CHANGE_ME" \
-e "MINIO_KMS_SECRET_KEY=base64encoded256bitkey" \
-v /mnt/disk1:/disk1 \
-v /mnt/disk2:/disk2 \
-v /mnt/disk3:/disk3 \
@ -157,11 +177,34 @@ version of the ``minio`` server process:
The command uses the following options:
- ``-e MINIO_ACCESS_KEY`` and ``-e MINIO_SECRET_KEY`` for configuring the
:ref:`root <minio-users-root>` user credentials.
.. list-table::
:widths: 40 60
:width: 100%
- ``-v /mnt/disk<int>:/disk<int>`` for configuring each disk the ``minio``
server uses.
* - :envvar:`MINIO_ROOT_USER_FILE`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD_FILE`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration).
Replace this value with a 256-bit base64-encrypted string:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
* - ``-v /mnt/disk<int>:/disk<int>``
- The path to each each disk the ``minio`` server uses.
Bleeding Edge MinIO
~~~~~~~~~~~~~~~~~~~
@ -175,8 +218,9 @@ bleeding-edge version of the ``minio`` server process:
:class: copyable
docker run -p 9000:9000 \
-e "MINIO_ACCESS_KEY=ROOT_ACCESS_KEY" \
-e "MINIO_SECRET_KEY=SECRET_ACCESS_KEY_CHANGE_ME" \
-e "MINIO_ROOT_USER_FILE=ROOT_ACCESS_KEY" \
-e "MINIO_ROOT_PASSWORD_FILE=SECRET_ACCESS_KEY_CHANGE_ME" \
-e "MINIO_KMS_SECRET_KEY=base64encoded256bitkey" \
-v /mnt/disk1:/disk1 \
-v /mnt/disk2:/disk2 \
-v /mnt/disk3:/disk3 \
@ -185,11 +229,34 @@ bleeding-edge version of the ``minio`` server process:
The command uses the following options:
- ``MINIO_ACCESS_KEY`` and ``MINIO_SECRET_KEY`` for configuring the
:ref:`root <minio-users-root>` user credentials.
.. list-table::
:widths: 40 60
:width: 100%
- ``-v /mnt/disk<int>:/disk<int>`` for configuring each disk the ``minio``
server uses.
* - :envvar:`MINIO_ROOT_USER_FILE`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_ROOT_PASSWORD_FILE`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration).
Replace this value with a 256-bit base64-encrypted string:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
* - ``-v /mnt/disk<int>:/disk<int>``
- The path to each each disk the ``minio`` server uses.
Standalone Installation
-----------------------
@ -222,7 +289,21 @@ environments.
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
3\) Generate an Encryption Key for the MinIO Backend
Starting in the :minio-release:`RELEASE.2021-04-22T15-44-28Z` release, MinIO
requires a user-specified encryption key or Key Management System (KMS) for
encrypting the backend (users, groups, policies, and server configuration).
Generate a 256-bit encryption key and encode it as a base64 string:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Copy the value for use in the next step.
4\) 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 <minio-erasure-coding>`:
@ -230,8 +311,8 @@ environments.
.. code-block:: shell
:class: copyable
export MINIO_ACCESS_KEY=minio-admin
export MINIO_SECRET_KEY=minio-secret-key-CHANGE-ME
export MINIO_ROOT_USER_FILE=minio-admin
export MINIO_ROOT_PASSWORD_FILE=minio-secret-key-CHANGE-ME
minio server /mnt/disk{1...4}/data
The example command breaks down as follows:
@ -240,12 +321,12 @@ environments.
:widths: 40 60
:width: 100%
* - :envvar:`MINIO_ACCESS_KEY`
* - :envvar:`MINIO_ROOT_USER_FILE`
- The access key for the :ref:`root <minio-users-root>` user.
Replace this value with a unique, random, and long string.
* - :envvar:`MINIO_SECRET_KEY`
* - :envvar:`MINIO_ROOT_PASSWORD_FILE`
- The corresponding secret key to use for the
:ref:`root <minio-users-root>` user.