3.0 configuration (#3825)

andreyaksenov · andreyaksenov · commit 289f2604583a · 2023-12-06T13:05:13.000+03:00
Document a new declarative configuration approach: local YAML file and etcd config
diff --git a/doc/book/admin/start_stop_instance.rst b/doc/book/admin/start_stop_instance.rst
@@ -124,6 +124,8 @@ With a single ``tt`` call, you can:
 *   connect to a specific instance of an application
 *   stop a specific instance of an application or all its instances
 
+.. _admin-start_stop_instance-multi-instance-layout:
+
 Application layout
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/code_snippets/snippets/config/README.md b/doc/code_snippets/snippets/config/README.md
@@ -0,0 +1,11 @@
+# Configuration
+
+A sample application demonstrating various features related to Tarantool [configuration](https://www.tarantool.io/en/doc/latest/concepts/configuration/).
+
+## Running
+
+To run applications placed in [instances.enabled](instances.enabled), go to the `config` directory in the terminal and execute the `tt start` command, for example:
+
+```console
+$ tt start application
+```
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application/config.yaml
@@ -0,0 +1,13 @@
+app:
+  file: 'myapp.lua'
+  cfg:
+    greeting: 'Hello'
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen: "3301"
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua b/doc/code_snippets/snippets/config/instances.enabled/application/myapp.lua
@@ -0,0 +1,4 @@
+-- myapp.lua --
+local log = require('log').new("myapp")
+local config = require('config')
+log.info("%s from app, %s!", config:get('app.cfg.greeting'), box.info.name)
diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/etcd/config.yaml
@@ -0,0 +1,5 @@
+config:
+  etcd:
+    endpoints:
+      - http://localhost:2379
+    prefix: /example
diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/etcd/instances.yml
@@ -0,0 +1,3 @@
+instance001:
+instance002:
+instance003:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd_full/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/etcd_full/config.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
diff --git a/doc/code_snippets/snippets/config/instances.enabled/etcd_full/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/etcd_full/instances.yml
@@ -0,0 +1,3 @@
+instance001:
+instance002:
+instance003:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/global_scope/config.yaml
@@ -0,0 +1,9 @@
+iproto:
+  listen: "3301"
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001: {}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/global_scope/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/group_scope/config.yaml
@@ -0,0 +1,8 @@
+groups:
+  group001:
+    iproto:
+      listen: "3301"
+    replicasets:
+      replicaset001:
+        instances:
+          instance001: {}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/group_scope/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/config.yaml
@@ -0,0 +1,8 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen: "3301"
diff --git a/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/instance_scope/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/config.yaml
@@ -0,0 +1,8 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        iproto:
+          listen: "3301"
+        instances:
+          instance001: {}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/replicaset_scope/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/templating/config.yaml
@@ -0,0 +1,10 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            snapshot:
+              dir: ./var/{{ instance_name }}/snapshots
+            wal:
+              dir: ./var/{{ instance_name }}/wals
diff --git a/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/templating/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/tt.yaml b/doc/code_snippets/snippets/config/tt.yaml
@@ -0,0 +1,63 @@
+tt:
+  modules:
+    # Directory where the external modules are stored.
+    directory: "modules"
+
+  app:
+    # Directory that stores various instance runtime
+    # artifacts like console socket, PID file, etc.
+    run_dir: "var/run"
+
+    # Directory that stores log files.
+    log_dir: var/log
+
+    # The maximum size in MB of the log file before it gets rotated.
+    log_maxsize: 100
+
+    # The maximum number of days to retain old log files.
+    log_maxage: 8
+
+    # The maximum number of old log files to retain.
+    log_maxbackups: 10
+
+    # Restart instance on failure.
+    restart_on_failure: false
+
+    # Directory where write-ahead log (.xlog) files are stored.
+    wal_dir: "var/lib"
+
+    # Directory where memtx stores snapshot (.snap) files.
+    memtx_dir: "var/lib"
+
+    # Directory where vinyl files or subdirectories will be stored.
+    vinyl_dir: "var/lib"
+
+    # Directory that stores binary files.
+    bin_dir: "bin"
+
+    # Directory that stores Tarantool header files.
+    inc_dir: "include"
+
+    # Path to directory that stores all applications.
+    # The directory can also contain symbolic links to applications.
+    instances_enabled: "instances.enabled"
+
+    # Tarantoolctl artifacts layout compatibility: if set to true tt will not create application
+    # sub-directories for control socket, pid files, log files, etc.. Data files (wal, vinyl,
+    # snap) and multi-instance applications are not affected by this option.
+    tarantoolctl_layout: false
+
+  # Path to file with credentials for downloading Tarantool Enterprise Edition.
+  # credential_path: /path/to/file
+  ee:
+    credential_path: ""
+
+  templates:
+    # The path to templates search directory.
+    - path: "templates"
+
+  repo:
+    # Directory where local rocks files could be found.
+    rocks: ""
+    # Directory that stores installation files.
+    distfiles: "distfiles"
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/config.yaml
@@ -0,0 +1,31 @@
+credentials:
+  users:
+    replicator:
+      password: 'topsecret'
+      roles: [replication]
+
+iproto:
+  advertise:
+    peer: replicator@
+
+replication:
+  failover: election
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            iproto:
+              listen: 127.0.0.1:3301
+          instance002:
+            iproto:
+              listen: 127.0.0.1:3302
+          instance003:
+            iproto:
+              listen: 127.0.0.1:3303
+
+# Load sample data
+app:
+  file: 'data.lua'
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/data.lua b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/data.lua
@@ -0,0 +1,32 @@
+function create_space()
+    box.schema.space.create('bands')
+    box.space.bands:format({
+        { name = 'id', type = 'unsigned' },
+        { name = 'band_name', type = 'string' },
+        { name = 'year', type = 'unsigned' }
+    })
+    box.space.bands:create_index('primary', { parts = { 'id' } })
+end
+
+function create_sync_space()
+    box.schema.space.create('bands', { is_sync = true })
+    box.space.bands:format({
+        { name = 'id', type = 'unsigned' },
+        { name = 'band_name', type = 'string' },
+        { name = 'year', type = 'unsigned' }
+    })
+    box.space.bands:create_index('primary', { parts = { 'id' } })
+end
+
+function load_data()
+    box.space.bands:insert { 1, 'Roxette', 1986 }
+    box.space.bands:insert { 2, 'Scorpions', 1965 }
+    box.space.bands:insert { 3, 'Ace of Base', 1987 }
+    box.space.bands:insert { 4, 'The Beatles', 1960 }
+    box.space.bands:insert { 5, 'Pink Floyd', 1965 }
+    box.space.bands:insert { 6, 'The Rolling Stones', 1962 }
+    box.space.bands:insert { 7, 'The Doors', 1965 }
+    box.space.bands:insert { 8, 'Nirvana', 1987 }
+    box.space.bands:insert { 9, 'Led Zeppelin', 1968 }
+    box.space.bands:insert { 10, 'Queen', 1970 }
+end
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/auto_leader/instances.yml
@@ -0,0 +1,3 @@
+instance001:
+instance002:
+instance003:
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/config.yaml
@@ -0,0 +1,35 @@
+credentials:
+  users:
+    replicator:
+      password: 'topsecret'
+      roles: [replication]
+    client:
+      password: 'secret'
+      roles: [super]
+
+iproto:
+  advertise:
+    peer: replicator@
+
+replication:
+  failover: manual
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        leader: instance001
+        instances:
+          instance001:
+            iproto:
+              listen: 127.0.0.1:3301
+          instance002:
+            iproto:
+              listen: 127.0.0.1:3302
+          instance003:
+            iproto:
+              listen: 127.0.0.1:3303
+
+# Load sample data
+app:
+  file: 'myapp.lua'
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/instances.yml
@@ -0,0 +1,3 @@
+instance001:
+instance002:
+instance003:
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua b/doc/code_snippets/snippets/replication/instances.enabled/manual_leader/myapp.lua
@@ -0,0 +1,32 @@
+function create_space()
+    box.schema.space.create('bands')
+    box.space.bands:format({
+        { name = 'id', type = 'unsigned' },
+        { name = 'band_name', type = 'string' },
+        { name = 'year', type = 'unsigned' }
+    })
+    box.space.bands:create_index('primary', { parts = { 'id' } })
+end
+
+function create_sync_space()
+    box.schema.space.create('bands', { is_sync = true })
+    box.space.bands:format({
+        { name = 'id', type = 'unsigned' },
+        { name = 'band_name', type = 'string' },
+        { name = 'year', type = 'unsigned' }
+    })
+    box.space.bands:create_index('primary', { parts = { 'id' } })
+end
+
+function load_data()
+    box.space.bands:insert { 1, 'Roxette', 1986 }
+    box.space.bands:insert { 2, 'Scorpions', 1965 }
+    box.space.bands:insert { 3, 'Ace of Base', 1987 }
+    box.space.bands:insert { 4, 'The Beatles', 1960 }
+    box.space.bands:insert { 5, 'Pink Floyd', 1965 }
+    box.space.bands:insert { 6, 'The Rolling Stones', 1962 }
+    box.space.bands:insert { 7, 'The Doors', 1965 }
+    box.space.bands:insert { 8, 'Nirvana', 1987 }
+    box.space.bands:insert { 9, 'Led Zeppelin', 1968 }
+    box.space.bands:insert { 10, 'Queen', 1970 }
+end
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml b/doc/code_snippets/snippets/replication/instances.enabled/master_master/config.yaml
@@ -0,0 +1,28 @@
+credentials:
+  users:
+    replicator:
+      password: 'topsecret'
+      roles: [replication]
+
+iproto:
+  advertise:
+    peer: replicator@
+
+replication:
+  failover: off
+
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            database:
+              mode: rw
+            iproto:
+              listen: 127.0.0.1:3301
+          instance002:
+            database:
+              mode: rw
+            iproto:
+              listen: 127.0.0.1:3302
diff --git a/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml b/doc/code_snippets/snippets/replication/instances.enabled/master_master/instances.yml
@@ -0,0 +1,2 @@
+instance001:
+instance002:
diff --git a/doc/code_snippets/snippets/replication/tt.yaml b/doc/code_snippets/snippets/replication/tt.yaml
diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst
diff --git a/doc/concepts/configuration/configuration_code.rst b/doc/concepts/configuration/configuration_code.rst
diff --git a/doc/concepts/configuration/configuration_etcd.rst b/doc/concepts/configuration/configuration_etcd.rst
diff --git a/doc/concepts/configuration/configuration_migrating.rst b/doc/concepts/configuration/configuration_migrating.rst
diff --git a/doc/concepts/index.rst b/doc/concepts/index.rst
diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst
diff --git a/doc/reference/configuration/index.rst b/doc/reference/configuration/index.rst
diff --git a/doc/reference/index.rst b/doc/reference/index.rst
diff --git a/doc/reference/reference_lua/config.rst b/doc/reference/reference_lua/config.rst
diff --git a/doc/reference/reference_lua/index.rst b/doc/reference/reference_lua/index.rst
diff --git a/doc/reference/tooling/tt_cli/cluster.rst b/doc/reference/tooling/tt_cli/cluster.rst
diff --git a/doc/reference/tooling/tt_cli/commands.rst b/doc/reference/tooling/tt_cli/commands.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+instance001:`
	`2`	`+instance002:`
	`3`	`+instance003:`