mirror of
https://github.com/minio/docs.git
synced 2025-07-31 18:04:52 +03:00
Exclude prefixes or folders from versioning (#769)
Object versioning can now be configured with certain exclusions (no longer strictly on a per-bucket basis). Add documentation about how to use the new options: * `--excluded-prefixes` to exclude objects with certain prefixes * `--exclude-folders` to exclude anything with name ending in `/` (folders) - [x] Exclude prefixes - [x] Exclude folders - [x] Wildcards/globbing - [x] Limitations - [x] View versioning exclusion configuration Staged: [Bucket Versioning](http://192.241.195.202:9000/staging/DOCS-760/linux/html/administration/object-management/object-versioning.html) [mc version](http://192.241.195.202:9000/staging/DOCS-760/linux/html/reference/minio-mc/mc-version.html) Fixes https://github.com/minio/docs/issues/760 --------- Co-authored-by: Krishnan Parthasarathi <krisis@users.noreply.github.com>
This commit is contained in:
Andrea Longo
GitHub
@ -67,6 +67,8 @@ Once authenticated, TLS provides the cipher to encrypt and then decrypt the tran
|
||||
|
||||
MinIO supports several methods of :ref:`Server-Side Encryption <minio-encryption-overview>`.
|
||||
|
||||
.. _minio-admin-concepts-organize-objects:
|
||||
|
||||
Can I organize objects in a folder structure within buckets?
|
||||
------------------------------------------------------------
|
||||
|
||||
|
||||
@ -219,8 +219,7 @@ Enable Bucket Versioning
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can enable versioning using the MinIO Console, the MinIO :mc:`mc` CLI, or
|
||||
using an S3-compatible SDK. Versioning is a bucket-scoped feature. You cannot
|
||||
enable versioning on only a prefix or subset of objects in a bucket.
|
||||
using an S3-compatible SDK.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
@ -266,6 +265,129 @@ enable versioning on only a prefix or subset of objects in a bucket.
|
||||
Objects created prior to enabling versioning have a
|
||||
``null`` :ref:`version ID <minio-bucket-versioning-id>`.
|
||||
|
||||
|
||||
Exclude a Prefix From Versioning
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can exclude certain :ref:`prefixes <minio-admin-concepts-organize-objects>` from versioning using the :ref:`MinIO Client <minio-client>`.
|
||||
This is useful for Spark/Hadoop workloads or others that initially create objects with temporary prefixes.
|
||||
|
||||
.. admonition:: Object locking
|
||||
:class: note
|
||||
|
||||
Buckets with :ref:`object locking enabled <minio-object-locking>` require versioning and do not support excluding prefixes.
|
||||
|
||||
- Use :mc-cmd:`mc version enable` with the :mc-cmd:`~mc version --excluded-prefixes` option:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable --excluded-prefixes "prefix1, prefix2" ALIAS/BUCKET
|
||||
|
||||
- Replace ``ALIAS`` with the :mc:`alias <mc alias>` of a configured MinIO deployment.
|
||||
|
||||
- Replace ``BUCKET`` with the name of the :s3-docs:`bucket <UsingBucket.html>` you want to exclude :ref:`prefixes <minio-admin-concepts-organize-objects>` for.
|
||||
|
||||
The list of :mc-cmd:`~mc version --excluded-prefixes` prefixes match all objects containing the specified strings in their prefix or name, similar to a regular expression of the form ``prefix*``.
|
||||
To match objects by prefix only, use ``prefix/*``.
|
||||
|
||||
For example, the following command excludes any objects containing ``_test`` or ``_temp`` in their prefix or name from versioning:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable --excluded-prefixes "_test, _temp" local/my-bucket
|
||||
|
||||
You can exclude up to 10 prefixes for each bucket.
|
||||
To add or remove prefixes, repeat the :mc-cmd:`mc version enable` command with an updated list.
|
||||
The new list of prefixes replaces the previous one.
|
||||
|
||||
To view the currently excluded prefixes, use :mc-cmd:`mc version info` with the :mc-cmd:`~mc version enable --JSON` option:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version info ALIAS/BUCKET --json
|
||||
|
||||
The command output resembles the following, with the list of excluded prefixes in the ``ExcludedPrefixes`` property:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ mc version info local/my-bucket --json
|
||||
{
|
||||
"Op": "info",
|
||||
"status": "success",
|
||||
"url": "local/my-bucket",
|
||||
"versioning": {
|
||||
"status": "Enabled",
|
||||
"MFADelete": "",
|
||||
"ExcludedPrefixes": [
|
||||
"prefix1, prefix2"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
To disable prefix exclusion and resume versioning all prefixes, repeat the :mc-cmd:`mc version enable` command without :mc-cmd:`~mc version --excluded-prefixes`:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable ALIAS/BUCKET
|
||||
|
||||
|
||||
Exclude Folders from Versioning
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can exclude folders from versioning using the :ref:`MinIO Client <minio-client>`.
|
||||
|
||||
.. admonition:: Object locking
|
||||
:class: note
|
||||
|
||||
Buckets with :ref:`object locking enabled <minio-object-locking>` require versioning and do not support excluding folders.
|
||||
|
||||
- Use :mc-cmd:`mc version enable` with the :mc-cmd:`~mc version --exclude-folders` option to exclude objects with names ending in ``/`` from versioning:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable --exclude-folders ALIAS/BUCKET
|
||||
|
||||
- Replace ``ALIAS`` with the :mc:`alias <mc alias>` of a configured MinIO deployment.
|
||||
|
||||
- Replace ``BUCKET`` with the :s3-docs:`bucket <UsingBucket.html>` you want to exclude :ref:`folders <minio-admin-concepts-organize-objects>` for.
|
||||
|
||||
To check whether folders are versioned for a bucket, use the :mc-cmd:`mc version enable` command with the ``--json`` option.
|
||||
If the ``ExcludeFolders`` property is ``true``, folders in that bucket are not versioned.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable --excluded-prefixes ALIAS/BUCKET --json
|
||||
|
||||
The command output resembles the following:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ mc version info local/my-bucket --json
|
||||
{
|
||||
"Op": "info",
|
||||
"status": "success",
|
||||
"url": "local/my-bucket",
|
||||
"versioning": {
|
||||
"status": "Enabled",
|
||||
"MFADelete": "",
|
||||
"ExcludeFolders": true
|
||||
}
|
||||
}
|
||||
|
||||
To disable folder exclusion and resume versioning all folders, repeat the :mc-cmd:`mc version enable` command without :mc-cmd:`~mc version --exclude-folders`:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable ALIAS/BUCKET
|
||||
|
||||
|
||||
Suspend Bucket Versioning
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -52,7 +52,18 @@ The :mc:`mc version` command enables, suspends, and retrieves the
|
||||
Parameters
|
||||
~~~~~~~~~~
|
||||
|
||||
.. mc-cmd:: ALIAS
|
||||
:required:
|
||||
|
||||
The :ref:`alias <alias>` of a MinIO deployment and the full path
|
||||
to the bucket for which to set the versioning configuration. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mc version enable myminio/mybucket
|
||||
|
||||
.. mc-cmd:: enable
|
||||
:optional:
|
||||
|
||||
Enables versioning on the MinIO bucket specified to
|
||||
:mc-cmd:`ALIAS <mc version ALIAS>`.
|
||||
@ -60,15 +71,27 @@ Parameters
|
||||
Mutually exclusive with :mc-cmd:`~mc version suspend` and
|
||||
:mc-cmd:`~mc version info`
|
||||
|
||||
.. mc-cmd:: suspend
|
||||
.. mc-cmd:: --exclude-folders
|
||||
:optional:
|
||||
|
||||
Disables versioning on the MinIO bucket specified to
|
||||
:mc-cmd:`ALIAS <mc version ALIAS>`.
|
||||
Use with :mc-cmd:`mc version enable` to disable versioning on all folders (objects whose name ends with ``/``) in the specified bucket.
|
||||
|
||||
Mutually exclusive with :mc-cmd:`~mc version suspend` and
|
||||
:mc-cmd:`~mc version info`
|
||||
.. mc-cmd:: --excluded-prefixes
|
||||
:optional:
|
||||
|
||||
Use with :mc-cmd:`mc version enable` to disable versioning on objects matching a list of prefixes, up to 10.
|
||||
The list of prefixes match all objects containing the specified strings in their prefix or name, similar to a regular expression of the form ``prefix*``.
|
||||
To match objects by prefix only, use ``prefix/*``.
|
||||
|
||||
For example, the following command excludes any objects containing ``_test`` or ``_temp`` in their prefix or name from versioning:
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc version enable --excluded-prefixes "_test, _temp" local/my-bucket
|
||||
|
||||
.. mc-cmd:: info
|
||||
:optional:
|
||||
|
||||
Returns the versioning configuration for the MinIO bucket specified to
|
||||
:mc-cmd:`ALIAS <mc version ALIAS>`.
|
||||
@ -76,14 +99,14 @@ Parameters
|
||||
Mutually exclusive with :mc-cmd:`~mc version suspend` and
|
||||
:mc-cmd:`~mc version info`
|
||||
|
||||
.. mc-cmd:: ALIAS
|
||||
.. mc-cmd:: suspend
|
||||
:optional:
|
||||
|
||||
*Required* The :ref:`alias <alias>` of a MinIO deployment and the full path
|
||||
to the bucket for which to set the versioning configuration. For example:
|
||||
Disables versioning on the MinIO bucket specified to
|
||||
:mc-cmd:`ALIAS <mc version ALIAS>`.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
mc version enable myminio/mybucket
|
||||
Mutually exclusive with :mc-cmd:`~mc version suspend` and
|
||||
:mc-cmd:`~mc version info`
|
||||
|
||||
Global Flags
|
||||
~~~~~~~~~~~~
|
||||
@ -171,4 +194,4 @@ S3 Compatibility
|
||||
|
||||
.. include:: /includes/common-minio-mc.rst
|
||||
:start-after: start-minio-mc-s3-compatibility
|
||||
:end-before: end-minio-mc-s3-compatibility
|
||||
:end-before: end-minio-mc-s3-compatibility
|
||||
|
||||
Reference in New Issue
Block a user