From db4b1c8cb1be9c33f3bd45c074016d45bd5de41f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 6 Nov 2024 16:07:57 +0700 Subject: [PATCH 1/3] Add tt cluster rs roles subcommand --- doc/tooling/tt_cli/cluster.rst | 77 ++++++++++++++++++++++++++++++---- 1 file changed, 68 insertions(+), 9 deletions(-) diff --git a/doc/tooling/tt_cli/cluster.rst b/doc/tooling/tt_cli/cluster.rst index ba4f60956..ffd01cb77 100644 --- a/doc/tooling/tt_cli/cluster.rst +++ b/doc/tooling/tt_cli/cluster.rst @@ -116,7 +116,7 @@ To add a new instance ``instance-003`` to the ``replicaset-001`` replica set: .. code-block:: console - tt cluster publish "http://localhost:2379/myapp?name=instance-003" instance_source.yaml --replicaset replicaset-001 + $ tt cluster publish "http://localhost:2379/myapp?name=instance-003" instance_source.yaml --replicaset replicaset-001 .. _tt-cluster-publish-validation: @@ -265,12 +265,14 @@ subcommands: - :ref:`promote ` - :ref:`demote ` +- :ref:`expel ` +- :ref:`roles ` .. important:: ``tt cluster replicaset`` works only with centralized cluster configurations. - To manage replica set leaders in clusters with local YAML configurations, - use :ref:`tt replicaset promote ` and :ref:`tt replicaset demote `. + To manage replica sets in clusters with local YAML configurations, + use :ref:`tt replicaset `. .. _tt-cluster-replicaset-promote: @@ -332,6 +334,50 @@ to ``ro`` and reloads the configuration. If failover is ``off``, the command doesn't consider the modes of other replica set members, so there can be any number of read-write instances in one replica set. +.. _tt-cluster-replicaset-expel: + +expel +~~~~~ + +.. code-block:: console + + $ tt cluster replicaset expel CONFIG_URI INSTANCE_NAME [OPTION ...] + +``tt cluster replicaset expel`` expels an instance from the cluster. Example: + + $ tt cluster replicaset expel "http://localhost:2379" storage-b-002 + +.. _tt-cluster-replicaset-roles: + +roles +~~~~~ + +.. code-block:: console + + $ tt cluster replicaset roles [add|remove] CONFIG_URI ROLE_NAME [OPTION ...] + +``tt cluster replicaset roles`` manages :ref:`application roles ` +in the configuration scope specified in the command options. It has two subcommands: + +* ``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: + +.. code-block:: console + + $ 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-failover: @@ -507,21 +553,34 @@ Options .. option:: --force - **Applicable to:** ``publish`` + **Applicable to:** ``publish``, ``replicaset`` Skip validation when publishing. Default: `false` (validation is enabled). + TODO: update for replicaset + +.. option:: -G, --global + + **Applicable to:** ``replicaset roles`` + + Apply the operation to the global configuration scope, that is, to all instances. .. option:: --group - **Applicable to:** ``publish`` + **Applicable to:** ``publish``, ``replicaset roles`` + + A name of the configuration group to which the operation applies. + +.. option:: --instance + + **Applicable to:** ``replicaset roles`` - A name of the configuration group to which the instance belongs. + A name of the instance to which the operation applies. .. option:: --replicaset - **Applicable to:** ``publish`` + **Applicable to:** ``publish``, ``replicaset roles`` - A name of the replica set to which the instance belongs. + A name of the replica set to which the operation applies. .. option:: -t, --timeout UINT @@ -548,7 +607,7 @@ Options This option is supported by the `Enterprise Edition `_ only. - **Applicable to:** ``publish`` + **Applicable to:** ``publish``, ``replicaset`` Generate hashes and signatures for integrity checks. From e33444f860dd4deb64e011386539a9e50c05c765 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 7 Nov 2024 18:12:55 +0700 Subject: [PATCH 2/3] Add tt replicaset roles subcommand --- doc/tooling/tt_cli/cluster.rst | 77 ++++++++------- doc/tooling/tt_cli/replicaset.rst | 150 +++++++++++++++++++++++++++--- 2 files changed, 174 insertions(+), 53 deletions(-) diff --git a/doc/tooling/tt_cli/cluster.rst b/doc/tooling/tt_cli/cluster.rst index ffd01cb77..eca35d1a8 100644 --- a/doc/tooling/tt_cli/cluster.rst +++ b/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,8 +552,8 @@ 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 @@ -564,19 +561,19 @@ Options 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`` diff --git a/doc/tooling/tt_cli/replicaset.rst b/doc/tooling/tt_cli/replicaset.rst index 8a6c0a3da..dda1f692a 100644 --- a/doc/tooling/tt_cli/replicaset.rst +++ b/doc/tooling/tt_cli/replicaset.rst @@ -20,6 +20,7 @@ Managing replica sets * :ref:`vshard ` * :ref:`bootstrap ` * :ref:`rebootstrap ` +* :ref:`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 ` +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 `, + use :ref:`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 `__. + +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 `__. + +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 `_. + + .. _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,35 +566,55 @@ 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. @@ -509,15 +622,26 @@ Options 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 `_ only. + + **Applicable to:** ``publish``, ``replicaset`` + + Generate hashes and signatures for integrity checks. + .. option:: -y, --yes **Applicable to:** ``rebootstrap`` From 9df94d6a1e4d3ede462261ced645c6429ab634b3 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 7 Nov 2024 18:27:32 +0700 Subject: [PATCH 3/3] Fix --- doc/tooling/tt_cli/replicaset.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/tooling/tt_cli/replicaset.rst b/doc/tooling/tt_cli/replicaset.rst index dda1f692a..f8e2d0e34 100644 --- a/doc/tooling/tt_cli/replicaset.rst +++ b/doc/tooling/tt_cli/replicaset.rst @@ -638,7 +638,7 @@ Options This option is supported by the `Enterprise Edition `_ only. - **Applicable to:** ``publish``, ``replicaset`` + **Applicable to:** ``promote``, ``demote``, ``expel``, ``roles`` Generate hashes and signatures for integrity checks.