Skip to content

Commit 7f01c9d

Browse files
andreyaksenovandreyaksenov
authored
Document new 'config' API (#4331)
1 parent 01bc328 commit 7f01c9d

File tree

1 file changed

+202
-74
lines changed

1 file changed

+202
-74
lines changed

‎doc/reference/reference_lua/config.rst

Lines changed: 202 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Module config
88
The ``config`` module provides the ability to work with an instance's configuration.
99
For example, you can determine whether the current instance is up and running without errors after applying the :ref:`cluster's configuration <configuration_overview>`.
1010

11-
By using the ``config.storage`` :ref:`role <configuration_reference_roles_options>`, you can set up a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>` and interact with this storage using the ``config`` module API.
11+
By using the ``config.storage`` :ref:`role <configuration_application_roles>`, you can set up a Tarantool-based :ref:`centralized configuration storage <configuration_etcd>` and interact with this storage using the ``config`` module API.
1212

1313

1414
.. _config_module_loading:
@@ -46,11 +46,17 @@ API Reference
4646
-
4747

4848
* - :ref:`config:get() <config_api_reference_get>`
49-
- Get a configuration applied to the current instance
49+
- Get a configuration applied to the current or remote instance
5050

5151
* - :ref:`config:info() <config_api_reference_info>`
5252
- Get the current instance's state in regard to configuration
5353

54+
* - :ref:`config:instance_uri() <config_api_reference_instance_uri>`
55+
- Get a URI of the current or remote instance
56+
57+
* - :ref:`config:instances() <config_api_reference_instances>`
58+
- List all instances of the cluster
59+
5460
* - :ref:`config:reload() <config_api_reference_reload>`
5561
- Reload the current instance's configuration
5662

@@ -83,19 +89,26 @@ config API
8389

8490
.. _config_api_reference_get:
8591

86-
.. method:: get([param])
92+
.. method:: get([param, opts])
8793

88-
Get a configuration applied to the current instance.
89-
Optionally, you can pass a configuration option name to get its value.
94+
Get a configuration applied to the current or remote instance.
95+
Note the following differences between getting a configuration for the current and remote instance:
96+
97+
- For the current instance, ``get()`` returns its configuration considering :ref:`environment variables <configuration_environment_variable>`.
98+
- For a remote instance, ``get()`` only considers a cluster configuration and ignores environment variables.
9099

91100
:param string param: a configuration option name
101+
:param table opts: options to pass. The following options are available:
102+
103+
- ``instance`` (since :doc:`3.1.0 </release/3.1.0>`) -- the name of a remote instance whose configuration should be obtained
104+
92105
:return: an instance configuration
93106

94107
**Examples:**
95108

96109
The example below shows how to get the full instance configuration:
97110

98-
.. code-block:: console
111+
.. code-block:: tarantoolsession
99112
100113
app:instance001> require('config'):get()
101114
---
@@ -104,12 +117,12 @@ config API
104117
too_long_threshold: 0.5
105118
top:
106119
enabled: false
107-
# other configuration values
120+
# Other configuration values
108121
# ...
109122
110123
This example shows how to get an ``iproto.listen`` option value:
111124

112-
.. code-block:: console
125+
.. code-block:: tarantoolsession
113126
114127
app:instance001> require('config'):get('iproto.listen')
115128
---
@@ -121,89 +134,204 @@ config API
121134

122135
.. _config_api_reference_info:
123136

124-
.. method:: info()
137+
.. method:: info([version])
125138

126139
Get the current instance's state in regard to configuration.
127140

128-
:return: a table containing an instance's state
141+
:param string version: (since :doc:`3.1.0 </release/3.1.0>`) the version of the information that should be returned. The ``version`` argument can be one of the following values:
129142

130-
The returned state includes the following sections:
143+
* ``v1`` (default): the ``meta`` field returned by ``info()`` includes information about the last loaded configuration
144+
* ``v2``: the ``meta`` field returned by ``info()`` includes two fields:
131145

132-
- ``status`` -- one of the following statuses:
146+
* the ``last`` field includes information about the last loaded configuration
147+
* the ``active`` field includes information for the last successfully applied configuration
133148

134-
* ``ready`` -- the configuration is applied successfully
135-
* ``check_warnings`` -- the configuration is applied with warnings
136-
* ``check_errors`` -- the configuration cannot be applied due to configuration errors
137149

138-
- ``meta`` -- additional configuration information
150+
:return: a table containing an instance's state. The returned state includes the following sections:
139151

140-
- ``alerts`` -- warnings or errors raised on an attempt to apply the configuration
152+
- ``status`` -- one of the following statuses:
141153

142-
**Examples:**
154+
* ``ready`` -- the configuration is applied successfully
155+
* ``check_warnings`` -- the configuration is applied with warnings
156+
* ``check_errors`` -- the configuration cannot be applied due to configuration errors
157+
158+
- ``meta`` -- additional configuration information
159+
160+
- ``alerts`` -- warnings or errors raised on an attempt to apply the configuration
161+
162+
Below are a few examples demonstrating how the ``info()`` output might look.
163+
164+
**Example: no configuration warnings or errors**
165+
166+
In the example below, an instance's state is ``ready`` and no warnings are shown:
167+
168+
.. code-block:: tarantoolsession
169+
170+
app:instance001> require('config'):info('v2')
171+
---
172+
- status: ready
173+
meta:
174+
last: &0 []
175+
active: *0
176+
alerts: []
177+
...
178+
179+
**Example: configuration warnings**
180+
181+
In the example below, the instance's state is ``check_warnings``.
182+
The ``alerts`` section informs that privileges to the ``bands`` space for ``sampleuser`` cannot be granted because the ``bands`` space has not been created yet:
183+
184+
.. code-block:: tarantoolsession
185+
186+
app:instance001> require('config'):info('v2')
187+
---
188+
- status: check_warnings
189+
meta:
190+
last: &0 []
191+
active: *0
192+
alerts:
193+
- type: warn
194+
message: box.schema.user.grant("sampleuser", "read,write", "space", "bands") has
195+
failed because either the object has not been created yet, a database schema
196+
upgrade has not been performed, or the privilege write has failed (separate
197+
alert reported)
198+
timestamp: 2024-07-03T18:09:18.826138+0300
199+
...
200+
201+
This warning is cleared when the ``bands`` space is created.
202+
203+
**Example: configuration errors**
204+
205+
In the example below, the instance's state is ``check_errors``.
206+
The ``alerts`` section informs that the ``log.level`` configuration option has an incorrect value:
207+
208+
.. code-block:: tarantoolsession
209+
210+
app:instance001> require('config'):info('v2')
211+
---
212+
- status: check_errors
213+
meta:
214+
last: []
215+
active: []
216+
alerts:
217+
- type: error
218+
message: '[cluster_config] log.level: Got 8, but only the following values are
219+
allowed: 0, fatal, 1, syserror, 2, error, 3, crit, 4, warn, 5, info, 6, verbose,
220+
7, debug'
221+
timestamp: 2024-07-03T18:13:19.755454+0300
222+
...
223+
224+
**Example: configuration errors (centralized configuration storage)**
225+
226+
In this example, the ``meta`` field includes information about a :ref:`centralized storage <configuration_etcd>` the instance takes a configuration from:
227+
228+
.. code-block:: tarantoolsession
229+
230+
app:instance001> require('config'):info('v2')
231+
---
232+
- status: check_errors
233+
meta:
234+
last:
235+
etcd:
236+
mod_revision:
237+
/myapp/config/all: 5
238+
revision: 5
239+
active:
240+
etcd:
241+
mod_revision:
242+
/myapp/config/all: 2
243+
revision: 4
244+
alerts:
245+
- type: error
246+
message: 'etcd source: invalid config at key "/myapp/config/all": [cluster_config]
247+
groups.group001.replicasets.replicaset001.instances.instance001.log.level: Got
248+
8, but only the following values are allowed: 0, fatal, 1, syserror, 2, error,
249+
3, crit, 4, warn, 5, info, 6, verbose, 7, debug'
250+
timestamp: 2024-07-03T15:22:06.438275Z
251+
...
252+
253+
254+
.. _config_api_reference_instance_uri:
255+
256+
.. method:: instance_uri([uri_type, opts])
257+
258+
**Since:** :doc:`3.1.0 </release/3.1.0>`
259+
260+
Get a URI of the current or remote instance.
261+
262+
:param string uri_type: a URI type. The following URI types are supported:
263+
264+
* ``peer`` -- a URI used to advertise the instance to other cluster members. See also: :ref:`iproto.advertise.peer <configuration_reference_iproto_advertise_peer>`.
265+
* ``sharding`` -- a URI used to advertise the current instance to a router and rebalancer. See also: :ref:`iproto.advertise.sharding <configuration_reference_iproto_advertise_sharding>`.
266+
267+
:param table opts: options to pass. The following options are available:
268+
269+
- ``instance`` -- the name of a remote instance whose URI should be obtained
270+
271+
:return: a table representing an instance URI. This table might include the following fields:
272+
273+
* ``uri`` -- an instance URI
274+
* ``login`` -- a username used to connect to this instance
275+
* ``password`` -- a user's password
276+
* ``params`` -- URI parameters used to connect to this instance
277+
278+
.. NOTE::
279+
280+
Note that the resulting URI object can be passed to the :ref:`connect() <net_box-connect>` function of the ``net.box`` module.
281+
282+
**Example**
283+
284+
The example below shows how to get a URI used to advertise ``storage-b-003`` to other cluster members:
285+
286+
.. code-block:: lua
287+
288+
local config = require('config')
289+
config:instance_uri('peer', { instance = 'storage-b-003' })
290+
291+
292+
.. _config_api_reference_instances:
143293

144-
Below are a few examples demonstrating how the ``info()`` output might look:
294+
.. method:: instances()
145295

146-
* In the example below, an instance's state is ``ready`` and no warnings are shown:
296+
**Since:** :doc:`3.1.0 </release/3.1.0>`
147297

148-
.. code-block:: console
298+
List all instances of the cluster.
149299

150-
app:instance001> require('config'):info()
151-
---
152-
- status: ready
153-
meta: []
154-
alerts: []
155-
...
300+
:return: a table containing information about instances. The returned table uses instance names as the keys and contains the following information for each instance:
156301

157-
* In the example below, the instance's state is ``check_warnings``.
158-
The ``alerts`` section informs that privileges to the ``books`` space for ``sampleuser`` cannot be granted because the ``books`` space has not created yet:
302+
- ``instance_name`` -- an instance name
303+
- ``replicaset_name`` -- the name of a replica set the instance belongs to
304+
- ``group_name`` -- the name of a group the instance belongs to
159305

160-
.. code-block:: console
306+
**Example**
161307

162-
app:instance001> require('config'):info()
163-
---
164-
- status: check_warnings
165-
meta: []
166-
alerts:
167-
- type: warn
168-
message: box.schema.user.grant("sampleuser", "read,write", "space", "books") has
169-
failed because either the object has not been created yet, or the privilege
170-
write has failed (separate alert reported)
171-
timestamp: 2024-02-27T15:07:41.815785+0300
172-
...
308+
The example below shows how to use ``instances()`` to get the names of all instances in the cluster, create a connection to each instance using the :ref:`connpool <connpool_module>` module, and log connection URIs using the :ref:`log <log-module>` module:
173309

174-
This warning is cleared when the ``books`` space is created.
310+
.. code-block:: lua
175311
176-
* In the example below, the instance's state is ``check_errors``.
177-
The ``alerts`` section informs that the ``log.level`` configuration option has an incorrect value:
312+
local config = require('config')
313+
local connpool = require('experimental.connpool')
314+
local log = require('log')
178315
179-
.. code-block:: console
316+
for instance_name in pairs(config:instances()) do
317+
local conn = connpool.connect(instance_name)
318+
log.info("Connection URI for %q: %s:%s", instance_name, conn.host, conn.port)
319+
end
180320
181-
app:instance001> require('config'):info()
182-
---
183-
- status: check_errors
184-
meta: []
185-
alerts:
186-
- type: error
187-
message: '[cluster_config] log.level: Got 8, but only the following values are
188-
allowed: 0, fatal, 1, syserror, 2, error, 3, crit, 4, warn, 5, info, 6, verbose,
189-
7, debug'
190-
timestamp: 2024-02-29T12:55:54.366810+0300
191-
...
321+
In this example, the same actions are performed for instances from the specified replica set:
192322

193-
* In this example, an instance's state includes information about a :ref:`centralized storage <configuration_etcd>` the instance takes a configuration from:
323+
.. code-block:: lua
194324
195-
.. code-block:: console
325+
local config = require('config')
326+
local connpool = require('experimental.connpool')
327+
local log = require('log')
196328
197-
app:instance001> require('config'):info()
198-
---
199-
- status: ready
200-
meta:
201-
storage:
202-
revision: 8
203-
mod_revision:
204-
/myapp/config/all: 8
205-
alerts: []
206-
...
329+
for instance_name, def in pairs(config:instances()) do
330+
if def.replicaset_name == 'storage-b' then
331+
local conn = connpool.connect(instance_name)
332+
log.info("Connection URI for %q: %s:%s", instance_name, conn.host, conn.port)
333+
end
334+
end
207335
208336
209337
.. _config_api_reference_reload:
@@ -252,7 +380,7 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
252380
:end-at: cluster_config_handle:close()
253381
:dedent:
254382

255-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_.
383+
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
256384

257385

258386
.. _config_storage_api_reference_get:
@@ -268,7 +396,7 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
268396
* ``data``: a table containing the information about the value:
269397

270398
* ``path``: a path
271-
* ``mod_revision``: a last revision at which this value was modified
399+
* ``mod_revision``: the last revision at which this value was modified
272400
* ``value:``: a value
273401

274402
* ``revision``: a revision after performing the operation
@@ -293,7 +421,7 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
293421
:end-at: get('/myapp/')
294422
:dedent:
295423

296-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_.
424+
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
297425

298426
.. _config_storage_api_reference_delete:
299427

@@ -308,7 +436,7 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
308436
* ``data``: a table containing the information about the value:
309437

310438
* ``path``: a path
311-
* ``mod_revision``: a last revision at which this value was modified
439+
* ``mod_revision``: the last revision at which this value was modified
312440
* ``value:``: a value
313441

314442
* ``revision``: a revision after performing the operation
@@ -333,7 +461,7 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
333461
:end-at: delete('/')
334462
:dedent:
335463

336-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_.
464+
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_
337465

338466

339467
.. _config_storage_api_reference_info:
@@ -394,4 +522,4 @@ The ``config.storage`` API allows you to interact with a Tarantool-based :ref:`c
394522
:end-at: })
395523
:dedent:
396524

397-
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_.
525+
Example on GitHub: `tarantool_config_storage <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/centralized_config/instances.enabled/tarantool_config_storage>`_

0 commit comments

Comments
 (0)