Add tt replicaset roles subcommand

Author: p7nov

doc/tooling/tt_cli/cluster.rst

@@ -345,6 +345,8 @@ expel
 
 ``tt cluster replicaset expel`` expels an instance from the cluster. Example:
 
+.. code-block:: console
+
     $ tt cluster replicaset expel "http://localhost:2379" storage-b-002
 
 .. _tt-cluster-replicaset-roles:
@@ -362,22 +364,45 @@ in the configuration scope specified in the command options. It has two subcomma
 *   ``add`` adds a role
 *   ``remove`` removes a role
 
-Use the ``--global``, ``--group``, ``--replicaset``, ``--instance`` options to select
-the configuration scope to add or remove the role. For example, to add a role to
-all instances in a replicaset:
+Use the ``--global``, ``--group``, ``--replicaset``, ``--instance`` options to specify
+the configuration scope to add or remove roles. For example, to add a role to
+all instances in a replica set:
 
 .. code-block:: console
 
-    $ tt cluster replicaset roles add "http://localhost:2379" roles.my-role \
-                                       --replicaset storage-a
+    $ tt cluster replicaset roles add "http://localhost:2379" roles.my-role --replicaset storage-a
 
 To remove a role defined in the global configuration scope:
 
 .. code-block:: console
 
-    $ tt cluster replicaset roles remove "http://localhost:2379" roles.my-role \
-                                       --global
+    $ tt cluster replicaset roles remove "http://localhost:2379" roles.my-role --global
+
+
+.. _tt-cluster-replicaset-details:
+
+Implementation details
+~~~~~~~~~~~~~~~~~~~~~~
 
+The changes that ``tt cluster replicaset`` makes to the configuration storage
+occur transactionally. Each call creates a new revision. In case of a revision mismatch,
+an error is raised.
+
+If the cluster configuration is distributed over multiple keys in the configuration
+storage (for example, in two paths ``/myapp/config/k1`` and ``/myapp/config/k2``),
+the affected instance configuration can be present in more that one of them.
+If it is found under several different keys, the command prompts the user to choose
+a key for patching. You can skip the selection by adding the ``-f``/``--force`` option:
+
+..  code-block:: console
+
+    $ tt cluster replicaset promote "http://localhost:2379/myapp" storage-001-a --force
+
+In this case, the command selects the key for patching automatically. A key's priority
+is determined by the detail level of the instance or replica set configuration stored
+under this key. For example, when failover is ``off``, a key with
+``instance.database`` options takes precedence over a key with the only ``instance`` field.
+In case of equal priority, the first key in the lexicographical order is patched.
 
 .. _tt-cluster-failover:
 
@@ -447,34 +472,6 @@ Example:
 
     $ tt cluster failover switch-status http://localhost:2379/myapp b1e938dd-2867-46ab-acc4-3232c2ef7ffe
 
-
-
-
-.. _tt-cluster-replicaset-details:
-
-Implementation details
-----------------------
-
-The changes that ``tt cluster replicaset`` makes to the configuration storage
-occur transactionally. Each call creates a new revision. In case of a revision mismatch,
-an error is raised.
-
-If the cluster configuration is distributed over multiple keys in the configuration
-storage (for example, in two paths ``/myapp/config/k1`` and ``/myapp/config/k2``),
-the affected instance configuration can be present in more that one of them.
-If it is found under several different keys, the command prompts the user to choose
-a key for patching. You can skip the selection by adding the ``-f``/``--force`` option:
-
-..  code-block:: console
-
-    $ tt cluster replicaset promote "http://localhost:2379/myapp" storage-001-a --force
-
-In this case, the command selects the key for patching automatically. A key's priority
-is determined by the detail level of the instance or replica set configuration stored
-under this key. For example, when failover is ``off``, a key with
-``instance.database`` options takes precedence over a key with the only ``instance`` field.
-In case of equal priority, the first key in the lexicographical order is patched.
-
 .. _tt-cluster-authentication:
 
 Authentication
@@ -555,28 +552,28 @@ Options
 
     **Applicable to:** ``publish``, ``replicaset``
 
