Skip to content

Commit 3a884af

Browse files
p7novp7nov
committed
Fix
1 parent 4941d09 commit 3a884af

File tree

2 files changed

+180
-66
lines changed

2 files changed

+180
-66
lines changed

‎doc/reference/tooling/tcm/tcm_configuration.rst

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
.. _tcm_configuration:
2+
3+
Configuration
4+
=============
5+
6+
.. TODO: write specific configuration tutorials for http, security, logging, and so on.
7+
8+
This topic describes the |tcm_full_name| configuration model. For the complete
9+
list of |tcm| configuration parameters, see the :ref:`|tcm| configuration reference <tcm_configuration_reference>`.
10+
11+
Parameter groups and names
12+
--------------------------
13+
14+
|tcm_full_name| configuration parameters are grouped by the functions that they
15+
affect. There are the following groups:
16+
17+
* HTTP
18+
* logging
19+
* configuration storage
20+
* security
21+
* add-ons
22+
* limits
23+
* |tcm| running mode
24+
25+
for better structure, some groups have nested groups. For example, there are ``tls``
26+
and ``websession-cookie`` groups within ``http`` that define TLS encryption and
27+
cookie settings.
28+
29+
Parameter names are the full paths from the top-level group to the specific parameter.
30+
For example:
31+
32+
* ``http.host`` is the ``host`` parameter that is defined directly in the ``http`` group.
33+
* ``http.tls.enabled`` is the ``enabled`` parameter that is defined in the ``tls``
34+
nested group within ``http``.
35+
36+
The following fragment
37+
38+
.. _tcm_configuration_ways:
39+
40+
Ways to pass |tcm| configuration parameters
41+
-------------------------------------------
42+
43+
There are three ways to pass |tcm| configuration parameters: a YAML file,
44+
environment variables, and the command-line options of the |tcm| executable.
45+
46+
.. _tcm_configuration_ways_yaml:
47+
48+
YAML configuration file
49+
~~~~~~~~~~~~~~~~~~~~~~~
50+
51+
|tcm| configuration can be stored in a YAML file. Its content must reflect the
52+
configuration parameters hierarchy.
53+
54+
The example below shows a shows a fragment of a |tcm| configuration file:
55+
56+
.. code-block::yaml
57+
58+
cluster:
59+
on-air-limit: 4096
60+
connection-rate-limit: 512
61+
tarantool-timeout: 10s
62+
tarantool-ping-timeout: 5s
63+
http:
64+
basic-auth:
65+
enabled: false
66+
network: tcp
67+
host: 127.0.0.1
68+
port: 8080
69+
request-size: 1572864
70+
websocket:
71+
read-buffer-size: 16384
72+
write-buffer-size: 16384
73+
keepalive-ping-interval: 20s
74+
handshake-timeout: 10s
75+
init-timeout: 15s
76+
77+
.. code-block::yaml
78+
79+
The location of a YAML configuration file must be passed during the |tcm| startup in the ``-c``
80+
command-line option:
81+
82+
.. code-block::console
83+
84+
./tcm -c=config.yml
85+
86+
.. _tcm_configuration_ways_env:
87+
88+
Environment variables
89+
~~~~~~~~~~~~~~~~~~~~~
90+
91+
|tcm| can take values of its configuration parameters from environment variables.
92+
The variable names start with ``TCM_``. Then goes the full path to the parameter,
93+
converted to upper case. All delimiters are replaced with underscores (``_``).
94+
For example, ``TCM_HTTP_HOST`` is a variable for the ``http.host`` parameter,
95+
and ``TCM_HTTP_WEBSESSION_COOKIE_NAME`` is for ``http.websession-cookie.name``.
96+
97+
The example below shows how to start |tcm| passing configuration parameters in
98+
environment variables:
99+
100+
.. code-block::console
101+
102+
export TCM_HTTP_HOST="0.0.0.0"
103+
export TCM_HTTP_POST="8888"
104+
./tcm
105+
106+
.. _tcm_configuration_ways_cli:
107+
108+
Command-line arguments
109+
~~~~~~~~~~~~~~~~~~~~~~
110+
111+
|tcm| executable has ``--`` command-line options for each configuration parameter.
112+
Their names reflect the full path to the parameter, with all delimiters replaced by
113+
hyphens (``-``). For example, ``--http-host`` is an option for ``http.host``,
114+
and ``--http-websession-cookie-name`` is for ``http.websession-cookie.name``.
115+
116+
The example below shows how to start |tcm| passing configuration parameters in
117+
command-line options:
118+
119+
.. code-block::console
120+
121+
./tcm --storage.etcd.embed.enabled --addon.enabled --http.host=0.0.0.0 --http.port=8888
122+
123+
124+
.. _tcm_configuration_precedence:
125+
126+
Configuration precedence
127+
~~~~~~~~~~~~~~~~~~~~~~~~
128+
129+
|tcm| configuration options are applied from multiple sources with the following precedence,
130+
from highest to lowest:
131+
132+
- ``tcm`` executable arguments.
133+
- `TCM_*` environment variables.
134+
- Configuration from a YAML file.
135+
136+
If the same option is defined in two or more locations, the option with the highest precedence is applied.
137+
138+
You can combine different ways of |tcm| configuration for efficient management of
139+
multiple |tcm| installations:
140+
141+
- A single YAML file for all installations can contain the common configuration parts.
142+
For example, the security parameters that fulfill your organization's requirements.
143+
- Environment variables that set specific parameters for each server, such as
144+
?? any good example??
145+
- Command-line options for parameters that must be unique for different |tcm| instances
146+
running on a single server. For example, ``http.port``.
147+
148+
Configuration parameter types
149+
-----------------------------
150+
151+
|tcm| configuration parameters have the `Go <https://go.dev/>`__ language
152+
types. Note that this is different from the :ref`Tarantool configuration parameters <configuration_reference>`,
153+
which have Lua types.
154+
155+
Most options have the Go's basic types: `bool`, `string`, `int`, and other integer
156+
numeric types.
157+
158+
Parameters that can take multiple values are arrays. In YAML, they are passed as
159+
YAML arrays (each item on a new line, starting with a dash). In environment variables
160+
and command line options, the items of such arrays are passed in a semicolon-separated string.
161+
162+
Parameters that set timeouts, TTLs, and other duration values, have the Go's `time.Duration <https://pkg.go.dev/time#Duration>`__
163+
type. This enables passing the values in the time-formatted strings such as ``4h30m25s``.
164+
165+
166+
? Configuration example or template for readers?
167+
------------------------------------------------

