Module topology.topology

topology module

Module functions

new (conf_client, name[, autocommit[, opts]]) Create a new topology.
instance.new_instance (self, instance_name[, opts[, replicaset_name]]) Add a new Tarantool instance to a topology.
instance.new_replicaset (self, replicaset_name[, opts]) Add new replicaset to a topology.
instance.delete_instance (self, instance_name) Delete instance from a topology.
instance.delete_replicaset (self, replicaset_name) Delete a replicaset.
instance.set_instance_options (self, instance_name, opts) Set parameters of existed Tarantool instance.
instance.set_replicaset_options (self, replicaset_name, opts) Set parameters of an existed replicaset in a topology.
instance.set_instance_reachable (self, instance_name) Switch state of Tarantool instance to a reachable.
instance.set_instance_unreachable (self, instance_name) Switch state of Tarantool instance to a unreachable.
instance.set_topology_options (self, opts) Set topology options.
instance.get_routers (self) Get routers.
instance.get_storages (self[, vshard_group]) Get storages.
instance.get_instance_options (self, instance_name) Get instance options.
instance.get_replicaset_options (self, replicaset_name) Get replicaset options.
instance.get_topology_options (self) Get topology options.
instance.get_vshard_config (self[, vshard_group]) Get vshard configuration.
instance.get_instances_it (self) Get instances iterator.
instance.get_replicasets_it (self) Get replicasets iterator.
instance.new_instance_link (self, upstream, downstreams) Add a new instance link.
instance.delete_instance_link (self, upstream, downstreams) Delete an instance link.
topology_obj.delete (self) Delete topology.
topology_obj.commit (self) Send local changes to remote configuration storage.
topology_obj.on_change (self, function_cb, time_interval) Execute function on changes in remote topology.


Module functions

new (conf_client, name[, autocommit[, opts]])

Create a new topology.

Parameters:

  • conf_client (table)

    A configuration client object. See Configuration storage module.
  • name (string)

    A topology name.
  • autocommit (table, optional)

    Enable mode of operation of a configuration storage connection. Each individual configuration storage interaction submitted through the configuration storage connection in autocommit mode will be executed in its own transaction that is implicitly committed. Enabled by default.
  • opts (table, optional)

    Topology options.
    • vshard_groups (table, optional)

      Parameters of vshard storage groups. Instance that has a vshard-storage role can belong to different vshard storage groups. For example, hot or cold groups meant to independently process hot and cold data. With multiple groups enabled, every replica set with a vshard-storage role enabled must be assigned to a particular group. The assignment can never be changed. By default there is a single vshard group 'default' and by default instances without vshard group belongs to the 'default' group. Every vshard group contains sharding parameters specific for this group. See more about vshard storage groups in Tarantool Cartridge Developers Guide. Sharding group may contain sharding configuration parameters described in Sharding Configuration reference.

      - bucket_count - Total bucket count in a cluster. It can not be changed after cluster bootstrap! Default: 3000.

      - rebalancer_disbalance_threshold - Maximal bucket count that can be received in parallel by single replicaset. Default: 1.

      - rebalancer_max_receiving - The maximum number of buckets that can be received in parallel by a single replica set. Default: 100.

      - rebalancer_max_sending - The degree of parallelism for parallel rebalancing. Works for storages only, ignored for routers. Default: 1.

      - discovery_mode - A mode of a bucket discovery fiber: 'on', 'off' or 'once'. Default: 'on'.

      - sync_timeout - Timeout to wait for synchronization of the old master with replicas before demotion. Used when switching a master or when manually calling the sync() function. Default: 1.

      - collect_lua_garbage - If set to true, the Lua collectgarbage() function is called periodically. Default: false.

      - collect_bucket_garbage_interval - The interval between garbage collector actions, in seconds. Default: 0.5.

      - shard_index - Name or id of a TREE index over the bucket id. Default: 'bucket_id'.

    • zone_distances (table, optional)

      A field defining the configuration of relative distances for each zone pair in a replica set. See Sharding Configuration reference and Sharding Administration.

    • failover (table, optional)

      TBD See more about failover configuration in Tarantool Cartridge Developers Guide.

      XXX: failover option is untested.

