Module cartridge

Tarantool framework for distributed applications development.

Cartridge provides you a simple way to manage distributed applications operations. The cluster consists of several Tarantool instances acting in concert. Cartridge does not care about how the instances start, it only cares about the configuration of already running processes.

Cartridge automates vshard and replication configuration, simplifies custom configuration and administrative tasks.

Functions

cfg (opts, box_opts) Initialize the cartridge module.
is_healthy () Check cluster health.

Tables

VshardGroup Vshard storage group configuration.

Local Functions

bootstrap (roles, uuids, labels, vshard_group) Bootstrap a new cluster.

Cluster administration

ServerInfo Instance general information.
ReplicasetInfo Replicaset general information.
admin_get_servers ([uuid]) Get servers list.
admin_get_replicasets ([uuid]) Get replicasets list.
admin_probe_server (uri) Discover an instance.
admin_join_server (args) Join an instance to the cluster.
admin_edit_server (args) Edit an instance.
admin_expel_server (uuid) Expel an instance.
admin_enable_servers (uuids) Enable nodes after they were disabled.
admin_disable_servers (uuids) Temporarily diable nodes.
admin_edit_replicaset (args) Edit replicaset parameters.
admin_get_failover () Get current failover state.
admin_enable_failover () Enable failover.
admin_disable_failover () Disable failover.

Clusterwide configuration

config_get_readonly ([section_name]) Get a read-only view on the clusterwide configuration.
config_get_deepcopy ([section_name]) Get a read-write deep copy of the clusterwide configuration.
config_patch_clusterwide (patch) Edit the clusterwide configuration.

Inter-role interaction

service_get (module_name) Get a module from registry.
service_set (module_name, instance) Put a module into registry or drop it.

Cross-instance calls

rpc_call (role_name, fn_name[, args[, opts]]) Perform a remote procedure call.


Functions

cfg (opts, box_opts)
Initialize the cartridge module.

After this call, you can operate the instance via Tarantool console. Notice that this call does not initialize the database - box.cfg is not called yet. Do not try to call box.cfg yourself, the cartridge will do it when it is time.

Both cartridge.cfg and box.cfg options can be configured with command-line arguments or environment variables.

Parameters:

  • opts Available options are:
    • workdir optional string a directory where all data will be stored: snapshots, wal logs and cartridge config file. (default: ".", overridden by env TARANTOOL_WORKDIR, args --workdir)
    • advertise_uri optional string either "<HOST>:<PORT>" or "<HOST>:" or "<PORT>". Used by other instances to connect to the current one.

      When <HOST> isn't specified, it's detected as the only non-local IP address. If there is more than one IP address available - defaults to "localhost".

      When <PORT> isn't specified, it's derived as follows: If the TARANTOOL_INSTANCE_NAME has numeric suffix _<N>, then <PORT> = 3300+<N>. Otherwise default <PORT> = 3301 is used.

    • cluster_cookie optional string secret used to separate unrelated applications, which prevents them from seeing each other during broadcasts. Also used for encrypting internal communication. (default: "secret-cluster-cookie", overridden by env TARANTOOL_CLUSTER_COOKIE, args --cluster-cookie)
    • bucket_count optional number bucket count for vshard cluster. See vshard doc for more details. (default: 30000, overridden by env TARANTOOL_BUCKET_COUNT, args --bucket-count)
    • vshard_groups optional {[string]=VshardGroupParams,...} vshard storage groups, table keys used as names
    • http_enabled optional boolean whether http server should be started (default: true, overridden by env TARANTOOL_HTTP_ENABLED, args --http-enabled)
    • http_port string or number port to open administrative UI and API on (default: 8081, derived from TARANTOOL_INSTANCE_NAME, overridden by env TARANTOOL_HTTP_PORT, args --http-port)
    • alias optional string human-readable instance name that will be available in administrative UI (default: argparse instance name, overridden by env TARANTOOL_ALIAS, args --alias)
    • roles table list of user-defined roles that will be available to enable on the instance_uuid
    • auth_enabled optional boolean toggle authentication in administrative UI and API (default: false)
    • auth_backend_name optional string user-provided set of callbacks related to authentication
    • console_sock optional string Socket to start console listening on. (default: nil, overridden by env TARANTOOL_CONSOLE_SOCK, args --console-sock)
  • box_opts optional table tarantool extra box.cfg options (e. g. memtx_memory), that may require additional tuning

Returns:

    true

Or

  1. nil
  2. table Error description
is_healthy ()
Check cluster health. It is healthy if all instances are healthy.

Returns:

    boolean

Tables

VshardGroup
Vshard storage group configuration.

Every vshard storage must be assigned to a group.

Fields:

  • bucket_count number Bucket count for the storage group.

Local Functions

bootstrap (roles, uuids, labels, vshard_group)
Bootstrap a new cluster.

It is bootstrapped with the only (current) instance. Later, you can join other instances using cartridge.admin.

