diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_config/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_config/config.yaml new file mode 100644 index 0000000000..7ba68f27f1 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_config/config.yaml @@ -0,0 +1,30 @@ +credentials: + users: + guest: + roles: [super] +groups: + group-001: + replicasets: + replicaset-001: + replication: + failover: manual + leader: instance-001 + instances: + instance-001: + iproto: + listen: + - uri: '127.0.0.1:3301' + advertise: + client: '127.0.0.1:3301' + instance-002: + iproto: + listen: + - uri: '127.0.0.1:3302' + advertise: + client: '127.0.0.1:3302' + instance-003: + iproto: + listen: + - uri: '127.0.0.1:3303' + advertise: + client: '127.0.0.1:3303' \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_config/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_config/instances.yml new file mode 100644 index 0000000000..cb21a1f662 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_config/instances.yml @@ -0,0 +1,3 @@ +instance-001: +instance-002: +instance-003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/config.yaml new file mode 100644 index 0000000000..52616f5e84 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/config.yaml @@ -0,0 +1,5 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /default \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/instances.yml new file mode 100644 index 0000000000..cb21a1f662 --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/instances.yml @@ -0,0 +1,3 @@ +instance-001: +instance-002: +instance-003: \ No newline at end of file diff --git a/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/myapp.lua new file mode 100644 index 0000000000..5a489d1eec --- /dev/null +++ b/doc/code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/myapp.lua @@ -0,0 +1,20 @@ +function create_space() + box.schema.space.create('bands') + box.space.bands:format({ + { name = 'id', type = 'unsigned' }, + { name = 'band_name', type = 'string' }, + { name = 'year', type = 'unsigned' } + }) + box.space.bands:create_index('primary', { type = "tree", parts = { 'id' } }) + box.schema.user.grant('guest', 'read,write,execute', 'universe') +end + +function load_data() + box.space.bands:insert { 1, 'Roxette', 1986 } + box.space.bands:insert { 2, 'Scorpions', 1965 } + box.space.bands:insert { 3, 'Ace of Base', 1987 } +end + +function select_data() + box.space.bands:select { 3 } +end \ No newline at end of file diff --git a/doc/how-to/getting_started_tcm.rst b/doc/how-to/getting_started_tcm.rst new file mode 100644 index 0000000000..d30b499bdf --- /dev/null +++ b/doc/how-to/getting_started_tcm.rst @@ -0,0 +1,397 @@ +.. _getting_started_tcm: + +Getting started with Tarantool Cluster Manager +============================================== + +.. admonition:: Enterprise Edition + :class: fact + + This tutorial uses `Tarantool Enterprise Edition `_. + +In this tutorial, you get :ref:`tcm` up and running on your local system, deploy +a local Tarantool EE cluster, and learn to manage the cluster from the |tcm| web UI. + +To complete this tutorial, you need: + +* A Linux machine with glibc 2.17 or later. +* A web browser: Chromium-based (Chromium version 108 or later), Mozilla Firefox 101 or later, or another up-to-date browser. +* The Tarantool Enterprise Edition SDK 3.0 or later in the ``tar.gz`` archive. + See :ref:`enterprise-setup` for information about getting the archive. + +For more detailed information about using |tcm|, refer to :ref:`tcm`. + +.. _getting_started_tcm_setup: + +Setting up Tarantool EE +----------------------- + +#. Extract the Tarantool EE SDK archive: + + .. code-block:: console + + $ tar -xvzf tarantool-enterprise-sdk-gc64---r.linux.x86_64.tar.gz + + This creates the ``tarantool-enterprise`` directory beside the archive. + The directory contains three executables for key Tarantool EE components: + + * ``tarantool`` -- Tarantool Enterprise Edition. + * ``tt`` -- the :ref:`tt ` command-line utility. + * ``tcm`` -- :ref:`tcm`. + +#. Add the Tarantool EE components to the executable path by executing the ``env.sh`` + script included in the distribution: + + .. code-block:: console + + $ source tarantool-enterprise/env.sh + +#. To check that the Tarantool EE executables ``tarantool``, ``tt``, + and ``tcm`` are available in the system, print their versions: + + .. code-block:: console + + $ tarantool --version + Tarantool Enterprise 3.0.0-0-gf58f7d82a-r23-gc64 + Target: Linux-x86_64-RelWithDebInfo + Build options: cmake . -DCMAKE_INSTALL_PREFIX=/home/centos/release/sdk/tarantool/static-build/tarantool-prefix -DENABLE_BACKTRACE=TRUE + Compiler: GNU-9.3.1 + C_FLAGS: -fexceptions -funwind-tables -fasynchronous-unwind-tables -static-libstdc++ -fno-common -msse2 -fmacro-prefix-map=/home/centos/release/sdk/tarantool=. -std=c11 -Wall -Wextra -Wno-gnu-alignof-expression -fno-gnu89-inline -Wno-cast-function-type -O2 -g -DNDEBUG -ggdb -O2 + CXX_FLAGS: -fexceptions -funwind-tables -fasynchronous-unwind-tables -static-libstdc++ -fno-common -msse2 -fmacro-prefix-map=/home/centos/release/sdk/tarantool=. -std=c++11 -Wall -Wextra -Wno-invalid-offsetof -Wno-gnu-alignof-expression -Wno-cast-function-type -O2 -g -DNDEBUG -ggdb -O2 + $ tt version + Tarantool CLI EE 2.1.0, linux/amd64. commit: d80c2e3 + $ tcm version + 1.0.0-0-gd38b12c2 + +.. _getting_started_tcm_start: + +Starting TCM +------------ + +|tcm_full_name| is ready to run out of the box. To start |tcm| run the following command: + +.. code-block:: console + + $ tcm --storage.etcd.embed.enabled + +.. important:: + + The |tcm| bootstrap log in the terminal includes a message with the credentials + to use for the first login. Make sure to save them somewhere. + + .. code-block:: text + + Jan 24 05:51:28.443 WRN Generated super admin credentials login=admin password=qF3A5rjGurjAwmlYccJ7JrL5XqjbIHY6 + + +The :ref:`--storage.etcd.embed.enabled ` +option makes |tcm| start its own instance of `etcd `__ on bootstrap. +This ``etcd`` instance is used for storing the :ref:`TCM configuration `. + +.. note:: + + During the development, it is also convenient to use the TCM-embedded etcd + as a configuration storage for Tarantool EE clusters connected to TCM. + Learn more in :ref:`configuration_etcd`. + +.. _getting_started_tcm_login: + +Logging into TCM +---------------- + +#. Open a web browser and go to ``http://127.0.0.1:8080/``. +#. Enter the username and the password you got from the |tcm| bootstrap log in the previous step. +#. Click **Log in**. + +After a successful login, you see the |tcm| web UI: + +.. image:: images/tcm_start_empty_cluster.png + :width: 700 + :align: center + :alt: TCM stateboard with empty cluster + +.. _getting_started_tcm_cluster: + +Setting up a Tarantool EE cluster +--------------------------------- + +To prepare a Tarantool EE cluster, complete the following steps: + +#. Define the cluster connection settings in |tcm|. +#. Configure the cluster in |tcm|. +#. Start the cluster instances locally using the :ref:`tt ` utility. + +.. _getting_started_tcm_cluster_connection: + +Defining the cluster's connection settings in TCM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A freshly installed |TCM| has a predefined cluster named **Default cluster**. It +doesn't have any configuration or topology out of the box. Its initial properties +include the etcd and Tarantool connection parameters. Check these properties +to find out where TCM sends the cluster configuration that you write. + +To view the **Default cluster**'s properties: + +#. Go to **Clusters** and click **Edit** in the **Actions** menu opposite the cluster name. + + .. image:: images/tcm_start_cluster_edit.png + :width: 700 + :align: center + :alt: TCM edit cluster + +#. Click **Next** on the **General** tab. + + .. image:: images/tcm_start_cluster_general.png + :width: 700 + :align: center + :alt: General cluster settings + +#. Find the connection properties of the configuration storage that the cluster uses. + By default, it's an etcd running on port ``2379`` (default etcd port) on the same host. + The key prefix used for the cluster configuration is ``/default``. Click **Next**. + + .. image:: images/tcm_start_cluster_storage.png + :width: 700 + :align: center + :alt: Cluster configuration storage settings + +#. Check the Tarantool user that |tcm| uses to connect to the cluster instances. + It's ``guest`` by default. + + .. image:: images/tcm_start_cluster_tarantool.png + :width: 700 + :align: center + :alt: Cluster Tarantool connection settings + + +.. _getting_started_tcm_cluster_config: + +Configuring a cluster in TCM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +|tcm| provides a web-based editor for writing cluster configurations. It is connected +to the configuration storage (etcd in this case): all changes you make in the browser +are sent to etcd in one click. + +To write the cluster configuration and upload it to the etcd storage: + +#. Go to **Configuration**. +#. Click **+** and provide an arbitrary name for the configuration file, for example, ``all``. +#. Paste the following :ref:`YAML configuration ` into the editor: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started_config/config.yaml + :language: yaml + :dedent: + + This configuration sets up a cluster of three nodes in one replica set: + one leader and two followers. + +#. Click **Apply** to send the configuration to etcd. + + .. image:: images/tcm_start_cluster_config.png + :width: 700 + :align: center + :alt: Cluster configuration in TCM + +When the cluster configuration is saved, you can see the cluster topology on the **Stateboard** page: + +.. image:: images/tcm_start_stateboard_offline.png + :width: 700 + :align: center + :alt: Offline cluster stateboard + +However, the cluster instances are offline because they aren't deployed yet. + +.. _getting_started_tcm_cluster_deploy: + +Deploying the cluster locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To deploy a local cluster based on the configuration from etcd: + +#. Go to the system terminal you used when setting up Tarantool. +#. Create a new ``tt`` environment in a directory of your choice: + + .. code-block:: console + + $ mkdir cluster-env + $ cd cluster-env/ + $ tt init + +#. Inside the ``instances.enabled`` directory of the created tt environment, create the ``cluster`` directory. + + .. code-block:: console + + $ mkdir instances.enabled/cluster + $ cd instances.enabled/cluster/ + +#. Inside ``instances.enabled/cluster``, create the ``instances.yml`` and ``config.yaml`` files: + + * ``instances.yml`` specifies instances to run in the current environment. In this example, there are three instances: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/instances.yml + :language: yaml + :dedent: + + * ``config.yaml`` instructs ``tt`` to load the cluster configuration from etcd. + The specified etcd location matches the configuration storage of the **Default cluster** in TCM: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/config.yaml + :language: yaml + :dedent: + +#. Start the cluster from the ``tt`` environment root (the ``cluster-env`` directory): + + .. code-block:: console + + $ tt start cluster + + To check how the cluster started, run ``tt status``. This output should look like this: + + .. code-block:: console + + $ tt status cluster + INSTANCE STATUS PID + cluster:instance-001 RUNNING 2058 + cluster:instance-002 RUNNING 2059 + cluster:instance-003 RUNNING 2060 + +.. _getting_started_tcm_manage: + +Managing the cluster in TCM +--------------------------- + +To learn to interact with a cluster in |tcm|, complete typical database tasks such as: + +* Checking the cluster state. +* Creating a space. +* Writing data. +* Viewing data. + +.. _getting_started_tcm_manage_check: + +Checking cluster state +~~~~~~~~~~~~~~~~~~~~~~ + +To check the cluster state in |tcm|, go to **Stateboard**. Here you see the overview +of the cluster topology, health, memory consumption, and other information. + +.. image:: images/tcm_start_stateboard_online.png + :width: 700 + :align: center + :alt: Online cluster stateboard + +.. _getting_started_tcm_manage_connect: + +Connecting to an instance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To view detailed information about an instance, click its name in the instances list +on the **Stateboard** page. + +.. image:: images/tcm_start_instance_details.png + :width: 700 + :align: center + :alt: Instance details in TCM + +To connect to the instance interactively and execute code on it, go to the **Terminal** tab. + +.. image:: images/tcm_start_instance_terminal.png + :width: 700 + :align: center + :alt: Instance terminal in TCM + +.. _getting_started_tcm_manage_space: + +Creating a space +~~~~~~~~~~~~~~~~ + +Go to the terminal of ``instance-001`` (the leader instance) and run the following code to +create a formatted space with a primary index in the cluster: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/myapp.lua + :language: lua + :lines: 2-8 + :dedent: + +.. _getting_started_tcm_manage_write: + +Writing data +~~~~~~~~~~~~ + +Since ``instance-001`` is a read-write instance (its ``box.info.ro`` is ``false``), +the write requests must be executed on it. Run the following code in the ``instance-001`` +terminal to write tuples in the space: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/myapp.lua + :language: lua + :lines: 13-15 + :dedent: + +.. _getting_started_tcm_manage_read: + +Reading data +~~~~~~~~~~~~ + +Check the space's tuples by running a read request on ``instance-001``: + + .. literalinclude:: /code_snippets/snippets/config/instances.enabled/tcm_get_started_tt/myapp.lua + :language: lua + :lines: 19 + :dedent: + +This is how it looks in |tcm|: + +.. image:: images/tcm_start_instance_write.png + :width: 700 + :align: center + :alt: Writing data through TCM + +.. _getting_started_tcm_manage_replication: + +Checking replication +~~~~~~~~~~~~~~~~~~~~ + +To check that the data is replicated across instances, run the read request on any +other instance -- ``instance-002`` or ``instance-003``. The result is the same as on ``instance-001``. + +.. image:: images/tcm_start_instance_read.png + :width: 700 + :align: center + :alt: Reading data through TCM + +.. note:: + + If you try to execute a write request on any instance but ``instance-001``, + you get an error because these instances are configured to be read-only. + +.. _getting_started_tcm_manage_view: + +Viewing data in TCM +~~~~~~~~~~~~~~~~~~~ + +|tcm| web UI includes a tool for viewing data stored in the cluster. To view +the space tuples in |tcm|: + +#. Click an instance name on the **Stateboard** page. +#. Open the **Actions** menu in the top-right corner and click **Explorer**. + + .. image:: images/tcm_start_explorer.png + :width: 700 + :align: center + :alt: Opening Explorer in TCM + + This opens the page that lists user-created spaces on the instance. + + .. image:: images/tcm_start_explorer_spaces.png + :width: 700 + :align: center + :alt: TCM Explorer: spaces + +#. Click **View** in the **Actions** menu of the space you want to see. The page + shows all the tuples added previously. + + .. image:: images/tcm_start_explorer_tuples.png + :width: 700 + :align: center + :alt: TCM Explorer: space tuples diff --git a/doc/how-to/images/tcm_start_cluster_config.png b/doc/how-to/images/tcm_start_cluster_config.png new file mode 100644 index 0000000000..ba69fbe0f5 Binary files /dev/null and b/doc/how-to/images/tcm_start_cluster_config.png differ diff --git a/doc/how-to/images/tcm_start_cluster_edit.png b/doc/how-to/images/tcm_start_cluster_edit.png new file mode 100644 index 0000000000..0b92eeb52f Binary files /dev/null and b/doc/how-to/images/tcm_start_cluster_edit.png differ diff --git a/doc/how-to/images/tcm_start_cluster_general.png b/doc/how-to/images/tcm_start_cluster_general.png new file mode 100644 index 0000000000..cf03802876 Binary files /dev/null and b/doc/how-to/images/tcm_start_cluster_general.png differ diff --git a/doc/how-to/images/tcm_start_cluster_storage.png b/doc/how-to/images/tcm_start_cluster_storage.png new file mode 100644 index 0000000000..0a5090d965 Binary files /dev/null and b/doc/how-to/images/tcm_start_cluster_storage.png differ diff --git a/doc/how-to/images/tcm_start_cluster_tarantool.png b/doc/how-to/images/tcm_start_cluster_tarantool.png new file mode 100644 index 0000000000..785115fca5 Binary files /dev/null and b/doc/how-to/images/tcm_start_cluster_tarantool.png differ diff --git a/doc/how-to/images/tcm_start_empty_cluster.png b/doc/how-to/images/tcm_start_empty_cluster.png new file mode 100644 index 0000000000..4b1199a28e Binary files /dev/null and b/doc/how-to/images/tcm_start_empty_cluster.png differ diff --git a/doc/how-to/images/tcm_start_explorer.png b/doc/how-to/images/tcm_start_explorer.png new file mode 100644 index 0000000000..d39b8528fb Binary files /dev/null and b/doc/how-to/images/tcm_start_explorer.png differ diff --git a/doc/how-to/images/tcm_start_explorer_spaces.png b/doc/how-to/images/tcm_start_explorer_spaces.png new file mode 100644 index 0000000000..8a1718e43b Binary files /dev/null and b/doc/how-to/images/tcm_start_explorer_spaces.png differ diff --git a/doc/how-to/images/tcm_start_explorer_tuples.png b/doc/how-to/images/tcm_start_explorer_tuples.png new file mode 100644 index 0000000000..2472d756e9 Binary files /dev/null and b/doc/how-to/images/tcm_start_explorer_tuples.png differ diff --git a/doc/how-to/images/tcm_start_instance_details.png b/doc/how-to/images/tcm_start_instance_details.png new file mode 100644 index 0000000000..aec6843617 Binary files /dev/null and b/doc/how-to/images/tcm_start_instance_details.png differ diff --git a/doc/how-to/images/tcm_start_instance_read.png b/doc/how-to/images/tcm_start_instance_read.png new file mode 100644 index 0000000000..5481ac5f80 Binary files /dev/null and b/doc/how-to/images/tcm_start_instance_read.png differ diff --git a/doc/how-to/images/tcm_start_instance_terminal.png b/doc/how-to/images/tcm_start_instance_terminal.png new file mode 100644 index 0000000000..acc7136b74 Binary files /dev/null and b/doc/how-to/images/tcm_start_instance_terminal.png differ diff --git a/doc/how-to/images/tcm_start_instance_write.png b/doc/how-to/images/tcm_start_instance_write.png new file mode 100644 index 0000000000..1b0ba4f4e4 Binary files /dev/null and b/doc/how-to/images/tcm_start_instance_write.png differ diff --git a/doc/how-to/images/tcm_start_stateboard_offline.png b/doc/how-to/images/tcm_start_stateboard_offline.png new file mode 100644 index 0000000000..2828506cdc Binary files /dev/null and b/doc/how-to/images/tcm_start_stateboard_offline.png differ diff --git a/doc/how-to/images/tcm_start_stateboard_online.png b/doc/how-to/images/tcm_start_stateboard_online.png new file mode 100644 index 0000000000..c712544bec Binary files /dev/null and b/doc/how-to/images/tcm_start_stateboard_online.png differ diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst index f95685c0af..e8a1fb50c9 100644 --- a/doc/how-to/index.rst +++ b/doc/how-to/index.rst @@ -19,6 +19,7 @@ If you are new to Tarantool, please see our Creating Tarantool database getting_started_connectors db/index + getting_started_tcm getting_started_net_box vshard_quick app/index