Returns:

    TopologyConfig

Or

  1. nil
  2. table Error description

Usage:

    local conf_lib = require('conf')
local topology_lib = require('topology')

local urls = {
    'http://localhost:2380',
    'http://localhost:2381',
    'http://localhost:2382',
}
local conf_client = conf_lib.new({ driver = 'etcd', endpoints = urls })
local t = topology_lib.new(conf_client, 'tweedledum')
instance.new_instance (self, instance_name[, opts[, replicaset_name]])

Add a new Tarantool instance to a topology.

Add a new Tarantool instance to a topology.

Parameters:

  • self

    Topology object.
  • instance_name (string)

    Tarantool instance name to add. Name must be globally unique.
  • opts (table, optional)

    instance options.
    • box_cfg (table, optional)

      Instance box.cfg options. box.cfg options should contain at least Uniform Resource Identifier of remote instance with **required** login and password. See Configuration parameters. Note: instance uuid will be generated automatically. See Configuration reference.
    • replicaset (string, optional)

      Replicaset name.
    • advertise_uri (string, optional)

      URI that will be used by clients to connect to this instance. A "URI" is a "Uniform Resource Identifier" and it's format is described in Module uri.
    • zone (string, optional)

      The router sends all read-write requests to the master instance only. Setting replica zones allows sending read-only requests not only to the master instance, but to any available replica that is the ‘nearest’ to the router. Zone can be used, for example, to define the physical distance between the router and each replica in each replica set. In this case read requests are sent to the nearest replica (with the lowest distance). Option used in a table zone_distances in Create a new topology. See more in Sharding Administration.
    • status (string, optional)

      Instance status, possible values are 'reachable' and 'unreachable'. Instance status also can be managed by:

    • vshard_groups (table, optional)

      Names of vshard storage groups. Instance that has a vshard-storage role can belong to different vshard storage groups. For example, hot or cold groups meant to independently process hot and cold data. With multiple groups enabled, every replica set with a vshard-storage role enabled must be assigned to a particular group. The assignment can never be changed. See more about vshard storage groups in Tarantool Cartridge Developers Guide.
    • is_master (boolean, optional)

      True if an instance is a master in replication cluster. See Replication architecture. You can define 0 or 1 masters for each replicaset. It accepts all write requests.
    • is_storage (boolean, optional)

      True if an instance is a storage. See Sharding Architecture.
    • is_router (boolean, optional)

      True if an instance is a router. See Sharding Architecture.

  • replicaset_name (string, optional)

    Replicaset name. Name must be globally unique. It will be created if it does not exist.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.new_replicaset (self, replicaset_name[, opts])

Add new replicaset to a topology.

Adds a new replicaset to a topology.

Note: replication cluster UUID will be generated automatically. See Configuration reference. By default used replication topology is fullmesh. However custom replication topology (see Replication architecture) can be made using methods Create a new instance link and Delete an instance link.

Parameters:

  • self

    Topology object.
  • replicaset_name (string)

    Name of replicaset to add. Name must be globally unique.
  • opts (table, optional)

    replicaset options.
    • master_mode (string, optional)

      Mode that describes how master instance should be assigned. Possible values:

      - single - it is allowed to have only a single master in replication cluster that should me assigned manually.

      - multimaster - it is allowed to have several instances with master role in a replication cluster, all of them should be assigned manually.

      - auto - master role will be assigned automatically. Auto mode requires specifying advisory roles (leader, follower, or candidate) in Tarantool instance options (box.cfg). See box.info.election.

      XXX: master_mode option is untested.

    • failover_priority ({false, ...})

      Table with instance names specifying servers failover priority.

      XXX: failover_priority option is untested.

    • weight ({false, ...})

      The weight of a replica set defines the capacity of the replica set: the larger the weight, the more buckets the replica set can store. The total size of all sharded spaces in the replica set is also its capacity metric. By default, all weights of all replicasets are equal. See Sharding Administration.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.delete_instance (self, instance_name)

