From 22d576bc7927c642d359c884e01115f085fc9a43 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Wed, 27 Dec 2023 17:55:08 -0500 Subject: [PATCH] Updates related to three MinIO Client Dec 2023 releases (#1098) Updates for three December 2023 MinIO Client releases. 1. mc RELEASE.2023-12-02T02-03-28Z - Enable/disabe ilm expiration rule replication in site replication config - New size filters for ilm rule add - Make STS related envvars alias specific 2. mc RELEASE.2023-12-14T00-37-41Z - Adds flags to `mc ilm rule add` to support service principals for Azure tiers. 3. mc RELEASE.2023-12-23T08-47-21Z - Adds new `mc idp ldap accesskey create` command - Updates other `mc idp ldap accesskey` commands - Updates `mc license registe` command - Adds `--license` flag to `mc license reigster` command Closes #1096 Closes #1088 Closes #1082 --- .../includes/common-minio-ad-ldap-params.rst | 2 + source/includes/common-replication.rst | 6 + source/operations/troubleshooting.rst | 3 +- .../minio-mc-admin/mc-admin-replicate.rst | 102 +++++++-- .../minio-mc/mc-idp-ldap-accesskey-create.rst | 215 ++++++++++++++++++ .../minio-mc/mc-idp-ldap-accesskey-ls.rst | 6 +- .../minio-mc/mc-idp-ldap-accesskey.rst | 5 + source/reference/minio-mc/mc-ilm-rule-add.rst | 108 ++++++++- source/reference/minio-mc/mc-ilm-tier-add.rst | 27 +++ .../minio-mc/mc-license-register.rst | 102 +++++++-- .../minio-mc/minio-client-settings.rst | 16 +- 11 files changed, 544 insertions(+), 48 deletions(-) create mode 100644 source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst diff --git a/source/includes/common-minio-ad-ldap-params.rst b/source/includes/common-minio-ad-ldap-params.rst index 28ddf6e0..26ebd91b 100644 --- a/source/includes/common-minio-ad-ldap-params.rst +++ b/source/includes/common-minio-ad-ldap-params.rst @@ -139,6 +139,8 @@ This command works against :ref:`access keys ` created by an AD/LDAP user after authenticating to MinIO. +Create AD/LDAP service accounts with the :mc-cmd:`mc idp ldap accesskey create` command. + Authenticated users can manage their own long-term Access Keys using the :ref:`MinIO Console `. MinIO supports using :ref:`AssumeRoleWithLDAPIdentity ` to generate temporary access keys using the :ref:`Security Token Service `. diff --git a/source/includes/common-replication.rst b/source/includes/common-replication.rst index 98200730..61dad50c 100644 --- a/source/includes/common-replication.rst +++ b/source/includes/common-replication.rst @@ -141,6 +141,12 @@ Each MinIO deployment ("peer site") synchronizes the following changes across th Site replication enables :ref:`bucket versioning ` for all new and existing buckets on all replicated sites. +.. versionadded:: mc RELEASE.2023-12-02T02-03-28Z + +You can choose to replicate ILM expiration rules across peer sites. +For new site replication configurations, use the :mc-cmd:`mc admin replicate add` with the :mc-cmd:`~mc admin replicate add --replicate-ilm-expiry` flag. +For existing site replication configurations, you can enable or disable the behavior using :mc-cmd:`mc admin replicate update` with either the :mc-cmd:`~mc admin replicate update --enable-ilm-expiry-replication` or :mc-cmd:`~mc admin replicate update --disable-ilm-expiry-replication` flag, as appropriate. + .. end-mc-admin-replicate-what-replicates .. start-mc-admin-replicate-what-does-not-replicate diff --git a/source/operations/troubleshooting.rst b/source/operations/troubleshooting.rst index 3e8c53c4..c95d45b7 100644 --- a/source/operations/troubleshooting.rst +++ b/source/operations/troubleshooting.rst @@ -95,8 +95,7 @@ Download the license file from SUBNET on a machine with access to the Internet. #. Log in to |SUBNET| #. Go to the :guilabel:`Deployments` tab -#. Select the deployment from the list -#. Select the :guilabel:`License` number near the top of the page to display the :guilabel:`Cluster License Key` +#. Select the :guilabel:`License` button near the top of the page on the right side of the account statistics information box to display the :guilabel:`Account License` #. Select :guilabel:`Download` SUBNET Issues diff --git a/source/reference/minio-mc-admin/mc-admin-replicate.rst b/source/reference/minio-mc-admin/mc-admin-replicate.rst index 93a6e17d..7a2cacf1 100644 --- a/source/reference/minio-mc-admin/mc-admin-replicate.rst +++ b/source/reference/minio-mc-admin/mc-admin-replicate.rst @@ -105,6 +105,13 @@ Syntax mc admin replicate add minio1 minio5 + The following command creates a new site replication configuration with ILM expiration rule synchronization between peer sites ``minio1``, ``minio2``, and ``minio3``. + + .. code-block:: shell + :class: copyable + + mc admin replicate add minio1 minio2 minio3 --replicate-ilm-expiry + .. tab-item:: SYNTAX The command has the following syntax: @@ -115,7 +122,8 @@ Syntax mc [GLOBALFLAGS] admin replicate add \ ALIAS1 \ ALIAS2 \ - [ALIAS3 ...] + [ALIAS3 ...] \ + [--replicate-ilm-expiry] .. mc-cmd:: ALIAS :required: @@ -130,6 +138,13 @@ Syntax Then include one or more additional :ref:`aliases ` to add to the existing site replication. The deployments to add must be empty. + .. mc-cmd:: --replicate-ilm-expiry + :optional: + + .. versionadded:: mc RELEASE.2023-12-02T02-03-28Z + + Replicate :ref:`ILM expiration ` rules across peers. + .. mc-cmd:: update :fullpath: @@ -161,7 +176,9 @@ Syntax ALIAS \ --deployment-id [deploymentID] \ --endpoint [newEndpoint] \ - --mode ["sync" | "async"] + --mode ["sync" | "async"] \ + --enable-ilm-expiry-replication \ + --disable-ilm-expiry-replication .. mc-cmd:: ALIAS :required: @@ -198,6 +215,21 @@ Syntax The deployment ID can be found by running :mc-cmd:`mc admin replicate info ALIAS` + .. mc-cmd:: --disable-ilm-expiry-replication + :optional: + + .. versionadded:: mc RELEASE.2023-12-02T02-03-28Z + + Stops the replication of ILM expiration rules between peer sites. + Existing rules already synchronized across peers are not removed from any peer site. + + .. mc-cmd:: --enable-ilm-expiry-replication + :optional: + + .. versionadded:: mc RELEASE.2023-12-02T02-03-28Z + + Start replication of ILM expiration rules between peer sites. + .. mc-cmd:: --endpoint :required: @@ -361,21 +393,24 @@ Syntax minio1 \ --user janedoe - The output of any of the above examples resembles the following: + The output of the above examples resembles the following: .. code-block:: shell Bucket replication status: - - 30/30 Buckets in sync + ● 30/30 Buckets in sync Policy replication status: - - 5/5 Policies in sync + ● 5/5 Policies in sync User replication status: - - 3/3 Users in sync + ● 3/3 Users in sync Group replication status: No Groups present + + ILM Expiry Rules replication status: + ● 5/5 ILM Expiry Rules in sync Object replication status: Replication status since 1 day @@ -384,20 +419,37 @@ Syntax Queued: - 0 objects, (0 B) (avg: 0 objects, 0 B; max: 0 objects, 0 B) Received: 0 objects (0 B) + Display the site replication status across sites for the ILM expiration rule with rule ID of ``ckok9v5b4dtgofkbi6tg`` for a site replication configuration that contains the site ``minio1``. + + .. code-block:: shell + + mc admin replicate status minio1 --ilm-expiry-rule ckok9v5b4dtgofkbi6tg + + The output resembles the following: + + .. code-block:: shell + + ● ILM Expiry Rule replication summary for: ckok9v5b4dtgofkbi6tg + + ILMExpiryRule | MINIO1 | MINIO2 + ILM Expiry Rule | ✔ | ✔ + .. tab-item:: SYNTAX .. code-block:: shell - mc [GLOBALFLAGS] admin replicate status \ - TARGET \ - [--all] \ - [--buckets] \ - [--bucket nameOfBucket] \ - [--groups] \ - [--group nameOfGroup] \ - [--policies] \ - [--policy nameOfPolicy] \ - [--users] \ + mc [GLOBALFLAGS] admin replicate status \ + TARGET \ + [--all] \ + [--buckets] \ + [--bucket nameOfBucket] \ + [--groups] \ + [--group nameOfGroup] \ + [--ilm-expiry-rules] \ + [--ilm-expiry-rule ] \ + [--policies] \ + [--policy nameOfPolicy] \ + [--users] \ [--user accessKey] .. mc-cmd:: TARGET @@ -430,6 +482,24 @@ Syntax Display the replication status of a specific group by including the group name after the flag. + .. mc-cmd:: --ilm-expiry-rules + :optional: + + .. versionadded:: mc RELEASE.2023-12-02T02-03-28Z + + Display sync information about ILM expiration rules. + + Mutually exclusive with :mc-cmd:`~mc admin replicate status --ilm-expiry-rule` + + .. mc-cmd:: --ilm-expiry-rule + :optional: + + .. versionadded:: mc RELEASE.2023-12-02T02-03-28Z + + Display replication status information about the specified ILM expiration rule. + + Mutually exclusive with :mc-cmd:`~mc admin replicate status --ilm-expiry-rules` + .. mc-cmd:: --policies :optional: diff --git a/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst b/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst new file mode 100644 index 00000000..0535a0e3 --- /dev/null +++ b/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst @@ -0,0 +1,215 @@ +.. _minio-mc-idp-ldap-accesskey-create: + +================================ +``mc idp ldap accesskey create`` +================================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + + +.. mc:: mc idp ldap accesskey create + +.. versionadded:: mc RELEASE.2023-12-23T08-47-21Z + +Description +----------- + +.. start-mc-idp-ldap-accesskey-create-desc + +The :mc:`mc idp ldap accesskey create` allows you to add LDAP access key pairs. + +.. end-mc-idp-ldap-accesskey-create-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following example creates a new access key pair with the same policy as the authenticated user on the ``minio`` :ref:`alias `: + + .. code-block:: shell + :class: copyable + + mc idp ldap accesskey create minio/ + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] idp ldap accesskey create \ + ALIAS \ + [--access-key ] \ + [--secret-key ] \ + [--policy ] \ + [--name ] \ + [--description ] \ + [--expiry-duration ] \ + [--login ] + + - Replace ``ALIAS`` with the :ref:`alias ` of a MinIO deployment configured for AD/LDAP integration. + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment configured for AD/LDAP. + + For example: + + .. code-block:: none + + mc idp ldap accesskey create minio + +.. mc-cmd:: --access-key + :optional: + + An access key to use for the account. + + Requires :mc-cmd:`~mc idp ldap accesskey create --secret-key` + +.. mc-cmd:: --secret-key + :optional: + + A secret to use for the account. + + Requires :mc-cmd:`~mc idp ldap accesskey create --access-key` + +.. mc-cmd:: --policy + :optional: + + File path to the JSON-formatted policy to use for the account. + + If not specified, the account uses the same policy as the authenticated user. + +.. mc-cmd:: --name + :optional: + + A human-readable name to use for the account. + +.. mc-cmd:: --description + :optional: + + Add a description for the service account. + For example, you might specify the reason the access key exists. + +.. mc-cmd:: --expiry-duration + :optional: + + Length of time the access key pair should remain valid for use in ``#d#h#s`` format. + + For example, ``7d``, ``24h``, ``5d12h30s`` are valid strings. + + Mutually exclusive with :mc-cmd:`~mc idp ldap accesskey create --expiry`. + +.. mc-cmd:: --expiry + :optional: + + The date after which the access key expires. + Enter the date in YYYY-MM-DD format. + + For example, to expire the credentials after December 31, 2024, enter ``2024-12-31``. + + Mutually exclusive with :mc-cmd:`~mc idp ldap accesskey create --expiry-duration`. + +.. mc-cmd:: --login + :optional: + + Prompts the user to log in using the LDAP credentials to use to generate the access key. + Specify the URL of the LDAP-configured MinIO Server to use for the login prompt. + + Requires an interactive terminal. + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility + +Examples +-------- + +Create a new access-key pair for the authenticated user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair to use with the currently authenticated user on the ``minio`` alias. +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create minio + +Create a new access-key pair with a custom access key and secret key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair with both an access key and secret key that you specify for the user currently authenticated on the ``minio`` alias. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create minio/ --access-key my-access-key-change-me --secret-key my-secret-key-change-me + +Create a new access-key pair that expires after 24 hours +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair to use with the currently authenticated user on the ``minio`` alias. +The credentials expire after 24 hours. + +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create minio --expiry-duration 24h + +Create a new access-key and prompt to login as the user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair. +The MinIO Client will first ask you to log in as the user the access key is for on the MinIO site configured for LDAP at ``minio.example.com``. + +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create minio --login minio.example.com + +Create a new access-key pair that expires after a date +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair to use with the currently authenticated user on the ``minio`` alias. +The credentials expire after February 29, 2024. + +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create minio --expiry 2024-02-29 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-idp-ldap-accesskey-ls.rst b/source/reference/minio-mc/mc-idp-ldap-accesskey-ls.rst index 0aee8493..58b5e26f 100644 --- a/source/reference/minio-mc/mc-idp-ldap-accesskey-ls.rst +++ b/source/reference/minio-mc/mc-idp-ldap-accesskey-ls.rst @@ -52,7 +52,7 @@ The :mc:`mc idp ldap accesskey ls` displays a list of LDAP access key pairs. mc [GLOBALFLAGS] idp ldap accesskey ls \ ALIAS \ - [--permanent-only] \ + [--svcacc-only] \ [--temp-only] \ [--users-only] \ [DN] ... @@ -81,10 +81,10 @@ Parameters mc idp ldap accesskey ls minio -.. mc-cmd:: --permanent-only +.. mc-cmd:: --svcacc-only :optional: - Output only permanent access keys. + Output only service account access keys. Mutually exclusive with :mc-cmd:`~mc idp ldap accesskey ls --temp-only`. diff --git a/source/reference/minio-mc/mc-idp-ldap-accesskey.rst b/source/reference/minio-mc/mc-idp-ldap-accesskey.rst index d8b9c340..0edc7690 100644 --- a/source/reference/minio-mc/mc-idp-ldap-accesskey.rst +++ b/source/reference/minio-mc/mc-idp-ldap-accesskey.rst @@ -38,6 +38,11 @@ The :mc-cmd:`mc idp ldap accesskey` command has the following subcommands: * - Subcommand - Description + * - :mc-cmd:`mc idp ldap accesskey create` + - .. include:: /reference/minio-mc/mc-idp-ldap-accesskey-create.rst + :start-after: start-mc-idp-ldap-accesskey-create-desc + :end-before: end-mc-idp-ldap-accesskey-create-desc + * - :mc-cmd:`mc idp ldap accesskey ls` - .. include:: /reference/minio-mc/mc-idp-ldap-accesskey-ls.rst :start-after: start-mc-idp-ldap-accesskey-ls-desc diff --git a/source/reference/minio-mc/mc-ilm-rule-add.rst b/source/reference/minio-mc/mc-ilm-rule-add.rst index ec8835af..a0dfb4c6 100644 --- a/source/reference/minio-mc/mc-ilm-rule-add.rst +++ b/source/reference/minio-mc/mc-ilm-rule-add.rst @@ -71,6 +71,8 @@ The command supports adding both :ref:`Transition (Tiering) `__ to use to log in to Azure storage. + + This option only applies if :mc-cmd:`~mc ilm tier add TIER_TYPE` is ``azure`` and you log in using an service principal identity. + This option has no effect for any other value of ``TIER_TYPE``. + +.. mc-cmd:: --azure-sp-client-id + :optional: + + Client ID for the `service principal account `__ to use to log in to Azure storage. + + This option only applies if :mc-cmd:`~mc ilm tier add TIER_TYPE` is ``azure`` and you log in using an service principal identity. + This option has no effect for any other value of ``TIER_TYPE``. + +.. mc-cmd:: --azure-sp-client-secret + :optional: + + The client secret for the `service principal account `__ to use to log in to Azure storage. + + This option only applies if :mc-cmd:`~mc ilm tier add TIER_TYPE` is ``azure`` and you log in using an service principal identity. + This option has no effect for any other value of ``TIER_TYPE``. + Global Flags ~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-license-register.rst b/source/reference/minio-mc/mc-license-register.rst index f382ce69..3dd215e5 100644 --- a/source/reference/minio-mc/mc-license-register.rst +++ b/source/reference/minio-mc/mc-license-register.rst @@ -49,6 +49,74 @@ The :mc-cmd:`mc license register` command connects your deployment with your |SU After registration, you can upload deployment health reports directly to SUBNET using the :mc-cmd:`mc support diag` command. +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following example registers the ``minio`` :ref:`alias ` with |SUBNET|: + + .. code-block:: shell + :class: copyable + + mc license register minio + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] license register ALIAS \ + [--airgap] \ + [--api-key ] \ + [--license ] \ + [--name ] + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + :required: + + The :ref:`alias ` of the MinIO deployment. + + +.. mc-cmd:: --airgap + :optional: + + Use in environments without network access to SUBNET (for example, airgapped, firewalled, or similar configuration). + + For instructions, see the :ref:`airgap example `. + + If the deployment is airgapped, but the local device where you are using the :ref:`minio client ` has network access, you do not need to use the ``--airgap`` flag. + +.. mc-cmd:: --api-key + + API of the account on SUBNET. + + Corresponds with the ``MC_SUBNET_API_KEY`` environment variable. + + To find the API key: + + #. Log in to |SUBNET| + #. Go to the :guilabel:`Deployments` tab + #. Select the :guilabel:`API Key` button near the top of the page on the right side of the account statistics information box + #. Select copy button to the right of the key field to copy the key value to your clipboard + +.. mc-cmd:: --license + :optional: + + Path to the license file to use for registering the deployment. + + You must first :ref:`download the license file ` for the account. + +.. mc-cmd:: --name + :optional: + + Specify a name other than the alias to associate to the MinIO deployment in SUBNET. + + Use ``--name `` replacing ```` with the name you want to use for the deployment on SUBNET. Examples -------- @@ -65,6 +133,18 @@ Register the MinIO deployment at alias ``minio1`` on SUBNET, using ``minio1`` as If not already registered, a prompt asks for SUBNET credentials for the deployment. +Register a Deployment Using the Account's License File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register a new MinIO deployment at alias ``minio5`` on SUBNET, using the license file downloaded for the account: + +.. code-block:: shell + :class: copyable + + mc license register minio5 /path/to/minio.license + +If not already downloaded, you can :ref:`download the license file ` from SUBNET. + Register a Deployment with a Different Deployment Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -117,29 +197,7 @@ The command has the following syntax: [--name value] \ [--airgap] -Parameters -~~~~~~~~~~ -.. mc-cmd:: ALIAS - :required: - - The :ref:`alias ` of the MinIO deployment. - -.. mc-cmd:: --name - :optional: - - Specify a name other than the alias to associate to the MinIO deployment in SUBNET. - - Use ``--name `` replacing ```` with the name you want to use for the deployment on SUBNET. - -.. mc-cmd:: --airgap - :optional: - - Use in environments without network access to SUBNET (for example, airgapped, firewalled, or similar configuration). - - For instructions, see the :ref:`airgap example `. - - If the deployment is airgapped, but the local device where you are using the :ref:`minio client ` has network access, you do not need to use the ``--airgap`` flag. Global Flags diff --git a/source/reference/minio-mc/minio-client-settings.rst b/source/reference/minio-mc/minio-client-settings.rst index b5ae2abc..ec19de15 100644 --- a/source/reference/minio-mc/minio-client-settings.rst +++ b/source/reference/minio-mc/minio-client-settings.rst @@ -88,16 +88,20 @@ STS Service Use this setting to add an STS endpoint to use for `mc` commands. +.. versionchanged:: mc RELEASE.2023-12-02T02-03-28Z + +Supports adding multiple environment variables by alias. + .. tab-set:: .. tab-item:: Environment Variable :selected: - .. envvar:: MC_STS_ENDPOINT + .. envvar:: MC_STS_ENDPOINT_ .. code-block:: shell - export MC_STS_ENDPOINT=https://sts.minio-operator.svc.cluster.local:4223/sts/ns-1 + export MC_STS_ENDPOINT_myalias=https://sts.minio-operator.svc.cluster.local:4223/sts/ns-1 .. tab-item:: Configuration Setting @@ -112,16 +116,20 @@ Web Token Identity Use this setting to add a web token identity to use for `mc` commands. +.. versionchanged:: mc RELEASE.2023-12-02T02-03-28Z + +Supports adding multiple environment variables by alias. + .. tab-set:: .. tab-item:: Environment Variable :selected: - .. envvar:: MC_WEB_IDENITY_TOKEN + .. envvar:: MC_WEB_IDENITY_TOKEN_ .. code-block:: shell - export MC_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/kubernetes.io/serviceaccount/token + export MC_WEB_IDENTITY_TOKEN_FILE_myalias=/var/run/secrets/kubernetes.io/serviceaccount/token .. tab-item:: Configuration Setting