Parameters:

  • roles {string,...} roles to be enabled on the current instance
  • uuids
    • instance_uuid optional string bootstrap current instance with specified uuid
    • replicaset_uuid optional string assign replicaset uuid to the current instance
  • labels {[string]=string,...} labels for the current instance
  • vshard_group string which vshard storage group to join to (for multi-group configuration only)

Cluster administration

ServerInfo
Instance general information.

Fields:

  • alias string Human-readable instance name.
  • uri string
  • uuid string
  • disabled boolean
  • status string Instance health.
  • message string Auxilary health status.
  • replicaset ReplicasetInfo Circular reference to a replicaset.
  • priority number Leadership priority for automatic failover.
ReplicasetInfo
Replicaset general information.

Fields:

  • uuid string The replicaset UUID.
  • roles {string,...} Roles enabled on the replicaset.
  • status string Replicaset health.
  • master ServerInfo Replicaset leader according to configuration.
  • active_master ServerInfo Active leader.
  • weight number Vshard replicaset weight. Matters only if vshard-storage role is enabled.
  • vshard_group string Name of vshard group the replicaset belongs to.
  • all_rw boolean A flag indicating that all servers in the replicaset should be read-write.
  • alias string Human-readable replicaset name.
  • servers {ServerInfo,...} Circular reference to all instances in the replicaset.
admin_get_servers ([uuid])
Get servers list. Optionally filter out the server with given uuid.

Parameters:

Returns:

    {ServerInfo,...}
admin_get_replicasets ([uuid])
Get replicasets list. Optionally filter out the replicaset with given uuid.

Parameters:

Returns:

    {ReplicasetInfo,...}
admin_probe_server (uri)
Discover an instance.

Parameters:

admin_join_server (args)
Join an instance to the cluster.

Parameters:

Returns:

    boolean true

Or

  1. nil
  2. table Error description
admin_edit_server (args)
Edit an instance.

Parameters:

Returns:

    boolean true

Or

  1. nil
  2. table Error description
admin_expel_server (uuid)
Expel an instance. Forever.

Parameters:

Returns:

    boolean true

Or

  1. nil
  2. table Error description
admin_enable_servers (uuids)
Enable nodes after they were disabled.

Parameters:

Returns:

    {ServerInfo,...}

Or

  1. nil
  2. table Error description
admin_disable_servers (uuids)
Temporarily diable nodes.

Parameters:

Returns:

    {ServerInfo,...}

Or

  1. nil
  2. table Error description
admin_edit_replicaset (args)
Edit replicaset parameters.

Parameters:

Returns:

    boolean true

Or

  1. nil
  2. table Error description
admin_get_failover ()
Get current failover state.
admin_enable_failover ()
Enable failover.
admin_disable_failover ()
Disable failover.

Clusterwide configuration

config_get_readonly ([section_name])
Get a read-only view on the clusterwide configuration.

Returns either conf[section_name] or entire conf. Any attempt to modify the section or its children will raise an error.

Parameters:

  • section_name string (optional)

Returns:

    table
config_get_deepcopy ([section_name])
Get a read-write deep copy of the clusterwide configuration.

Returns either conf[section_name] or entire conf. Changing it has no effect unless it's used to patch clusterwide configuration.

Parameters:

  • section_name string (optional)

Returns:

    table
config_patch_clusterwide (patch)
Edit the clusterwide configuration. Top-level keys are merged with the current configuration. To remove a top-level section, use patch_clusterwide{key = box.NULL}.

The function uses a two-phase commit algorithm with the following steps:

I. Patches the current configuration.

II. Validates topology on the current server.

III. Executes the preparation phase (prepare_2pc) on every server excluding the following servers: expelled, disabled, and servers being joined during this call.

IV. If any server reports an error, executes the abort phase (abort_2pc). All servers prepared so far are rolled back and unlocked.

V. Performs the commit phase (commit_2pc). In case the phase fails, an automatic rollback is impossible, the cluster should be repaired manually.

Parameters:

  • patch table A patch to be applied.

Returns:

    boolean true

Or

  1. nil
  2. table Error description

Inter-role interaction

service_get (module_name)
Get a module from registry.

Parameters:

Returns:

    nil

Or

    table instance
service_set (module_name, instance)
Put a module into registry or drop it. This function typically doesn't need to be called explicitly, the cluster automatically sets all the initialized roles.

Parameters:

Returns:

    nil

Cross-instance calls

rpc_call (role_name, fn_name[, args[, opts]])
Perform a remote procedure call. Find a suitable healthy instance with an enabled role and perform a net.box conn:call on it.

Parameters:

  • role_name string
  • fn_name string
  • args table (optional)
  • opts
    • prefer_local optional boolean Don't perform a remote call if possible. (default: true)
    • leader_only optional boolean Perform a call only on the replica set leaders. (default: false)
    • remote_only (deprecated) Use prefer_local instead.
    • timeout passed to net.box conn:call options.
    • buffer passed to net.box conn:call options.

Returns:

    conn:call() result

Or

  1. nil
  2. table Error description
generated by LDoc 1.4.6 Last updated 2019-08-29 23:56:02