‎doc/reference/tooling/tcm/tcm_config.rst renamed to ‎doc/reference/tooling/tcm/tcm_configuration_reference.rst

Lines changed: 13 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,11 @@
1-
.. _tcm_configuration:
2-
3-
Configuration
4-
=============
5-
6-
|tcm_full_name| configuration options define various aspects of its
7-
8-
* HTTP parameters
9-
* logging
10-
* configuration storage
11-
* security
12-
* add-ons
13-
* limits
14-
* |tcm| running mode
15-
16-
Ways to pass |tcm| configuration options
17-
----------------------------------------
18-
19-
There are three ways to pass |tcm| configuration parameters:
20-
21-
- YAML configuration file. The file location is passed during the |tcm| startup
22-
in the ``-c`` command-line option
23-
24-
.. code-block::console
25-
26-
./tcm -c
27-
28-
- Environment variables
29-
30-
- |tcm| command-line arguments
31-
32-
.. _tcm_configuration_precedence:
33-
34-
Configuration precedence
35-
~~~~~~~~~~~~~~~~~~~~~~~~
36-
37-
|tcm| configuration options are applied from multiple sources with the following precedence, from highest to lowest:
38-
39-
- ``tcm`` executable arguments.
40-
- `TCM_*` environment variables.
41-
- Configuration from a YAML file.
42-
43-
If the same option is defined in two or more locations, the option with the highest precedence is applied.
44-
45-
46-
You can combine different ways of |tcm| configuration for efficient management of
47-
multiple |tcm| instances. For example: there can be a single YAML file with common
48-
configuration parts, environment variables that are ser
49-
50-
Configuration option types
51-
--------------------------
52-
53-
|tcm| configuration options use the `Go <https://go.dev/>`__ programming language
54-
types. Most options have the primitive types, such as numbers or strings.
55-
56-
Use notation th
1+
.. _tcm_configuration_reference:
572

583
Configuration reference
59-
-----------------------
4+
=======================
5+
6+
This topic describes :ref:`configuration parameters <tcm_configuration>` of |tcm_full_name|.
607

61-
There are the following groups of |tcm| configuration options:
8+
There are the following groups of |tcm| configuration parameters:
629

6310
- :ref:`cluster <tcm_configuration_reference_cluster>`
6411
- :ref:`http <tcm_configuration_reference_http>`
@@ -72,7 +19,7 @@ There are the following groups of |tcm| configuration options:
7219
.. _tcm_configuration_reference_cluster:
7320

7421
cluster
75-
~~~~~~~
22+
-------
7623

7724
The ``cluster`` section defines parameters of connection between |tcm|
7825
and Tarantool clusters.
@@ -134,7 +81,7 @@ and Tarantool clusters.
13481
.. _tcm_configuration_reference_http:
13582

13683
http
137-
~~~~
84+
----
13885

13986
The ``http`` section defines parameters of HTTP connections between |tcm| and clients.
14087

@@ -820,7 +767,7 @@ The ``http`` section defines parameters of HTTP connections between |tcm| and cl
820767
.. _tcm_configuration_reference_log:
821768

822769
log
823-
~~~
770+
---
824771

825772
The ``log`` section defines the |tcm| logging parameters.
826773

@@ -1090,7 +1037,7 @@ The ``log`` section defines the |tcm| logging parameters.
10901037
.. _tcm_configuration_reference_storage:
10911038

10921039
storage
1093-
~~~~~~~
1040+
-------
10941041

10951042
The ``storage`` section defines the parameters of the configuration storage that
10961043
|tcm| uses for connected clusters.
@@ -1115,7 +1062,7 @@ The ``storage`` section defines the parameters of the configuration storage that
11151062
.. _tcm_configuration_reference_addon:
11161063

11171064
addon
1118-
~~~~~
1065+
-----
11191066

11201067
The ``addon`` section defines the |tcm|
11211068

@@ -1177,7 +1124,7 @@ The ``addon`` section defines the |tcm|
11771124
.. _tcm_configuration_reference_limits:
11781125

11791126
limits
1180-
~~~~~~
1127+
------
11811128

11821129
The ``limits`` section defines limits on various |tcm| objects and relations
11831130
between them.
@@ -1267,7 +1214,7 @@ between them.
12671214
.. _tcm_configuration_reference_security:
12681215

12691216
security
1270-
~~~~~~~~
1217+
--------
12711218

12721219
The ``security`` section defines the security parameters of |tcm|.
12731220

@@ -1369,7 +1316,7 @@ The ``security`` section defines the security parameters of |tcm|.
13691316
.. _tcm_configuration_reference_mode:
13701317

13711318
mode
1372-
~~~~
1319+
----
13731320

13741321
.. confval:: mode
13751322

0 commit comments

Comments
 (0)