diff --git a/doc/code_snippets/test/config/etcd.yaml b/doc/code_snippets/test/config/etcd.yaml index f956fea2bf..e38344ebd9 100644 --- a/doc/code_snippets/test/config/etcd.yaml +++ b/doc/code_snippets/test/config/etcd.yaml @@ -1,5 +1,5 @@ config: etcd: - prefix: /example endpoints: - - http://localhost:2379 \ No newline at end of file + - http://localhost:2379 + prefix: /example \ No newline at end of file diff --git a/doc/code_snippets/test/config/etcd_full.yaml b/doc/code_snippets/test/config/etcd_full.yaml new file mode 100644 index 0000000000..479314e097 --- /dev/null +++ b/doc/code_snippets/test/config/etcd_full.yaml @@ -0,0 +1,12 @@ +config: + etcd: + endpoints: + - http://localhost:2379 + prefix: /example + username: testuser + password: foobar + ssl: + ca_file: ca.crt + http: + request: + timeout: 3 \ No newline at end of file diff --git a/doc/concepts/configuration/configuration_etcd.rst b/doc/concepts/configuration/configuration_etcd.rst index 1b44c540b0..60a9e966af 100644 --- a/doc/concepts/configuration/configuration_etcd.rst +++ b/doc/concepts/configuration/configuration_etcd.rst @@ -6,92 +6,157 @@ Storing configuration in etcd .. admonition:: Enterprise Edition :class: fact - Centralized configuration is supported by the `Enterprise Edition `_ only. + Storing configuration in etcd is supported by the `Enterprise Edition `_ only. -.. TODO - https://github.com/tarantool/doc/issues/3658 +Tarantool enables you to store configuration data in one place using etcd. +To achieve this, you need to define how to access etcd and put a :ref:`YAML configuration ` to a etcd server. - - Install and configure etcd (authentication, TLS) - - Local etcd configuration (mention env vars) - - endpoints - - key prefix - - auth - - TLS - - http (timeout, socket) - - Put a remote config - - etcdctl put - - tt cluster publish - - Show cluster config - - etcdctl get - - tt cluster show - - Start app - - Local config - - Env vars - - Reload config - - auto - - manual (config.reload) +.. _etcd_local_configuration: - Local config (``config.yaml``): +Local etcd configuration +------------------------ - .. literalinclude:: /code_snippets/test/config/etcd.yaml - :language: yaml - :dedent: +To store a cluster's configuration in etcd, you need to provide etcd connection settings in a local configuration file. +These settings are used to :ref:`publish ` a cluster's configuration and :ref:`show ` it. - Remote config (``remote_config.yaml``): +Connection options for etcd should be specified in the ``config.etcd`` section of the configuration file. +At least, the following options should be specified: - .. literalinclude:: /code_snippets/test/config/replicaset_manual.yaml - :language: yaml - :dedent: +.. literalinclude:: /code_snippets/test/config/etcd.yaml + :language: yaml + :dedent: - Put a remote config: +- :ref:`config.etcd.endpoints ` specifies the list of etcd endpoints. +- :ref:`config.etcd.prefix ` sets a key prefix used to search a configuration. Tarantool searches keys by the following path: ``/prefix/config/*``. - .. code-block:: console - $ etcdctl put /example/config/all.yaml < remote_config.yaml +You can also provide additional etcd connection options: - Put a remote config using ``tt cluster``: +.. literalinclude:: /code_snippets/test/config/etcd_full.yaml + :language: yaml + :dedent: - .. code-block:: console +In this example, the following options are configured in addition to a etcd endpoint and key prefix: - $ tt cluster publish "http://localhost:2379/tt" remote_config.yaml +- :ref:`config.etcd.username ` and :ref:`config.etcd.password ` specify credentials used for authentication. +- :ref:`config.etcd.ssl.ca_file ` specifies a path to a trusted certificate authorities (CA) file. +- :ref:`config.etcd.http.request.timeout ` configures a timeout for connecting to a etcd server. - Searches keys by the following path: ``/prefix/config/*``. - See https://github.com/tarantool/doc/issues/3725 +You can find all the available configuration options in the :ref:`etcd ` section. - Manual: - .. code-block:: yaml - config: - reload: 'manual' +.. _etcd_publishing_configuration: - Reload config (on all instances): +Publishing cluster's configuration to etcd +------------------------------------------ - .. code-block:: lua +.. _etcd_publishing_configuration_tt: - require('config'):reload() +Publishing configuration using the tt utility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Authentication: +The tt utility provides the :ref:`tt cluster ` command for managing a cluster's configuration. +The ``tt cluster publish`` command can be used to publish a cluster's configuration to etcd. - .. code-block:: console +The example below shows how a :ref:`layout ` of the application called ``app`` might look: - $ etcdctl --user root --password foobar role grant-permission tt readwrite /tt/config/all - $ etcdctl --user root --password foobar role grant-permission tt --prefix=true readwrite /tt/ +.. code-block:: none - $ etcdctl --user root --password foobar user grant-role testuser tt + instances.enabled + └── app + ├── config.yaml + ├── cluster.yaml + └── instances.yml +* ``config.yaml`` contains a :ref:`local configuration ` used to connect to etcd. +* ``cluster.yaml`` contains a cluster's configuration to be published. +* ``instances.yml`` specifies :ref:`instances ` to run in the current environment. ``tt cluster publish`` ignores the configured instances. - .. code-block:: yaml +To publish a cluster's configuration (``cluster.yaml``) to a etcd server, execute ``tt cluster publish`` as follows: - config: - etcd: - http: - request: - timeout: 3 - prefix: /tt - endpoints: - - http://localhost:2379 - username: testuser - password: foobar +.. code-block:: console + $ tt cluster publish "http://localhost:2379/example" instances.enabled/app/cluster.yaml + + +.. _etcd_publishing_configuration_etcdctl: + +Publishing configuration using etcdctl +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To publish a cluster's configuration using the ``etcdctl`` utility, use the ``put`` command: + +.. code-block:: console + + $ etcdctl put /example/config/all < cluster.yaml + + + + +.. _etcd_showing_configuration: + +Showing a cluster's configuration +--------------------------------- + +As for :ref:`publishing configuration `, you can see a cluster's configuration in two ways: + +- Using the :ref:`tt cluster show ` command. +- Using the ``etcdctl get`` command. + + +.. _etcd_starting_instances: + +Starting Tarantool instances +---------------------------- + +To learn how to start Tarantool instances, see the :ref:`Starting Tarantool instances ` section. + + +.. _etcd_reloading_configuration: + +Reloading configuration +----------------------- + +By default, Tarantool watches etcd keys with the :ref:`specified prefix ` for changes in a cluster's configuration and reloads a changed configuration automatically. +If necessary, you can set the :ref:`config.reload ` option to ``manual`` to turn off configuration reloading: + +.. code-block:: yaml + + config: + reload: 'manual' + etcd: + # ... + +In this case, you can reload a configuration in :ref:`application code ` using the ``reload()`` function provided by the :ref:`config ` module: + +.. code-block:: lua + + require('config'):reload() + + + + + + + + + +.. + Generating certificates for testing: + 1) openssl genrsa -out ca.key 2048 + 2) openssl req -new -x509 -days 365 -key ca.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=Acme Root CA" -out ca.cr + 3) openssl req -newkey rsa:2048 -nodes -keyout server.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=localhost" -out server.csr + 4) openssl x509 -req -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1") -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt + 5) sudo cp server.crt /etc/ssl/certs + 6) sudo cp server.key /etc/ssl/private + + Starting etcd: + etcd --cert-file=ssl/server.crt --key-file=ssl/server.key --advertise-client-urls=https://localhost:2379 --listen-client-urls=https://localhost:2379 + + Get keys: + etcdctl get /tt/config/all --cert=ssl/server.crt --key=ssl/server.key + + Test using curl: + curl --cacert ssl/ca.crt https://localhost:2379/v2/keys/foo -XPUT -d value=bar -v \ No newline at end of file diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst index 44f6d16903..c328a10e84 100644 --- a/doc/reference/configuration/configuration_reference.rst +++ b/doc/reference/configuration/configuration_reference.rst @@ -5,6 +5,222 @@ Configuration reference This topic describes all :ref:`configuration parameters ` provided by Tarantool. +.. _configuration_reference_config: + +config +------ + +* :ref:`config.reload ` +* :ref:`config.version ` +* :ref:`config.etcd.* ` + +.. _configuration_reference_config_reload: + +.. confval:: config.reload + + **Since:** :doc:`3.0.0 `. + + Specify how configuration is reloaded. + This option accepts the following values: + + - ``auto``: configuration is reloaded automatically when it is changed. + - ``manual``: configuration should be reloaded manually. In this case, you can reload configuration in application code using :ref:`config.reload() `. + + See also: :ref:`Reloading configuration `. + + | Type: string + | Possible values: 'auto', 'manual' + | Default: 'auto' + | Environment variable: TT_CONFIG_RELOAD + + +.. _configuration_reference_config_version: + +.. confval:: config.version + + **Since:** :doc:`3.0.0 `. + + A configuration version. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_VERSION + + + +.. _configuration_reference_config_etcd: + +etcd +~~~~ + +.. admonition:: Enterprise Edition + :class: fact + + Storing configuration in etcd is supported by the `Enterprise Edition `_ only. + +This section describes options related to :ref:`storing configuration in etcd `. + +* :ref:`config.etcd.endpoints ` +* :ref:`config.etcd.prefix ` +* :ref:`config.etcd.username ` +* :ref:`config.etcd.password ` +* :ref:`config.etcd.ssl.ca_file ` +* :ref:`config.etcd.ssl.ca_path ` +* :ref:`config.etcd.ssl.ssl_key ` +* :ref:`config.etcd.ssl.verify_host ` +* :ref:`config.etcd.ssl.verify_peer ` +* :ref:`config.etcd.http.request.timeout ` +* :ref:`config.etcd.http.request.unix_socket ` + + + +.. _config_etcd_endpoints: + +.. confval:: config.etcd.endpoints + + **Since:** :doc:`3.0.0 `. + + The list of endpoints used to access a etcd server. + + See also: :ref:`Local etcd configuration `. + + | Type: array + | Default: nil + | Environment variable: TT_CONFIG_ETCD_ENDPOINTS + + +.. _config_etcd_prefix: + +.. confval:: config.etcd.prefix + + **Since:** :doc:`3.0.0 `. + + A key prefix used to search a configuration on a etcd server. + Tarantool searches keys by the following path: ``/prefix/config/*``. + + See also: :ref:`Local etcd configuration `. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_PREFIX + +.. _config_etcd_username: + +.. confval:: config.etcd.username + + **Since:** :doc:`3.0.0 `. + + A username used for authentication. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_USERNAME + +.. _config_etcd_password: + +.. confval:: config.etcd.password + + **Since:** :doc:`3.0.0 `. + + A password used for authentication. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_PASSWORD + + +.. _config_etcd_ssl_ca_file: + +.. confval:: config.etcd.ssl.ca_file + + **Since:** :doc:`3.0.0 `. + + A path to a trusted certificate authorities (CA) file. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_CA_FILE + + +.. _config_etcd_ssl_ca_path: + +.. confval:: config.etcd.ssl.ca_path + + **Since:** :doc:`3.0.0 `. + + A path to a directory holding certificates to verify the peer with. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_CA_PATH + + +.. _config_etcd_ssl_ssl_key: + +.. confval:: config.etcd.ssl.ssl_key + + **Since:** :doc:`3.0.0 `. + + A path to a private SSL key file. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_SSL_KEY + + +.. _config_etcd_ssl_verify_host: + +.. confval:: config.etcd.ssl.verify_host + + **Since:** :doc:`3.0.0 `. + + Enable verification of the certificate's name (CN) against the specified host. + + | Type: boolean + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_HOST + + +.. _config_etcd_ssl_verify_peer: + +.. confval:: config.etcd.ssl.verify_peer + + **Since:** :doc:`3.0.0 `. + + Enable verification of the peer's SSL certificate. + + | Type: boolean + | Default: nil + | Environment variable: TT_CONFIG_ETCD_SSL_VERIFY_PEER + + +.. _config_etcd_http_request_timeout: + +.. confval:: config.etcd.http.request.timeout + + **Since:** :doc:`3.0.0 `. + + A timeout for connecting to a etcd server. + + | Type: number + | Default: nil + | Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_TIMEOUT + +.. _config_etcd_http_request_unix_socket: + +.. confval:: config.etcd.http.request.unix_socket + + **Since:** :doc:`3.0.0 `. + + A Unix domain socket used to connect to a etcd server. + + | Type: string + | Default: nil + | Environment variable: TT_CONFIG_ETCD_HTTP_REQUEST_UNIX_SOCKET + + + + .. TODO https://github.com/tarantool/doc/issues/3664 diff --git a/doc/reference/reference_lua/config.rst b/doc/reference/reference_lua/config.rst new file mode 100644 index 0000000000..9ddacc11df --- /dev/null +++ b/doc/reference/reference_lua/config.rst @@ -0,0 +1,8 @@ +.. _config-module: + +Module config +============= + +**Since:** :doc:`3.0.0 ` + +.. TODO: https://github.com/tarantool/doc/issues/3662 diff --git a/doc/reference/reference_lua/index.rst b/doc/reference/reference_lua/index.rst index f09443274d..2002f75e4f 100644 --- a/doc/reference/reference_lua/index.rst +++ b/doc/reference/reference_lua/index.rst @@ -25,6 +25,7 @@ This reference covers Tarantool's built-in Lua modules. checks clock compat + config console crypto csv diff --git a/doc/reference/tooling/tt_cli/cluster.rst b/doc/reference/tooling/tt_cli/cluster.rst new file mode 100644 index 0000000000..0236893038 --- /dev/null +++ b/doc/reference/tooling/tt_cli/cluster.rst @@ -0,0 +1,10 @@ +.. _tt-cluster: + +Managing a cluster's configuration +================================== + +.. code-block:: console + + $ tt cluster + +.. TODO: https://github.com/tarantool/doc/issues/3725 diff --git a/doc/reference/tooling/tt_cli/commands.rst b/doc/reference/tooling/tt_cli/commands.rst index 5c68092f1b..61fc3506c0 100644 --- a/doc/reference/tooling/tt_cli/commands.rst +++ b/doc/reference/tooling/tt_cli/commands.rst @@ -26,6 +26,8 @@ help for the given command. - Check an application file for syntax errors * - :doc:`clean ` - Clean instance files + * - :doc:`cluster ` + - Manage a cluster's configuration * - :doc:`completion ` - Generate completion for a specified shell * - :doc:`connect ` @@ -83,6 +85,7 @@ help for the given command. cfg check clean + cluster completion connect coredump