diff --git a/doc/tooling/tcm/tcm_configuration.rst b/doc/tooling/tcm/tcm_configuration.rst index f9929c1c0..93ce3aaad 100644 --- a/doc/tooling/tcm/tcm_configuration.rst +++ b/doc/tooling/tcm/tcm_configuration.rst @@ -162,6 +162,8 @@ multiple |tcm| installations: - Command-line options for parameters that must be unique for different |tcm| instances running on a single server. For example, ``http.port``. +.. _tcm_configuration_types: + Configuration parameter types ----------------------------- @@ -219,6 +221,8 @@ packages documentation `__. websession-cookie: same-site: SameSiteStrictMode +.. _tcm_configuration_template: + Creating a configuration template --------------------------------- @@ -229,4 +233,101 @@ To write a default |tcm| configuration to the ``tcm.example.yml`` file, run: .. code-block:: console - $ tcm generate-config > tcm.example.yml. \ No newline at end of file + $ tcm generate-config > tcm.example.yml. + +.. _tcm_configuration_initial: + +Initial settings +---------------- + +You can use YAML configuration files to create entities in |tcm| automatically +upon the first start. These entities are defined in the :ref:`tcm_configuration_reference_initial` +section of the configuration file. + +.. important:: + + The initial settings are applied **only once** upon the first |tcm| start. + Further changes are **not applied** upon |tcm| restarts. + +.. _tcm_configuration_initial_clusters: + +Clusters +~~~~~~~~ + +To add clusters to |tcm| upon the first start, specify their settings in the +:ref:`initial-settings.clusters ` +configuration section. + +The ``initial-settings.clusters`` section is an array whose items describe separate clusters, +for example: + +.. code-block:: yaml + + initial-settings: + clusters: + - name: Cluster 1 + description: First cluster + # cluster settings + - name: Cluster 2 + description: Second cluster + # cluster settings + +In this configuration, you can specify all cluster settings that you define +when :ref:`connecting clusters ` through the |tcm| web interface. +This includes: + +- the cluster name +- description +- additional URLs +- configuration storage connection +- Tarantool instances connection +- and other settings. + +For the full list of cluster configuration parameters, see the :ref:`initial-settings.clusters ` +reference. For example, this is how you add a cluster that uses an etcd configuration +storage: + + +.. code-block:: yaml + + initial-settings: + clusters: + - name: My cluster + description: Cluster description + urls: + - label: Test + url: http://example.com + storage-connection: + provider: etcd + etcd-connection: + endpoints: + - http://127.0.0.1:2379 + username: "" + password: "" + prefix: /cluster1 + tarantool-connection: + username: guest + password: "" + +By default, |tcm| contains a cluster named **Default cluster** with ID +``00000000-0000-0000-0000-000000000000``. You can use this ID to modify +the default cluster settings upon the first |tcm| start. For example, rename it +and add its connection settings: + +.. code-block:: yaml + + initial-settings: + clusters: + - id: 00000000-0000-0000-0000-000000000000 + name: My cluster + storage-connection: + provider: etcd + etcd-connection: + endpoints: + - http://127.0.0.1:2379 + username: etcd-user + password: secret + prefix: /cluster1 + tarantool-connection: + username: guest + password: "" \ No newline at end of file diff --git a/doc/tooling/tcm/tcm_configuration_reference.rst b/doc/tooling/tcm/tcm_configuration_reference.rst index c9cd8b278..21a34d7da 100644 --- a/doc/tooling/tcm/tcm_configuration_reference.rst +++ b/doc/tooling/tcm/tcm_configuration_reference.rst @@ -19,6 +19,7 @@ There are the following groups of |tcm| configuration parameters: - :ref:`limits ` - :ref:`security ` - :ref:`mode ` +- :ref:`initial-settings ` .. _tcm_configuration_reference_cluster: @@ -131,7 +132,7 @@ Tarantool clusters. The name of the space field that is used as a sharding key. | - | Type: String + | Type: string | Default: `bucket_id` | Environment variable: TCM_CLUSTER_SHARDING_INDEX | Command-line option: ``--cluster.sharding-index`` @@ -1096,11 +1097,11 @@ The ``log`` section defines the |tcm| logging parameters. storage ------- -The ``storage`` section defines the parameters of the |tcm| data storage. +The ``storage`` section defines the parameters of the |tcm| :ref:`backend store `. - :ref:`storage.provider ` -etcd storage parameters: +etcd backend store parameters: - :ref:`storage.etcd.prefix ` - :ref:`storage.etcd.endpoints ` @@ -1176,7 +1177,7 @@ etcd storage parameters: - :ref:`storage.etcd.embed.initial-cluster-state ` - :ref:`storage.etcd.embed.self-signed-cert-validity ` -Tarantool storage parameters: +Tarantool backend store parameters: - :ref:`storage.tarantool.prefix ` - :ref:`storage.tarantool.addr ` @@ -1275,7 +1276,7 @@ Tarantool storage parameters: | | Type: time.Duration - | Default: 0s + | Default: 0 (disabled) | Environment variable: TCM_STORAGE_ETCD_AUTO_SYNC_INTERVAL | Command-line option: ``--storage.etcd.auto-sync-interval`` @@ -1549,10 +1550,11 @@ storage.etcd.embed.* ~~~~~~~~~~~~~~~~~~~~ The ``storage.etcd.embed`` group defines the configuration of the embedded etcd -cluster that can used as a |tcm| configuration storage. +cluster to use as a |tcm| backend store. This cluster can be used for development purposes when the production or testing etcd cluster is not available or not needed. +See also :ref:`tcm_backend_store_embed`. .. _tcm_configuration_reference_storage_tarantool_prefix: @@ -1911,10 +1913,11 @@ storage.tarantool.embed.* ~~~~~~~~~~~~~~~~~~~~~~~~~ The ``storage.tarantool.embed`` group parameters define the configuration of the -embedded Tarantool cluster that can used as a |tcm| configuration storage. +embedded Tarantool cluster to use as a |tcm| backend store. This cluster can be used for development purposes when the production or testing cluster is not available or not needed. +See also :ref:`tcm_backend_store_embed`. .. _tcm_configuration_reference_addon: @@ -2281,4 +2284,668 @@ The ``feature`` section defines the security parameters of |tcm|. | Type: bool | Default: false | Environment variable: TCM_FEATURE_API_TOKEN - | Command-line option: ``--feature.api-token`` \ No newline at end of file + | Command-line option: ``--feature.api-token`` + +.. _tcm_configuration_reference_initial: + +initial-settings +---------------- + +The ``initial-settings`` group defines entities that are created automatically +upon the first |tcm| startup. + +See also :ref:`tcm_configuration_initial`. + + +- :ref:`initial-settings.clusters ` + +.. important:: + + The ``initial-settings.*`` configuration options can be set in the YAML + configuration file only. There are no environment variables nor + command-line options for them. + +.. _tcm_configuration_reference_initial_clusters: + +.. confval:: initial-settings.clusters + + An array of clusters to create in |tcm| automatically upon the first startup. + + See also :ref:`tcm_configuration_initial`. + + | + | Type: []Cluster + | Default: [] + + +.. _tcm_configuration_reference_initial_cluster_id: + +.. confval:: initial-settings.clusters..id + + Cluster ID. Skip this option to generate an ID automatically. + Specify the value ``00000000-0000-0000-0000-000000000000`` + to customize the default cluster upon |tcm| startup. + + | + | Type: string + | Default: "" (ID is generated automatically) + + +.. _tcm_configuration_reference_initial_cluster_name: + +.. confval:: initial-settings.clusters..name + + Cluster name. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_description: + +.. confval:: initial-settings.clusters..description + + Cluster description. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_color: + +.. confval:: initial-settings.clusters..color + + A color to highlight the cluster in |tcm|. + Possible values: + + - ``dark`` + - ``gray`` + - ``red`` + - ``pink`` + - ``grape`` + - ``violet`` + - ``indigo`` + - ``blue`` + - ``cyan`` + - ``green`` + - ``lime`` + - ``yellow`` + - ``orange`` + - ``teal`` + - empty string (no color) + + | + | Type: string + | Default: "" (no color) + + +.. _tcm_configuration_reference_initial_cluster_urls: + +.. confval:: initial-settings.clusters..urls + + URLs of additional services for the cluster. See also :ref:`tcm_connect_clusters_connect_new`. + + | + | Type: []ClusterUrl + | Default: [] + + +.. _tcm_configuration_reference_initial_cluster_url_label: + +.. confval:: initial-settings.clusters...label + + URL label to show in |tcm|. Typically, this is the linked service name. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_url_url: + +.. confval:: initial-settings.clusters...url + + The URL address of the linked service. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_storage_provider: + +.. confval:: initial-settings.clusters..storage-connection.provider + + The type of the storage used for storing the cluster configuration. + + Possible values: + + - ``etcd`` + - ``tarantool`` + - empty string (undefined) + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_endpoints: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.endpoints + + An array of node URIs of the etcd cluster where the Tarantool cluster configuration is stored. + + | + | Type: []string + | Default: [] + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_autosync: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.auto-sync-interval + + An automated sync interval. + + | + | Type: time.Duration + | Default: 0 (disabled) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_dialtimeout: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.dial-timeout + + An etcd dial timeout. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_dialkatime: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.dial-keep-alive-time + + A dial keep-alive time. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_dialkatimeout: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.dial-keep-alive-timeout + + A dial keep-alive timeout. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_maxcallsend: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.max-call-send-msg-size + + The maximum size (in bytes) of a request from the cluster to its etcd + configuration storage. + + | + | Type: int + | Default: 2097152 + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_maxcallrecv: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.max-call-recv-msg-size + + The maximum size (in bytes) of a response to the cluster from its etcd + configuration storage. + + | + | Type: int + | Default: 0 (unlimited) + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_username: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.username + + A username for accessing the cluster's etcd storage. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_password: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.password + + A password for accessing the cluster's etcd storage. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_rejectold: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.reject-old-cluster + + Whether etcd should refuse to create a client against an outdated cluster. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_permitwostream: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.permit-without-stream + + Whether keepalive pings can be send to the etcd server without active streams. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_storage_etcd_prefix: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.prefix + + A prefix for the cluster configuration parameters in etcd. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_enabled: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.enabled + + Indicates whether TLS is enabled for connections to the cluster's etcd storage. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_cert-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.cert-file + + A path to a TLS certificate file to use for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_key-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.key-file + + A path to a TLS private key file to use for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_trusted-ca-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.trusted-ca-file + + A path to a trusted CA certificate file to use for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_client-cert-auth: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.client-cert-auth + + Indicates whether client cert authentication is enabled. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_crl-file: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.crl-file + + A path to the client certificate revocation list file. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_insecure-skip-verify: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.insecure-skip-verify + + Skip checking client certificate in etcd connections. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_skip-client-san-verify: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.skip-client-san-verify + + Skip verification of SAN field in client certificate for etcd connections. + + | + | Type: bool + | Default: false + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_server-name: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.server-name + + Name of the TLS server for etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_cipher-suites: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.cipher-suites + + TLS cipher suites for etcd connections. Possible values are the Golang `tls.TLS_* `__ constants. + + | + | Type: []uint16 + | Default: [] + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_allowed-cn: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.allowed-cn + + An allowed common name for authentication in etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_allowed-hostname: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.allowed-hostname + + An allowed TLS certificate name for authentication in etcd connections. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_etcd_tls_empty-cn: + +.. confval:: initial-settings.clusters..storage-connection.etcd-connection.tls.empty-cn + + Whether the empty common name is allowed in etcd connections. + + | + | Type: bool + | Default: false + + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_username: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.username + + A username for connecting to the cluster's Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_password: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.password + + A password for connecting to the cluster's Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_endpoints: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.endpoints + + An array of the cluster's Tarantool-based configuration storage URIs. + + | + | Type: []string + | Default: [] + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_method: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.method + + An authentication method for the cluster's Tarantool-based configuration storage. + + Possible values are the Go's `go-tarantool/Auth `__ constants: + + - ``AutoAuth`` (0) + - ``ChapSha1Auth`` + - ``PapSha256Auth`` + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_prefix: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.prefix + + A prefix for the cluster configuration parameters in the Tarantool-based configuration storage. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_key-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.key-file + + A path to a TLS private key file to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_cert-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.cert-file + + A path to an SSL certificate to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_ca-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.ca-file + + A path to a trusted CA certificate to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_ciphers: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.ciphers + + A list of SSL cipher suites that can be used for connecting to the cluster's Tarantool-based + configuration storage. Possible values are listed in :ref:`.params.ssl_ciphers `. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_enabled: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.enabled + + A password for an encrypted private SSL key to use for connecting to the cluster's Tarantool-based + configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_storage_tarantool_ssl_password-file: + +.. confval:: initial-settings.clusters..storage-connection.tarantool-connection.ssl.password-file + + A text file with passwords for encrypted private SSL keys to use + for connecting to the cluster's Tarantool-based configuration storage. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + + +.. _tcm_configuration_reference_initial_cluster_tarantool_username: + +.. confval:: initial-settings.clusters..tarantool-connection.username + + A username for connecting to the cluster instances. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_password: + +.. confval:: initial-settings.clusters..tarantool-connection.password + + A password for connecting to the cluster instances. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_method: + +.. confval:: initial-settings.clusters..tarantool-connection.method + + An authentication method for connecting to the cluster. + + Possible values are the Go's `go-tarantool/Auth `__ constants: + + - ``AutoAuth`` (0) + - ``ChapSha1Auth`` + - ``PapSha256Auth`` + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_timeout: + +.. confval:: initial-settings.clusters..tarantool-connection.timeout + + The cluster request timeout. + + | + | Type: time.Duration + | Default: 0 (not set) + +.. _tcm_configuration_reference_initial_cluster_tarantool_rate-limit: + +.. confval:: initial-settings.clusters..tarantool-connection.rate-limit + + The cluster rate limit. + + | + | Type: uint + | Default: 0 (not set) + + +.. _tcm_configuration_reference_initial_cluster__tarantool_ssl_key-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.key-file + + A path to a TLS private key file to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_cert-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.cert-file + + A path to an SSL certificate to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_ca-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.ca-file + + A path to a trusted CA certificate to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_ciphers: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.ciphers + + A list of SSL cipher suites that can be used for connecting to the cluster instances. + Possible values are listed in :ref:`.params.ssl_ciphers `. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_enabled: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.enabled + + A password for an encrypted private SSL key to use for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" + +.. _tcm_configuration_reference_initial_cluster_tarantool_ssl_password-file: + +.. confval:: initial-settings.clusters..tarantool-connection.ssl.password-file + + A text file with passwords for encrypted private SSL keys to use + for connecting to the cluster instances. + + See also: :ref:`configuration_connections_ssl`. + + | + | Type: string + | Default: "" diff --git a/doc/tooling/tcm/tcm_connect_clusters.rst b/doc/tooling/tcm/tcm_connect_clusters.rst index fa54d69d0..8e8c031cf 100644 --- a/doc/tooling/tcm/tcm_connect_clusters.rst +++ b/doc/tooling/tcm/tcm_connect_clusters.rst @@ -10,20 +10,27 @@ Connecting clusters |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. +* use :ref:`centralized configuration ` storage: etcd or Tarantool-based. 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|: +There are two scenarios of cluster connection to |tcm|: - Connect an existing cluster. -- Add a new cluster and :ref:`write its configuration ` from scratch in the |tcm| web UI. +- Add a new cluster and :ref:`write its configuration ` from scratch in the |tcm| + web interface. In both cases, you need to deploy Tarantool and start the cluster instances using the :ref:`tt-cli` or another suitable way. +To add a cluster to |tcm|, you can use two ways: + +- Use the |tcm| web interface as described on this page. +- Specify the ``initial-settings.clusters`` section of the |tcm| configuration. + To learn more, see :ref:`tcm_configuration_initial`. + .. _tcm_connect_clusters_parameters: Connection parameters