-    Skip validation when publishing. Default: `false` (validation is enabled).
-    TODO: update for replicaset
+    -   ``publish``: skip validation when publishing. Default: `false` (validation is enabled).
+    -   ``replicaset``: skip key selection for patching. Learn more in :ref:`tt-cluster-replicaset-details:`.
 
 ..  option:: -G, --global
 
     **Applicable to:** ``replicaset roles``
 
     Apply the operation to the global configuration scope, that is, to all instances.
 
-..  option:: --group
+..  option:: -g, --group
 
     **Applicable to:** ``publish``, ``replicaset roles``
 
     A name of the configuration group to which the operation applies.
 
-..  option:: --instance
+..  option:: -i, --instance
 
     **Applicable to:** ``replicaset roles``
 
     A name of the instance to which the operation applies.
 
-..  option:: --replicaset
+..  option:: -r, --replicaset
 
     **Applicable to:** ``publish``, ``replicaset roles``
 

doc/tooling/tt_cli/replicaset.rst

@@ -20,6 +20,7 @@ Managing replica sets
 *   :ref:`vshard <tt-replicaset-vshard>`
 *   :ref:`bootstrap <tt-replicaset-bootstrap>`
 *   :ref:`rebootstrap <tt-replicaset-rebootstrap>`
+*   :ref:`roles <tt-replicaset-roles>`
 
 .. _tt-replicaset-status:
 
@@ -391,6 +392,98 @@ To automatically confirm reboostrap, add the ``-y``/``--yes`` option:
 
     $ tt replicaset rebootstrap myapp:storage-001 -y
 
+.. _tt-replicaset-roles:
+
+roles
+-----
+
+..  code-block:: console
+
+    $ tt replicaset roles [add|remove] APPLICATION[:APP_INSTANCE] ROLE_NAME [OPTIONS ...]
+    # or
+    $ tt rs roles [add|remove] APPLICATION[:APP_INSTANCE] ROLE_NAME [OPTIONS ...]
+
+``tt replicaset roles`` (``tt rs roles``) manages :ref:`application roles <application_roles>`
+in the cluster.
+This command works on Tarantool clusters with a local YAML
+configuration and Cartridge clusters. It has two subcommands:
+
+*   ``add`` adds a role
+*   ``remove`` removes a role
+
+.. note::
+
+    To manage roles in a Tarantool cluster with a :ref:`centralized configuration <configuration_etcd>`,
+    use :ref:`tt cluster replicaset roles <tt-cluster-replicaset-roles>`.
+
+
+.. _tt-replicaset-roles-config:
+
+Managing roles in clusters with local YAML configurations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When called on clusters with local YAML configurations, ``tt replicaset roles``
+subcommands add or remove the corresponding lines from the configuration file
+and reload the configuration.
+
+Use the ``--global``, ``--group``, ``--replicaset``, ``--instance`` options to specify
+the configuration scope to add or remove roles. For example, to add a role to
+all instances in a replica set:
+
+.. code-block:: console
+
+    $ tt replicaset roles add my-app roles.my-role --replicaset storage-a
+
+You can also manage roles of a specific instance by specifying its name after the application name:
+
+.. code-block:: console
+
+    $ tt replicaset roles add my-app:router-001 roles.my-role
+
+To remove a role defined in the global configuration scope:
+
+.. code-block:: console
+
+    $ tt replicaset roles remove my-app roles.my-role --global
+
+If some instances of the affected scope are running outside the current ``tt``
+environment, ``tt replicaset roles`` can't ensure the configuration reload on
+them and reports an error. You can skip this check by adding the ``-f``/``--force`` option:
+
+..  code-block:: console
+
+    $ tt replicaset roles add my-app roles.my-role --replicaset storage-a --force
+
+
+.. _tt-replicaset-roles-cartridge:
+
+Managing roles in Cartridge clusters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+..  include:: _includes/cartridge_deprecation_note.rst
+
+When called on Cartridge clusters, ``tt replicaset roles`` subcommands add or remove
+Cartridge `cluster roles <https://www.tarantool.io/en/doc/2.11/book/cartridge/cartridge_dev/#cluster-roles>`__.
+
+Cartridge cluster roles are defined per replica set. Thus, you can use the
+``--replicaset`` and ``--group`` options to define a role's scope. In this case,
+a group is a `vshard group <https://www.tarantool.io/en/doc/2.11/book/cartridge/cartridge_dev/#using-multiple-vshard-storage-groups>`__.
+
+To add a role to a Cartridge cluster replica set:
+
+..  code-block:: console
+
+    $ tt replicaset roles add my-cartridge-app my-role --replicaset storage-001
+
+To remove a role from a vshard group:
+
+..  code-block:: console
+
+    $ tt replicaset roles remove my-cartridge-app my-role --group cold-data
+
+Learn more about `Cartridge cluster roles <https://www.tarantool.io/en/doc/2.11/book/cartridge/cartridge_dev/#cluster-roles>`_.
+
+
 .. _tt-replicaset-orchestrator:
 
 Selecting the application orchestrator manually
