From 5f52c9aefaa5b6bf75972ab6d03074d313e14e51 Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Mon, 25 Sep 2023 15:18:19 +0300 Subject: [PATCH] Document the 'tt cartridge' command --- doc/reference/tooling/tt_cli/cartridge.rst | 514 +++++++++++++++++++++ doc/reference/tooling/tt_cli/commands.rst | 3 + 2 files changed, 517 insertions(+) create mode 100644 doc/reference/tooling/tt_cli/cartridge.rst diff --git a/doc/reference/tooling/tt_cli/cartridge.rst b/doc/reference/tooling/tt_cli/cartridge.rst new file mode 100644 index 0000000000..800b22482f --- /dev/null +++ b/doc/reference/tooling/tt_cli/cartridge.rst @@ -0,0 +1,514 @@ +.. _tt_cartridge: + +Managing a Cartridge application +================================ + +.. code-block:: bash + + tt cartridge COMMAND [command options] + +``tt cartridge`` manages a Cartridge application. +``COMMAND`` is one of the following: + +* :ref:`admin ` +* :ref:`bench ` +* :ref:`failover ` +* :ref:`repair ` +* :ref:`replicasets ` + + +.. _tt_cartridge_admin: + +admin +----- + +.. code-block:: bash + + tt cartridge admin ADMIN_FUNC_NAME [options] + +``tt cartridge admin`` calls `admin functions `_ provided by the application. + +.. _tt_cartridge_admin_options: + +Options +~~~~~~~ + +.. option:: --name STRING + + (Required) An application name. + +.. option:: -l, --list + + List the available admin functions. + +.. option:: --instance STRING + + A name of the instance to connect to. + +.. option:: --conn STRING + + An address to connect to. + +.. option:: --run-dir STRING + + A directory where PID and socket files are stored. Defaults to ``/var/run/tarantool``. + + +.. _tt_cartridge_admin_examples: + +Example +~~~~~~~ + +Get a list of the available admin functions: + +.. code-block:: bash + + tt cartridge admin --name APPNAME --list + + • Available admin functions: + + probe Probe instance + +Get help for a specific function: + +.. code-block:: bash + + tt cartridge admin --name APPNAME probe --help + + • Admin function "probe" usage: + + Probe instance + + Args: + --uri string Instance URI + +Call a function with an argument: + +.. code-block:: bash + + tt cartridge admin --name APPNAME probe --uri localhost:3301 + + • Probe "localhost:3301": OK + + + +.. _tt_cartridge_bench: + +bench +----- + +.. code-block:: bash + + tt cartridge bench [options] + +``tt cartridge bench`` runs benchmarks for Tarantool. + +.. _tt_cartridge_bench_options: + +Options +~~~~~~~ + +.. option:: --url STRING + + A Tarantool instance address (the default is ``127.0.0.1:3301``). + +.. option:: --user STRING + + A username used to connect to the instance (the default is ``guest``). + +.. option:: --password STRING + + A password used to connect to the instance. + +.. option:: --connections INT + + A number of concurrent connections (the default is ``10``). + +.. option:: --requests INT + + A number of simultaneous requests per connection (the default is ``10``). + +.. option:: --duration INT + + The duration of a benchmark test in seconds (the default is ``10``). + +.. option:: --keysize INT + + The size of a key part of benchmark data in bytes (the default is ``10``). + +.. option:: --datasize INT + + The size of a value part of benchmark data in bytes (the default is ``20``). + +.. option:: --insert INT + + A percentage of inserts (the default is ``100``). + +.. option:: --select INT + + A percentage of selects. + +.. option:: --update INT + + A percentage of updates. + +.. option:: --fill INT + + A number of records to pre-fill the space (the default is ``1000000``). + + +.. _tt_cartridge_failover: + +failover +-------- + +.. code-block:: bash + + tt cartridge failover COMMAND [command options] + +``tt cartridge failover`` manages an application failover. + +.. _tt_cartridge_failover_commands: + +Subcommands +~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``set`` + - Setup failover in the specified mode: + + * ``stateful`` + * ``eventual`` + * ``disabled`` + + Usage: + + .. code-block:: bash + + tt cartridge failover set MODE [options] + + Options: + + * ``--state-provider STRING``: A failover's state provider. Can be ``stateboard`` or ``etcd2``. Used only in the ``stateful`` mode. + * ``--params STRING``: Failover parameters specified in a JSON-formatted string, for example, ``"{'fencing_timeout': 10', 'fencing_enabled': true}"``. + * ``--provider-params STRING``: Failover provider parameters specified in a JSON-formatted string, for example, ``"{'lock_delay': 14}"``. + + * - ``setup`` + - Setup failover with parameters described in a file. + The failover configuration file defaults to ``failover.yml``. + + Usage: + + .. code-block:: bash + + tt cartridge failover setup --file STRING + + The ``failover.yml`` file might look as follows: + + .. code-block:: yaml + + mode: stateful + state_provider: stateboard + stateboard_params: + uri: localhost:4401 + password: passwd + failover_timeout: 15 + + * - ``status`` + - Get the current failover status. + + Usage: + + .. code-block:: bash + + tt cartridge failover status + + * - ``disable`` + - Disable failover. + + Usage: + + .. code-block:: bash + + tt cartridge failover disable + + +.. _tt_cartridge_failover_options: + +Options +~~~~~~~ + +.. option:: --name STRING + + An application name. Defaults to "package" in rockspec. + +.. option:: --file STRING + + A path to the file containing failover settings. Defaults to ``failover.yml``. + + +.. _tt_cartridge_repair: + +repair +------ + +.. code-block:: bash + + tt cartridge repair COMMAND [command options] + +``tt cartridge repair`` repairs a running application. + +.. _tt_cartridge_repair_commands: + +Subcommands +~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``list-topology`` + - Get a summary of the current cluster topology. + + Usage: + + .. code-block:: bash + + tt cartridge repair list-topology [options] + + * - ``remove-instance`` + - Remove the instance with the specified UUID from the cluster. If the instance isn't found, raise an error. + + Usage: + + .. code-block:: bash + + tt cartridge repair remove-instance UUID [options] + + * - ``set-advertise-uri`` + - Change the instance's advertise URI. Raise an error if the instance isn't found or is expelled. + + Usage: + + .. code-block:: bash + + tt cartridge repair set-advertise-uri INSTANCE-UUID NEW-URI [options] + + * - ``set-leader`` + - Set the instance as the leader of the replica set. Raise an error in the following cases: + + * There is no replica set or instance with that UUID. + * The instance doesn't belong to the replica set. + * The instance has been disabled or expelled. + + Usage: + + .. code-block:: bash + + tt cartridge repair set-leader REPLICASET-UUID INSTANCE-UUID [options] + + +.. _tt_cartridge_repair_options: + +Options +~~~~~~~ + +The following options work with any ``repair`` subcommand: + +.. option:: --name + + (Required) An application name. + +.. option:: --data-dir + + The directory containing the instances' working directories. Defaults to ``/var/lib/tarantool``. + +The following options work with any ``repair`` command, except ``list-topology``: + +.. option:: --run-dir + + The directory where PID and socket files are stored. Defaults to ``/var/run/tarantool``. + +.. option:: --dry-run + + Launch in dry-run mode: show changes but do not apply them. + +.. option:: --reload + + Enable instance configuration to reload after the patch. + + + +.. _tt_cartridge_replicasets: + +replicasets +----------- + +.. code-block:: bash + + tt cartridge replicasets COMMAND [command options] + +``tt cartridge replicasets`` manages an application's replica sets. + + +.. _tt_cartridge_replicasets_commands: + +Subcommands +~~~~~~~~~~~ + +.. container:: table + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``setup`` + - Setup replica sets using a file. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets setup [options] + + Options: + + * ``--file``: A file with a replica set configuration. Defaults to ``replicasets.yml``. + * ``--bootstrap-vshard``: Bootstrap vshard upon setup. + + * - ``save`` + - Save the current replica set configuration to a file. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets save [options] + + Options: + + * ``--file``: A file to save the configuration to. Defaults to ``replicasets.yml``. + + * - ``list`` + - List the current cluster topology. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets list [options] + + Options: + + * ``--replicaset STRING``: A replica set name. + + * - ``join`` + - Join the instance to a cluster. + If a replica set with the specified alias isn't found in cluster, it is created. + Otherwise, instances are joined to an existing replica set. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets join INSTANCE_NAME... [options] + + Options: + + * ``--replicaset STRING``: A replica set name. + + * - ``list-roles`` + - List the available roles. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets list-roles [options] + + * - ``list-vshard-groups`` + - List the available vshard groups. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets list-vshard-groups [options] + + * - ``add-roles`` + - Add roles to the replica set. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets add-roles ROLE_NAME... [options] + + Options: + + * ``--replicaset STRING``: A replica set name. + * ``--vshard-group STRING``: A vshard group for ``vshard-storage`` replica sets. + + * - ``remove-roles`` + - Remove roles from the replica set. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets remove-roles ROLE_NAME... [options] + + Options: + + * ``--replicaset STRING``: A replica set name. + + * - ``set-weight`` + - Specify replica set weight. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets set-weight WEIGHT [options] + + Options: + + * ``--replicaset STRING``: A replica set name. + + * - ``set-failover-priority`` + - Configure replica set failover priority. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets set-failover-priority INSTANCE_NAME... [options] + + Options: + + * ``--replicaset STRING``: A replica set name. + + * - ``bootstrap-vshard`` + - Bootstrap vshard. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets bootstrap-vshard [options] + + * - ``expel`` + - Expel one or more instances from the cluster. + + Usage: + + .. code-block:: bash + + tt cartridge replicasets expel INSTANCE_NAME... [options] diff --git a/doc/reference/tooling/tt_cli/commands.rst b/doc/reference/tooling/tt_cli/commands.rst index 2447f9f46a..1910d867a6 100644 --- a/doc/reference/tooling/tt_cli/commands.rst +++ b/doc/reference/tooling/tt_cli/commands.rst @@ -16,6 +16,8 @@ help for the given command. - Show a list of installed binaries and their versions * - :doc:`build ` - Build an application locally + * - :doc:`cartridge ` + - Manage a Cartridge application * - :doc:`cat ` - Print the contents of ``.snap`` or ``.xlog`` files into stdout * - :doc:`cfg ` @@ -70,6 +72,7 @@ help for the given command. binaries build + cartridge cat cfg check