Document new 'config' API

Author: andreyaksenov

doc/reference/reference_lua/config.rst

@@ -46,11 +46,17 @@ API Reference
             -
 
         *   -   :ref:`config:get() <config_api_reference_get>`
-            -   Get a configuration applied to the current instance
+            -   Get a configuration applied to the specified instance
 
         *   -   :ref:`config:info() <config_api_reference_info>`
             -   Get the current instance's state in regard to configuration
 
+        *   -   :ref:`config:instance_uri() <config_api_reference_instance_uri>`
+            -   Get a URI of the specified instance
+
+        *   -   :ref:`config:instances() <config_api_reference_instances>`
+            -   List all instances of the cluster
+
         *   -   :ref:`config:reload() <config_api_reference_reload>`
             -   Reload the current instance's configuration
 
@@ -83,12 +89,19 @@ config API
 
     .. _config_api_reference_get:
 
-    ..  method:: get([param])
+    ..  method:: get([param, opts])
+
+        Get a configuration applied to the current or remote instance.
+        Note that there is the following difference between getting a configuration for the current and remote instance:
 
-        Get a configuration applied to the current instance.
-        Optionally, you can pass a configuration option name to get its value.
+        -   For the current instance, ``get()`` returns an instance configuration taking into account all configuration sources, including environment variables.
+        -   For a remote instance, ``get()`` takes into account only cluster configuration. This means that environment variables are ignored.
 
         :param string param: a configuration option name
+        :param table opts: options to pass. The following options are available:
+
+                           -   ``instance`` (since :doc:`3.1.0 </release/3.1.0>`) -- a name of a remote instance whose configuration should be obtained
+
         :return: an instance configuration
 
         **Examples:**
@@ -121,10 +134,18 @@ config API
 
     .. _config_api_reference_info:
 
-    ..  method:: info()
+    ..  method:: info([version])
 
         Get the current instance's state in regard to configuration.
 
+        :param string version: (since :doc:`3.1.0 </release/3.1.0>`) the version of the information that should be returned. ``version`` can be one of the following values:
+
+                               * ``v1`` (default): no additional information in the ``meta`` field
+                               * ``v2``: the ``meta`` field includes two fields:
+
+                                   * the ``active`` field includes information for the last successfully applied configuration
+                                   * the ``last`` field includes information about the last loaded configuration
+
         :return: a table containing an instance's state
 
         The returned state includes the following sections:
@@ -206,6 +227,66 @@ config API
                 ...
 
 
+    .. _config_api_reference_instances:
+
+    ..  method:: instances()
+
+        **Since:** :doc:`3.1.0 </release/3.1.0>`
+
+        List all instances of the cluster.
+
+        :return: a table containing information about instances
+
+        The returned table uses instance names as the keys and contains the following information for each instance:
+
+        -   ``instance_name`` -- an instance name
+        -   ``replicaset_name`` -- a name of the replica set the instance belongs to
+        -   ``group_name`` -- a name of the group the instance belongs to
+
+        **Example**
+
+        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:
+
+        ..  code-block:: lua
+
+            local config = require('config')
+            for instance_name in pairs(config:instances()) do
+                local connpool = require('experimental.connpool')
+                local conn = connpool.connect(instance_name)
+                local log = require('log')
+                log.info(string.format("Connection URI for '%s': %s:%s", instance_name, conn.host, conn.port))
+            end
+
+
+    .. _config_api_reference_instance_uri:
+
+    ..  method:: instance_uri([uri_type, opts])
+
+        **Since:** :doc:`3.1.0 </release/3.1.0>`
+
+        Get a URI of the current or remote instance.
+
+        :param string uri_type: a URI type. There are the following URI types are supported:
+
+                                * ``peer`` -- a URI used to advertise the instance to other cluster members. See also: :ref:`configuration_reference_iproto_advertise_peer`.
+                                * ``sharding`` -- a URI used to advertise the current instance to a router and rebalancer. See also: :ref:`configuration_reference_iproto_advertise_sharding`.
+
+        :param table opts: options to pass. The following options are available:
+
+                           -   ``instance`` -- a name of a remote instance whose URI should be obtained
+
+        :return: an instance URI
+
+        **Example**
+
+        The example below shows how to get a URI used to advertise ``storage-b-003`` to other cluster members:
+
+        ..  code-block:: lua
+
+            local config = require('config')
+            config:instance_uri('peer', { instance = 'storage-b-003' })
+
+
     .. _config_api_reference_reload:
 
     ..  method:: reload()