@@ -462,7 +555,7 @@ Options
 
     Force a custom orchestrator for Tarantool 2.x clusters.
 
-..  option:: --file FILE
+..  option:: --file STRING
 
     **Applicable to:** ``bootstrap``
 
@@ -473,51 +566,82 @@ Options
 
 ..  option:: -f, --force
 
-    **Applicable to:** ``promote``, ``demote``
+    **Applicable to:** ``promote``, ``demote``, ``roles``
 
-    Skip promotion or demotion if the specified instance is not running in the same environment.
+    Skip operation on instances not running in the same environment.
 
-..  option:: --replicaset REPLICASET
+..  option:: -G, --global
 
-    **Applicable to:** ``bootstrap``
+    **Applicable to:** ``roles`` on Tarantool 3.x and later
+
+    Apply the operation to the global configuration scope, that is, to all instances.
+
+..  option:: -g, --group STRING
+
+    **Applicable to:** ``roles``
+
+    A name of the configuration group to which the operation applies.
+
+
+..  option:: -i, --instance STRING
+
+    **Applicable to:** ``roles``
 
-    A replica set name for instance bootstrapping.
+    A name of the instance to which the operation applies. Not applicable to Cartridge clusters.
+    Learn more in :ref:`tt-replicaset-roles-cartridge`.
+
+..  option:: -r, --replicaset STRING
+
+    **Applicable to:** ``bootstrap``, ``roles``
+
+    A name of the replica set to which the operation applies.
 
     See also: :ref:`tt-replicaset-bootstrap-instance`
 
-..  option:: -u USERNAME, --username USERNAME
+..  option:: -u, --username STRING
 
     A Tarantool user for connecting to the instance using a URI.
 
-..  option:: -p PASSWORD, --password PASSWORD
+..  option:: -p, --password STRING
 
     The user's password.
 
-..  option:: --sslcertfile FILEPATH
+..  option:: --sslcertfile STRING
 
     The path to an SSL certificate file for encrypted connections for the URI case.
 
-..  option:: --sslkeyfile FILEPATH
+..  option:: --sslkeyfile STRING
 
     The path to a private SSL key file for encrypted connections for the URI case.
 
-..  option:: --sslcafile FILEPATH
+..  option:: --sslcafile STRING
 
     The path to a trusted certificate authorities (CA) file for encrypted connections for the URI case.
 
 ..  option:: --sslciphers STRING
 
     The list of SSL cipher suites used for encrypted connections for the URI case, separated by colons (``:``).
 
-..  option:: --timeout
+..  option:: --timeout UINT
 
     **Applicable to:** ``promote``, ``demote``, ``expel``, ``vshard``, ``bootstrap``
 
     The timeout for completing the operation, in seconds. Default:
 
-    -   ``3`` for ``promote``, ``demote``, ``expel``
+    -   ``3`` for ``promote``, ``demote``, ``expel``, ``roles``
     -   ``10`` for ``vshard`` and ``bootstrap``
 
+..  option:: --with-integrity-check STRING
+
+    ..  admonition:: Enterprise Edition
+        :class: fact
+
+        This option is supported by the `Enterprise Edition <https://www.tarantool.io/compare/>`_ only.
+
+    **Applicable to:** ``publish``, ``replicaset``
+
+    Generate hashes and signatures for integrity checks.
+
 ..  option:: -y, --yes
 
     **Applicable to:** ``rebootstrap``