Roles: update per DEV review

Author: andreyaksenov

doc/book/admin/index.rst

@@ -25,6 +25,7 @@ This chapter includes the following sections:
    :maxdepth: 2
    :numbered: 0
 
+   instance_config
    start_stop_instance
    modules
    logs

doc/book/cluster_app/instance_config.rst renamed to doc/book/admin/instance_config.rst

@@ -1,23 +1,23 @@
 -- greeter.lua --
 local log = require('log').new("greeter")
 
-local function validate_config(cfg)
+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_config(cfg)
+local function apply(cfg)
     log.info("%s from the 'greeter' role!", cfg.greeting)
 end
 
-local function stop_role()
+local function stop()
     log.info("The 'greeter' role is stopped")
 end
 
 return {
-    validate = validate_config,
-    apply = apply_config,
-    stop = stop_role,
+    validate = validate,
+    apply = apply,
+    stop = stop,
 }

doc/book/cluster_app.rst

@@ -2,17 +2,17 @@
 local httpd
 local json = require('json')
 
-local function validate_config(cfg)
+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 <= 65536, "'port' should be between 1 and 65536")
+        assert(cfg.port >= 1 and cfg.port <= 65535, "'port' should be between 1 and 65535")
     end
 end
 
-local function apply_config(cfg)
+local function apply(cfg)
     if httpd then
         httpd:stop()
     end
@@ -48,7 +48,7 @@ local function apply_config(cfg)
     httpd:start()
 end
 
-local function stop_role()
+local function stop()
     httpd:stop()
 end
 
@@ -59,7 +59,7 @@ end
 init()
 
 return {
-    validate = validate_config,
-    apply = apply_config,
-    stop = stop_role,
+    validate = validate,
+    apply = apply,
+    stop = stop,
 }

doc/code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua

@@ -2,10 +2,10 @@ credentials:
   users:
     replicator:
       password: 'topsecret'
-      roles: [replication]
+      roles: [ replication ]
     storage:
       password: 'secret'
-      roles: [sharding]
+      roles: [ sharding ]
 
 iproto:
   advertise:
@@ -19,11 +19,11 @@ sharding:
 
 groups:
   storages:
-    roles: [roles.crud-storage]
+    roles: [ roles.crud-storage ]
     app:
       module: storage
     sharding:
-      roles: [storage]
+      roles: [ storage ]
     replication:
       failover: manual
     replicasets:
@@ -50,7 +50,7 @@ groups:
               listen:
               - uri: '127.0.0.1:3305'
   routers:
-    roles: [roles.crud-router]
+    roles: [ roles.crud-router ]
     roles_cfg:
       roles.crud-router:
         stats: true
@@ -62,7 +62,7 @@ groups:
     app:
       module: router
     sharding:
-      roles: [router]
+      roles: [ router ]
     replicasets:
       router-a:
         instances:

doc/code_snippets/snippets/config/instances.enabled/application_role_http_api/http-api.lua

@@ -240,7 +240,7 @@ Roles and configuration scopes
 ******************************
 
 As the most of configuration options, roles and their configurations can be defined at :ref:`different levels <configuration_scopes>`.
-Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the ``map`` type, different rules are used when applying the configuration:
+Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the ``map`` type, there are some specifics when applying the configuration:
 
 -   For ``roles``, an instance's role takes precedence over roles defined at another levels.
     In the example below, ``instance001`` has only ``role3``:
@@ -258,7 +258,7 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the
 
 -   For ``roles_cfg``, the following rules are applied:
 
-    -   If the same role's option exists at different levels, an instance's option takes precedence over options defined at another levels.
+    -   If a configuration for the same role is provided at different levels, an instance configuration takes precedence over configuration defined at another levels.
         In the example below, ``role1.greeting`` is ``'Hi'``:
 
         ..  code-block:: yaml
@@ -275,23 +275,22 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the
                     role1:
                       greeting: 'Hi'
 
-    -   If some role's option exists at one level but doesn't exist at another level, these options are merged.
-        In the example below, ``role1.greeting`` is ``'Hi'`` and ``role1.farewell`` is ``'Goodbye'``:
+    -   If configurations for different roles are provided at different levels, both configurations are applied at the instance level.
+        In the example below, ``instance001`` has ``role1.greeting`` set to ``'Hi'`` and ``role2.farewell`` set to ``'Bye'``:
 
         ..  code-block:: yaml
 
             # ...
             replicaset001:
               roles_cfg:
                 role1:
-                  greeting: 'Hello'
-                  farewell: 'Goodbye'
+                  greeting: 'Hi'
               instances:
                 instance001:
-                  roles: [ role1 ]
+                  roles: [ role1, role2 ]
                   roles_cfg:
-                    role1:
-                      greeting: 'Hi'
+                    role2:
+                      farewell: 'Bye'