Delete instance from a topology.

Deletes an instance. Deleted instance still exists in a topology, but has a status expelled and it cannot be used anymore.

Parameters:

  • self

    Topology object.
  • instance_name (string)

    Name of an instance to delete.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.delete_replicaset (self, replicaset_name)

Delete a replicaset.

Deletes replicaset from a topology.

Parameters:

  • self

    Topology object.
  • replicaset_name (string)

    Name of a replicaset to delete.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.set_instance_options (self, instance_name, opts)

Set parameters of existed Tarantool instance.

Set parameters of existed Tarantool instance.

Parameters:

  • self

    Topology object.
  • instance_name (string)

    Tarantool instance name.
  • opts (table)

    Instance options.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.set_replicaset_options (self, replicaset_name, opts)

Set parameters of an existed replicaset in a topology.

Set parameters of a replicaset in a topology.

Parameters:

  • self

    Topology object.
  • replicaset_name (string)

    Replicaset name.
  • opts (table)

    See description of options in Replicaset options.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.set_instance_reachable (self, instance_name)

Switch state of Tarantool instance to a reachable.

Make instance available for clients. It participate in replication and can serve requests.

Parameters:

  • self

    Topology object.
  • instance_name (string)

    Tarantool instance name.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.set_instance_unreachable (self, instance_name)

Switch state of Tarantool instance to a unreachable.

Make instance unavailable for clients. It cannot participate in replication, it cannot serve requests.

Parameters:

  • self

    Topology object.
  • instance_name (string)

    Tarantool instance name.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.set_topology_options (self, opts)

Set topology options.

Set topology options.

Parameters:

Returns:

    true

Or

  1. nil
  2. table Error description
instance.get_routers (self)

Get routers.

Get a table with routers in a topology.

Parameters:

  • self

    Topology object.

Returns:

    table Map with instance names and their options described in Create a new instance.

    Example of response: 

     {
   'router-1' = {
        is_router = true,
        ...
   },
   'router-2' = {
        is_router = true,
        ...
   },
 }

Or

  1. nil
  2. table Error description
instance.get_storages (self[, vshard_group])

Get storages.

Get a table with storages in a topology.

Parameters:

Returns:

    table Map with instance names and their options described in Create a new instance.

    Example of response: 

     {
   'storage-1' = {
        is_storage = true,
        ...
   },
   'storage-2' = {
        is_storage = true,
        ...
   },
 }

Or

  1. nil
  2. table Error description
instance.get_instance_options (self, instance_name)

Get instance options.

Get instance options.

Parameters:

  • self

    Topology object.
  • instance_name (string)

    Tarantool instance name.

Returns:

    table Table with with instance options described in Create a new instance. and key box_cfg with table that contains Tarantool configuration parameters.

    Example of response: 

     {
   box_cfg = {
     feedback_enabled = true,
     memtx_memory = 268435456,
     instance_uuid = "79a116a2-a88a-4e6c-9f83-9621127e9aeb",
     read_only = true,
     replicaset_uuid = "2ad6d727-1b19-4241-bde7-301f15575f69",
     replication = {},
     replication_sync_timeout = 6,
     wal_mode = "write"
   },
   is_master = false,
   is_storage = true
 }

Or

  1. nil
  2. table Error description
instance.get_replicaset_options (self, replicaset_name)

Get replicaset options.

Get replicaset options.

Parameters:

  • self

    Topology object.
  • replicaset_name (string)

    Replicaset name.

