Docs for roles/role_cfg (#4221)

andreyaksenov · web-flow · commit fb2dd553dd51 · 2024-06-10T11:48:13.000+03:00
diff --git a/doc/book/admin/instance_config.rst b/doc/book/admin/instance_config.rst
@@ -20,7 +20,7 @@ The main steps of creating and preparing the application for deployment are:
 In this section, a `sharded_cluster <https://github.com/tarantool/doc/tree/latest/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster>`_ application is used as an example.
 This cluster includes 5 instances: one router and 4 storages, which constitute two replica sets.
 
-.. image:: admin_instances_dev.png
+.. image:: /book/admin/admin_instances_dev.png
     :align: left
     :width: 700
     :alt: Cluster topology
@@ -171,7 +171,7 @@ define instances to run on each machine by changing the content of the ``instanc
 
 -   On the developer's machine, this file might include all the instances defined in the cluster configuration.
 
-    .. image:: admin_instances_dev.png
+    .. image:: /book/admin/admin_instances_dev.png
         :align: left
         :width: 700
         :alt: Cluster topology
@@ -184,7 +184,7 @@ define instances to run on each machine by changing the content of the ``instanc
 
 -   In the production environment, this file includes instances to run on the specific machine.
 
-    .. image:: admin_instances_prod.png
+    .. image:: /book/admin/admin_instances_prod.png
         :align: left
         :width: 700
         :alt: Cluster topology
diff --git a/doc/book/index.rst b/doc/book/index.rst
@@ -17,6 +17,7 @@ User's Guide
     box/index
     admin/index
     monitoring/index
+    cluster_app
     connectors
     ../reference/reference_sql/index
     faq
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application_role/config.yaml
@@ -0,0 +1,7 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            roles: [ greeter ]
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role/greeter.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role/greeter.lua
@@ -0,0 +1,6 @@
+-- greeter.lua --
+return {
+    validate = function() end,
+    apply = function() require('log').info("Hi from the 'greeter' role!") end,
+    stop = function() end,
+}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application_role/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/byeer.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/byeer.lua
@@ -0,0 +1,9 @@
+-- byeer.lua --
+local log = require('log').new("byeer")
+
+return {
+    dependencies = { 'greeter' },
+    validate = function() end,
+    apply = function() log.info("Bye from the 'byeer' role!") end,
+    stop = function() end,
+}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/config.yaml
@@ -0,0 +1,10 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            roles: [ greeter ]
+            roles_cfg:
+              greeter:
+                greeting: 'Hi'
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua
@@ -0,0 +1,23 @@
+-- greeter.lua --
+local log = require('log').new("greeter")
+
+local function validate(cfg)
+    if cfg.greeting then
+        assert(type(cfg.greeting) == "string", "'greeting' should be a string")
+        assert(cfg.greeting == "Hi" or cfg.greeting == "Hello", "'greeting' should be 'Hi' or 'Hello'")
+    end
+end
+
+local function apply(cfg)
+    log.info("%s from the 'greeter' role!", cfg.greeting)
+end
+
+local function stop()
+    log.info("The 'greeter' role is stopped")
+end
+
+return {
+    validate = validate,
+    apply = apply,
+    stop = stop,
+}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/README.md b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/README.md
@@ -0,0 +1,22 @@
+# HTTP API
+
+A sample application showing how to implement a custom `http-api` role.
+
+## Running
+
+To start an application, execute the following command in the [config](../../../config) directory:
+
+```console
+$ tt start application_role_http_api
+```
+
+## Making test requests
+
+To test the API, make the following requests:
+
+```console
+$ curl -X GET --location "http://0.0.0.0:8080/band?limit=7" \
+    -H "Accept: application/json"
+$ curl -X GET --location "http://0.0.0.0:8080/band/5" \
+    -H "Accept: application/json"
+```
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/config.yaml b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/config.yaml
@@ -0,0 +1,11 @@
+groups:
+  group001:
+    replicasets:
+      replicaset001:
+        instances:
+          instance001:
+            roles: [ http-api ]
+            roles_cfg:
+              http-api:
+                host: '127.0.0.1'
+                port: 8080
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/data.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/data.lua
@@ -0,0 +1,32 @@
+local data = {}
+
+data.add_sample_data =  function()
+    box.watch('box.status', function()
+        if box.info.ro then
+            return
+        end
+
+        box.schema.space.create('bands', { if_not_exists = 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' } })
+        box.space.bands:create_index('band', { parts = { 'band_name' } })
+        box.space.bands:create_index('year_band', { parts = { { 'year' }, { 'band_name' } } })
+
+        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)
+end
+
+return data
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua
@@ -0,0 +1,65 @@
+-- http-api.lua --
+local httpd
+local json = require('json')
+
+local function validate(cfg)
+    if cfg.host then
+        assert(type(cfg.host) == "string", "'host' should be a string containing a valid IP address")
+    end
+    if cfg.port then
+        assert(type(cfg.port) == "number", "'port' should be a number")
+        assert(cfg.port >= 1 and cfg.port <= 65535, "'port' should be between 1 and 65535")
+    end
+end
+
+local function apply(cfg)
+    if httpd then
+        httpd:stop()
+    end
+    httpd = require('http.server').new(cfg.host, cfg.port)
+    local response_headers = { ['content-type'] = 'application/json' }
+    httpd:route({ path = '/band/:id', method = 'GET' }, function(req)
+        local id = req:stash('id')
+        local band_tuple = box.space.bands:get(tonumber(id))
+        if not band_tuple then
+            return { status = 404, body = 'Band not found' }
+        else
+            local band = { id = band_tuple['id'],
+                           band_name = band_tuple['band_name'],
+                           year = band_tuple['year'] }
+            return { status = 200, headers = response_headers, body = json.encode(band) }
+        end
+    end)
+    httpd:route({ path = '/band', method = 'GET' }, function(req)
+        local limit = req:query_param('limit')
+        if not limit then
+            limit = 5
+        end
+        local band_tuples = box.space.bands:select({}, { limit = tonumber(limit) })
+        local bands = {}
+        for _, tuple in pairs(band_tuples) do
+            local band = { id = tuple['id'],
+                           band_name = tuple['band_name'],
+                           year = tuple['year'] }
+            table.insert(bands, band)
+        end
+        return { status = 200, headers = response_headers, body = json.encode(bands) }
+    end)
+    httpd:start()
+end
+
+local function stop()
+    httpd:stop()
+end
+
+local function init()
+    require('data'):add_sample_data()
+end
+
+init()
+
+return {
+    validate = validate,
+    apply = apply,
+    stop = stop,
+}
diff --git a/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/instances.yml b/doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/instances.yml
@@ -0,0 +1 @@
+instance001:
diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/sharded_cluster-scm-1.rockspec b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster/sharded_cluster-scm-1.rockspec
@@ -5,7 +5,7 @@ source  = {
 }
 
 dependencies = {
-    'vshard == 0.1.26'
+    'vshard == 0.1.27'
 }
 build = {
     type = 'none';
diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/config.yaml
@@ -2,10 +2,10 @@ credentials:
   users:
     replicator:
       password: 'topsecret'
-      roles: [replication]
+      roles: [ replication ]
     storage:
       password: 'secret'
-      roles: [sharding]
+      roles: [ sharding ]
 
 iproto:
   advertise:
@@ -19,9 +19,11 @@ sharding:
 
 groups:
   storages:
-    roles: [storage]
+    roles: [ roles.crud-storage ]
+    app:
+      module: storage
     sharding:
-      roles: [storage]
+      roles: [ storage ]
     replication:
       failover: manual
     replicasets:
@@ -48,9 +50,19 @@ groups:
               listen:
               - uri: '127.0.0.1:3305'
   routers:
-    roles: [router]
+    roles: [ roles.crud-router ]
+    roles_cfg:
+      roles.crud-router:
+        stats: true
+        stats_driver: metrics
+        stats_quantiles: false
+        stats_quantile_tolerated_error: 0.001
+        stats_quantile_age_buckets_count: 5
+        stats_quantile_max_age_time: 180
+    app:
+      module: router
     sharding:
-      roles: [router]
+      roles: [ router ]
     replicasets:
       router-a:
         instances:
diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/router.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/router.lua
@@ -1,17 +1 @@
 local vshard = require('vshard')
-local crud = require('crud')
-
-local M = {}
-
-function M.validate()
-end
-
-function M.apply()
-    crud.init_router()
-end
-
-function M.stop()
-    crud.stop_router()
-end
-
-return M
diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/sharded_cluster_crud-scm-1.rockspec b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/sharded_cluster_crud-scm-1.rockspec
@@ -5,8 +5,8 @@ source  = {
 }
 
 dependencies = {
-    'vshard == 0.1.26',
-    'crud == 1.4.3'
+    'vshard == 0.1.27',
+    'crud == 1.5.2'
 }
 build = {
     type = 'none';
diff --git a/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/storage.lua b/doc/code_snippets/snippets/sharding/instances.enabled/sharded_cluster_crud/storage.lua
@@ -1,29 +1,17 @@
-local crud = require('crud')
-
-local M = {}
-
-function M.validate()
-end
-
-function M.apply()
-    crud.init_storage()
-    if box.info.ro ~= true then
-        box.schema.create_space('bands', {
-            format = {
-                { name = 'id', type = 'unsigned' },
-                { name = 'bucket_id', type = 'unsigned' },
-                { name = 'band_name', type = 'string' },
-                { name = 'year', type = 'unsigned' }
-            },
-            if_not_exists = true
-        })
-        box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true })
-        box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true })
+box.watch('box.status', function()
+    if box.info.ro then
+        return
     end
-end
-
-function M.stop()
-    crud.stop_storage()
-end
 
-return M
+    box.schema.create_space('bands', {
+        format = {
+            { name = 'id', type = 'unsigned' },
+            { name = 'bucket_id', type = 'unsigned' },
+            { name = 'band_name', type = 'string' },
+            { name = 'year', type = 'unsigned' }
+        },
+        if_not_exists = true
+    })
+    box.space.bands:create_index('id', { parts = { 'id' }, if_not_exists = true })
+    box.space.bands:create_index('bucket_id', { parts = { 'bucket_id' }, unique = false, if_not_exists = true })
+end)
diff --git a/doc/code_snippets/snippets/sharding/templates/basic/{{.name}}-scm-1.rockspec.tt.template b/doc/code_snippets/snippets/sharding/templates/basic/{{.name}}-scm-1.rockspec.tt.template
@@ -5,7 +5,7 @@ source  = {
 }
 
 dependencies = {
-    'vshard == 0.1.25'
+    'vshard == 0.1.27'
 }
 build = {
     type = 'none';
diff --git a/doc/concepts/configuration.rst b/doc/concepts/configuration.rst
diff --git a/doc/how-to/app/app_roles.rst b/doc/how-to/app/app_roles.rst
diff --git a/doc/how-to/app/index.rst b/doc/how-to/app/index.rst
diff --git a/doc/reference/configuration/configuration_reference.rst b/doc/reference/configuration/configuration_reference.rst
