From 55531dcbae5bae2ca590aef165a57097348d4307 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 14 Dec 2023 18:03:25 +0700 Subject: [PATCH 1/2] Add TCM cluster connecting and configuration --- doc/reference/tooling/tcm/index.rst | 6 + .../tooling/tcm/tcm_access_control.rst | 7 +- doc/reference/tooling/tcm/tcm_audit_log.rst | 7 +- .../tooling/tcm/tcm_cluster_config.rst | 85 +++++++++ .../tooling/tcm/tcm_configuration.rst | 5 + .../tcm/tcm_configuration_reference.rst | 4 + .../tooling/tcm/tcm_connect_clusters.rst | 163 ++++++++++++++++++ 7 files changed, 269 insertions(+), 8 deletions(-) create mode 100644 doc/reference/tooling/tcm/tcm_cluster_config.rst create mode 100644 doc/reference/tooling/tcm/tcm_connect_clusters.rst diff --git a/doc/reference/tooling/tcm/index.rst b/doc/reference/tooling/tcm/index.rst index e4fa27b10d..4b52edfffa 100644 --- a/doc/reference/tooling/tcm/index.rst +++ b/doc/reference/tooling/tcm/index.rst @@ -3,11 +3,15 @@ Tarantool Cluster Manager ========================= +.. ee_note_tcm_start + .. admonition:: Enterprise Edition :class: fact |tcm_full_name| is a part of the `Enterprise Edition `_. +.. ee_note_tcm_end + |tcm_full_name| (|tcm|) is a web-based visual tool for configuring, managing, and monitoring Tarantool EE clusters. It provides a GUI for working with clusters and individual instances, from monitoring their state to executing commands interactively @@ -31,6 +35,8 @@ to read data. LDAP authorization is supported as well. .. toctree:: :maxdepth: 1 + tcm_connect_clusters + tcm_cluster_config tcm_access_control tcm_audit_log tcm_configuration diff --git a/doc/reference/tooling/tcm/tcm_access_control.rst b/doc/reference/tooling/tcm/tcm_access_control.rst index 8a11e59fb1..04e9f7b99c 100644 --- a/doc/reference/tooling/tcm/tcm_access_control.rst +++ b/doc/reference/tooling/tcm/tcm_access_control.rst @@ -3,10 +3,9 @@ Access control ============== -.. admonition:: Enterprise Edition - :class: fact - - |tcm_full_name| is a part of the `Enterprise Edition `_. +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end |tcm_full_name| features a role-based access control system. It enables flexible management of access to |tcm| functions, connected clusters, and stored data. diff --git a/doc/reference/tooling/tcm/tcm_audit_log.rst b/doc/reference/tooling/tcm/tcm_audit_log.rst index 07af2662f2..d702462027 100644 --- a/doc/reference/tooling/tcm/tcm_audit_log.rst +++ b/doc/reference/tooling/tcm/tcm_audit_log.rst @@ -3,10 +3,9 @@ Audit log ========= -.. admonition:: Enterprise Edition - :class: fact - - |tcm_full_name| is a part of the `Enterprise Edition `_. +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end |tcm_full_name| provides the audit logging functionality for tracking user activity and security-related events, such as: diff --git a/doc/reference/tooling/tcm/tcm_cluster_config.rst b/doc/reference/tooling/tcm/tcm_cluster_config.rst new file mode 100644 index 0000000000..533c5fa58f --- /dev/null +++ b/doc/reference/tooling/tcm/tcm_cluster_config.rst @@ -0,0 +1,85 @@ +.. _tcm_configuring_clusters: + +Configuring clusters +==================== + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| features a built-in text editor for Tarantool EE cluster configurations. + +When you :ref:`connect a cluster ` to |tcm|, it gains access +to the cluster's centralized configuration storage: an etcd or a Tarantool cluster. +|tcm| has both read and write access to the cluster configuration. This enables +the configuration editor to work in two ways: + +* If a configuration already exists, the editor shows its current state. +* When you change the configuration in the editor and apply changes, they + are sent to the configuration storage. + +To learn how to write Tarantool cluster configurations, see :ref:`configuration`. + +.. _tcm_configuring_clusters_manage: + +Managing a cluster's configuration +---------------------------------- + +The configuration editor is available on the **Cluster** > **Configuration** page. + +To start managing a cluster's configuration, select this cluster in the **Cluster** +drop-down and go to the **Configuration** page. + +A cluster configuration in |tcm| can consist of one or multiple YAML files. +When there are multiple files, they are all considered parts of a single cluster +configuration. You can use this for structuring big cluster configurations. +All files that form the configuration of a cluster are listed on the left side +of the **Cluster configuration** page. + +To add a cluster configuration file, click the plus icon (**+**) below the page title. + +To open a configuration file in the editor, click its name in the file list. + +To delete a cluster configuration file, click the **Delete** button beside the filename. + +To download a cluster configuration file, click the **Download** button beside the filename. + +.. warning:: + + All configuration changes are discarded when you leave the **Cluster configuration** page. + :ref:`Save ` the configuration if you want to continue + editing it later or :ref:`apply ` it + to start using it on the cluster. + +.. _tcm_configuring_clusters_save: + +Saving a configuration draft +---------------------------- + +|tcm| can store configurations drafts. If you want to leave an unfinished configuration +and return to it later, save it in |tcm|. Saving applies to whole cluster configurations: +it records the edits of all files, file additions, and file deletions. + +To save a cluster configuration draft after editing, click **Save** in the **Cluster configuration** page. + +All unsaved changes are discarded when you leave the **Cluster configuration** page. + +If you have a saved configuration draft, you can reset the changes for each of its +files individually. A reset returns the file into the state that is currently used +by a cluster (that is, saved in the configuration storage). If you reset a newly +added file, it is deleted. + +To reset an saved configuration file, click the **Reset** button beside the filename. + + +.. _tcm_configuring_clusters_apply: + +Applying a configuration +------------------------ + +When you finish editing a configuration and it's ready to use, apply the updated +configuration to the cluster. To apply a cluster configuration, click **Apply** +on the **Cluster configuration** page. This sends the new configuration to the cluster +configuration storage, and it comes into effect upon the cluster configuration reload. + + diff --git a/doc/reference/tooling/tcm/tcm_configuration.rst b/doc/reference/tooling/tcm/tcm_configuration.rst index 88af38f768..c2179cef80 100644 --- a/doc/reference/tooling/tcm/tcm_configuration.rst +++ b/doc/reference/tooling/tcm/tcm_configuration.rst @@ -3,6 +3,11 @@ Configuration ============= + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + .. TODO: write specific configuration tutorials for http, security, logging, and so on. (https://github.com/tarantool/doc/issues/3545) This topic describes how to configure |tcm_full_name|. For the complete diff --git a/doc/reference/tooling/tcm/tcm_configuration_reference.rst b/doc/reference/tooling/tcm/tcm_configuration_reference.rst index 85fd59b82b..dec444ea2d 100644 --- a/doc/reference/tooling/tcm/tcm_configuration_reference.rst +++ b/doc/reference/tooling/tcm/tcm_configuration_reference.rst @@ -3,6 +3,10 @@ Configuration reference ======================= +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + This topic describes :ref:`configuration parameters ` of |tcm_full_name|. There are the following groups of |tcm| configuration parameters: diff --git a/doc/reference/tooling/tcm/tcm_connect_clusters.rst b/doc/reference/tooling/tcm/tcm_connect_clusters.rst new file mode 100644 index 0000000000..2dfbc3d3c3 --- /dev/null +++ b/doc/reference/tooling/tcm/tcm_connect_clusters.rst @@ -0,0 +1,163 @@ +.. _tcm_connect_clusters: + +Сonnecting clusters +=================== + +.. include:: index.rst + :start-after: ee_note_tcm_start + :end-before: ee_note_tcm_end + +|tcm_full_name| works with clusters that: + +* run on Tarantool EE 3.0 or later +* use :ref:`centralized configuration ` stored in etcd or another Tarantool cluster. + +A single |tcm| installation can have multiple connected clusters. A connection to +|tcm| doesn't affect the cluster's functioning. You can connect clusters to |tcm| +and disconnect them on the fly. + +There are two ways to add a cluster to |tcm|: + +- Connect an existing cluster. +- Add a new cluster and :ref:`write its configuration ` from scratch in the |tcm| web UI. + +In both cases, you need to deploy Tarantool and start the cluster instances using +the :ref:`tt-cli` or another suitable way. + +.. _tcm_connect_clusters_parameters: + +Connection parameters +--------------------- + +When connecting a cluster to |tcm|, you need to provide two sets of connection parameters: +for the cluster instances and for the centralized configuration storage. + +Configuration storage connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The cluster configuration can be stored in either an :ref:`etcd ` +cluster or a separate Tarantool-based storage. In both cases, the following connection +parameters are required: + +* A key prefix used to identify the cluster in the configuration storage. + A prefix must be unique for each cluster in storage. +* URIs of all instances of the configuration storage. +* The credentials for accessing the configuration storage: an `etcd user `__ + or a :ref:`Tarantool user ` and . + +Additionally, if SSL or TLS encryption is enabled for the configuration storage, +provide the corresponding encryption configuration: keys, certificates, and other +parameters. For the complete list of parameters, consult the `etcd documentation `__ +or Tarantool :ref:`enterprise-iproto-encryption`. + +Cluster connection +~~~~~~~~~~~~~~~~~~ + +For interaction with the cluster instances, |tcm| needs the following access parameters: + +* A :ref:`Tarantool user ` that exists in the cluster and their password. + |tcm| connects to the cluster on behalf of this user. +* An :ref:`SSL configuration ` if the traffic encryption + is enabled on the cluster. + +Managing connected clusters +--------------------------- + +Administrators can add new clusters, edit, and remove existing ones from |tcm|. + +Connected clusters are listed on the **Clusters** page. + +.. _tcm_connect_clusters_connect_preconf: + +Connecting a pre-configured cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you already have a cluster and want connect it to |tcm|, +follow these steps: + +#. Go to **Clusters** and click **Add**. +#. Fill in the general cluster information: + + * Specify an arbitrary name. + * Optionally, provide a description and select a color to mark this cluster in |tcm|. + * Optionally, enter the URLs of additional services for the cluster. For example, + a Grafana dashboard that monitors the cluster metrics, ot a syslog server + for viewing the cluster logs. |tcm| provides quick access to these URLs on + the cluster **Stateboard** page. + +3. Provide the details of the cluster configuration storage: + + * Storage type: **etcd** or **tarantool**. + * The **Prefix** specified in the cluster configuration. + * The URIs of the configuration storage instances. + * The credentials for accessing the configuration storage. + * The SSL/TLS parameters if the connection encryption is enabled on the storage. + +4. Provide the credentials for accessing the cluster: a Tarantool user's name, their password, + and SSL parameters in case :ref:`traffic encryption ` + is enabled on the cluster. + +.. _tcm_connect_clusters_connect_new: + +Adding a new cluster +~~~~~~~~~~~~~~~~~~~~ + +If you don't have a cluster yet, you can add one in |tcm| and write its configuration +from scratch using the :ref:`built-in configuration editor `. + +.. important:: + + When adding a new cluster, you need to have a storage for its configuration up + and running so that |tcm| can connect to it. Cluster instances can be deployed later. + +To add a new cluster: + +#. Go to **Clusters** and click **Add**. +#. Fill in the general cluster information: + + * Specify an arbitrary name. + * Optionally, provide a description and select a color to mark this cluster in |tcm|. + * Optionally, enter the URLs of additional services for the cluster. For example, + a Grafana dashboard that monitors the cluster metrics, ot a syslog server + for viewing the cluster logs. |tcm| provides quick access to these URLs on + the cluster **Stateboard** page. + +#. Select the type of the cluster configuration storage: **etcd** or **tarantool**. +#. Define a unique **Prefix** for identifying this cluster in the configuration storage. +#. Provide the connection details for the cluster configuration storage: + + * The URIs of configuration storage instances. + * The credentials for accessing the configuration storage. + * The SSL/TLS parameters if the connection encryption is enabled on the storage. + +#. Provide the cluster credentials: a username, a password, and SSL parameters in + case :ref:`traffic encryption ` is enabled on + the cluster. + +Once you add the cluster: + +* Set up the cluster configuration using the |tcm| :ref:`configuration editor `. +* Deploy Tarantool on the cluster nodes using the :ref:`tt-cli` or other suitable tools. +* Start the cluster using the :ref:`tt-cli` or other suitable tools. + +.. _tcm_connect_clusters_edit: + +Editing a connected cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To edit a connected cluster, go to **Clusters** and click **Edit** in the **Actions** +menu of the corresponding table row. + +.. _tcm_connect_clusters_disconnect: + +Disconnecting a cluster +~~~~~~~~~~~~~~~~~~~~~~~ + +To disconnect a cluster from |tcm|, go to **Clusters** and click **Disconnect** +in the **Actions** menu of the corresponding table row. + +.. note:: + + Disconnecting a cluster does not affect its functioning. The only + thing that is changed is that it's no longer shown in |tcm|. + You can connect this cluster again at any time. \ No newline at end of file From befa65d59758b43df08ba70878478ad4723a23b0 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 15 Dec 2023 14:41:55 +0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com> --- doc/reference/tooling/tcm/tcm_cluster_config.rst | 2 +- doc/reference/tooling/tcm/tcm_connect_clusters.rst | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/reference/tooling/tcm/tcm_cluster_config.rst b/doc/reference/tooling/tcm/tcm_cluster_config.rst index 533c5fa58f..817433baa3 100644 --- a/doc/reference/tooling/tcm/tcm_cluster_config.rst +++ b/doc/reference/tooling/tcm/tcm_cluster_config.rst @@ -69,7 +69,7 @@ files individually. A reset returns the file into the state that is currently us by a cluster (that is, saved in the configuration storage). If you reset a newly added file, it is deleted. -To reset an saved configuration file, click the **Reset** button beside the filename. +To reset a saved configuration file, click the **Reset** button beside the filename. .. _tcm_configuring_clusters_apply: diff --git a/doc/reference/tooling/tcm/tcm_connect_clusters.rst b/doc/reference/tooling/tcm/tcm_connect_clusters.rst index 2dfbc3d3c3..5f2c3e83e7 100644 --- a/doc/reference/tooling/tcm/tcm_connect_clusters.rst +++ b/doc/reference/tooling/tcm/tcm_connect_clusters.rst @@ -43,7 +43,7 @@ parameters are required: A prefix must be unique for each cluster in storage. * URIs of all instances of the configuration storage. * The credentials for accessing the configuration storage: an `etcd user `__ - or a :ref:`Tarantool user ` and . + or a :ref:`Tarantool user `. Additionally, if SSL or TLS encryption is enabled for the configuration storage, provide the corresponding encryption configuration: keys, certificates, and other @@ -72,7 +72,7 @@ Connected clusters are listed on the **Clusters** page. Connecting a pre-configured cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you already have a cluster and want connect it to |tcm|, +If you already have a cluster and want to connect it to |tcm|, follow these steps: #. Go to **Clusters** and click **Add**. @@ -81,7 +81,7 @@ follow these steps: * Specify an arbitrary name. * Optionally, provide a description and select a color to mark this cluster in |tcm|. * Optionally, enter the URLs of additional services for the cluster. For example, - a Grafana dashboard that monitors the cluster metrics, ot a syslog server + a Grafana dashboard that monitors the cluster metrics, or a syslog server for viewing the cluster logs. |tcm| provides quick access to these URLs on the cluster **Stateboard** page. @@ -118,7 +118,7 @@ To add a new cluster: * Specify an arbitrary name. * Optionally, provide a description and select a color to mark this cluster in |tcm|. * Optionally, enter the URLs of additional services for the cluster. For example, - a Grafana dashboard that monitors the cluster metrics, ot a syslog server + a Grafana dashboard that monitors the cluster metrics, or a syslog server for viewing the cluster logs. |tcm| provides quick access to these URLs on the cluster **Stateboard** page. @@ -159,5 +159,5 @@ in the **Actions** menu of the corresponding table row. .. note:: Disconnecting a cluster does not affect its functioning. The only - thing that is changed is that it's no longer shown in |tcm|. + thing that changes is that it's no longer shown in |tcm|. You can connect this cluster again at any time. \ No newline at end of file