Returns:

    table Table with replicaset options, see Replicaset options and replicas with names of instances added to that replicaset.

    Example of response: 

     {
   cluster_uuid = '2bff7d87-697f-42f5-b7c7-33f40a8db1ea',
   master_mode = 'auto',
   replicas = { 'instance-name-1', 'instance_name-2', 'instance_name-3' }
 }

Or

  1. nil
  2. table Error description
instance.get_topology_options (self)

Get topology options.

Get topology options.

Parameters:

  • self

    Topology object.

Returns:

    table Table with topology options, see Create a new topology, and key replicasets that contains a table with names of replicasets added to topology.

    Example of response: 

     {
   replicasets = {
      'replicaset_name-1',
      'replicaset_name-2'
   },
   vshard_groups = {
      ...
   },
 }

Or

  1. nil
  2. table Error description
instance.get_vshard_config (self[, vshard_group])

Get vshard configuration.

Method prepares a configuration suitable for vshard bootstrap. In sharding participates instances that belongs to specified vshard group or group 'default' if it is not specified, has router role and has a status 'reachable'. See Sharding quick start guide.

Parameters:

Returns:

    table Table whose format and possible parameters are defined by vshard module and described in Sharding quick start guide and description of basic parameters in Sharding configuration reference.

    Example of response: 

     {
     memtx_memory = 100 * 1024 * 1024,
     bucket_count = 10000,
     rebalancer_disbalance_threshold = 10,
     rebalancer_max_receiving = 100,
     sharding = {
         ['cbf06940-0790-498b-948d-042b62cf3d29'] = { -- replicaset #1
             replicas = {
                 ['8a274925-a26d-47fc-9e1b-af88ce939412'] = {
                     uri = 'storage:storage@127.0.0.1:3301',
                     name = 'storage_1_a',
                     master = true
                 },
                 ['3de2e3e1-9ebe-4d0d-abb1-26d301b84633'] = {
                     uri = 'storage:storage@127.0.0.1:3302',
                     name = 'storage_1_b'
                 }
             },
         }, -- replicaset #1
         ['ac522f65-aa94-4134-9f64-51ee384f1a54'] = { -- replicaset #2
             replicas = {
                 ['1e02ae8a-afc0-4e91-ba34-843a356b8ed7'] = {
                     uri = 'storage:storage@127.0.0.1:3303',
                     name = 'storage_2_a',
                     master = true
                 },
                 ['001688c3-66f8-4a31-8e19-036c17d489c2'] = {
                     uri = 'storage:storage@127.0.0.1:3304',
                     name = 'storage_2_b'
                 }
             },
         }, -- replicaset #2
     }, -- sharding
     weights = ...
 }

Or

  1. nil
  2. table Error description
instance.get_instances_it (self)

Get instances iterator.

Method returns an iterator with pairs 'instance name' and its parameters. Quite useful and powerful with library luafun.

Parameters:

  • self

    Topology object.

Returns:

    table Iterator of tables with instances names and their options.

Or

  1. nil
  2. table Error description

Usage:

    local conf_lib = require('conf')
local topology_lib = require('topology')

local urls = {
    'http://localhost:2380',
    'http://localhost:2381',
    'http://localhost:2382',
}

local conf_client = conf_lib.new({ driver = 'etcd', endpoints = urls })
local t = topology_lib.new(conf_client, 'Tweedledum_and_Tweedledee')
t:new_instance('tweedledum', {
    is_router = true,
})
t:new_instance('tweedledee', {
    is_storage = true,
})
t:get_instances_it():length() -- 2
local predicate_is_storage = function(name, opts)
    return opts.is_storage == true
end
t:get_instances_it():remove_if(predicate_is_storage) -- keep routers only
t:get_replicasets_it():totable() -- {'tweedledee', 'tweedledum'}
local instances = t:get_replicasets_it():tomap()
-- instances['tweedledum']:
-- {
--   box_cfg = {
--     instance_uuid = "9d486fd0-f2c6-4789-9592-ab43d883f320"
--   },
--   is_router = true,
--   status = "reachable",
--   vshard_groups = { "default" }
-- }
instance.get_replicasets_it (self)

Get replicasets iterator.

Method returns a iterator with pairs 'replicaset name' and its parameters. Quite useful and powerful with library luafun.

Parameters:

  • self

    Topology object.

Returns:

    table Iterator of tables with replicasets names and their options.

Or

  1. nil
  2. table Error description

Usage:

    local conf_lib = require('conf')
local topology_lib = require('topology')

local urls = {
    'http://localhost:2380',
    'http://localhost:2381',
    'http://localhost:2382',
}

local conf_client = conf_lib.new({ driver = 'etcd', endpoints = urls })
local t = topology_lib.new(conf_client, 'Tweedledum_and_Tweedledee')
t:new_replicaset('tweedledum')
t:new_replicaset('tweedledee')

t:get_replicasets_it():length() -- 2
t:get_replicasets_it():totable() -- {"tweedledum", "tweedledee"}
instance.new_instance_link (self, upstream, downstreams)

Add a new instance link.

Creates a links between instances. These links constitutes a replication topology.

XXX: Method is not ready.

Parameters:

  • self

    Topology object.
  • upstream (string)

    Name of upstream instance.
  • downstreams ({...})

    Table with names of downstream instances. These instances will be used as downstreams of specified instance anymore.

Returns:

    true

Or

  1. nil
  2. table Error description
instance.delete_instance_link (self, upstream, downstreams)

Delete an instance link.

Deletes a links between instances. These links constitutes a replication topology.

XXX: Method is not ready.

Parameters:

  • self

    Topology object.
  • upstream (string)

    Name of upstream instance.
  • downstreams ({...})

    Table with names of downstream instances. These instances will not be used as downstreams of specified instance anymore.

Returns:

    true

Or

  1. nil
  2. table Error description
topology_obj.delete (self)

Delete topology.

Deletes a topology.

Parameters:

  • self

    Topology object.

Returns:

    true

Or

  1. nil
  2. table Error description
topology_obj.commit (self)

Send local changes to remote configuration storage.

Send topology changes made offline to remote configuration storage. Method is applicable with disabled option autocommit, with enabled autocommit option does nothing. See Create a new topology.

Parameters:

  • self

    Topology object.

Returns:

    true

Or

  1. nil
  2. table Error description
topology_obj.on_change (self, function_cb, time_interval)

Execute function on changes in remote topology.

Function polls remote configuration storage every time interval for changes in topology and execute a function callback once a change happen.

XXX: Method is untested. XXX: See autovshard implementation.

Parameters:

  • self

    Topology object.
  • function_cb (string)

    Callback function that should be executed.
  • time_interval (number)

    Specify a poll interval in seconds. Default interval is 0.1 sec.

Returns:

    None

Usage:

    -- How to update vshard configuration continuously.

local conf_lib = require('conf')
local topology_lib = require('topology')
local vshard = require('vshard')
local fiber = require('fiber')

local urls = {
    'http://localhost:2380',
    'http://localhost:2381',
    'http://localhost:2382',
}

local conf_client = conf_lib.new({ driver = 'etcd', endpoints = urls })
local t = topology_lib.new(conf_client, 'tweedledum')

-- on storage instance
local vshard_storage_cb = function()
   local vshard_cfg = t:get_vshard_config()
   vshard.router.cfg(vshard_cfg)
end
local instance_uuid = os.getenv('TARANTOOL_UUID')
local vshard_cfg = t:get_vshard_config()
vshard.storage.cfg(vshard_cfg, instance_uuid)
fiber.create(t:on_change, vshard_cfg_cb, 0.5)

-- on router instance
local vshard_router_cb = function()
   local vshard_cfg = t:get_vshard_config()
   vshard.router.cfg(vshard_cfg)
end
vshard.router.cfg(vshard_cfg)
vshard.router.bootstrap()
fiber.create(t:on_change, vshard_cfg_cb, 0.5)