Tarantool Cartridge / Table of contents / Module cartridge
Tarantool Cartridge / Table of contents / Module cartridge

Module cartridge

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.

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: 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 byenv 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, whichprevents them from seeing each other during broadcasts.Also used as admin password in HTTP and binary connections and forencrypting internal communications.Allowed symbols are [a-zA-Z0-9_.~-] .(default: «secret-cluster-cookie», overridden byenv TARANTOOL_CLUSTER_COOKIE ,args --cluster-cookie )
    • bucket_count: (optional number) bucket count for vshard cluster. See vshard doc for more details.(default: 30000, overridden byenv TARANTOOL_BUCKET_COUNT ,args --bucket-count )
    • vshard_groups: (optional {[string]=VshardGroup,…}) vshard storage groups, table keys used as names
    • http_enabled: (optional boolean) whether http server should be started(default: true, overridden byenv 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 byenv 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 byenv TARANTOOL_ALIAS,args –alias)
    • roles: (table) list of user-defined roles that will be availableto 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 byenv TARANTOOL_CONSOLE_SOCK ,args --console-sock )
    • webui_blacklist: (optional {string,…}) List of pages to be hidden in WebUI.(Added in v2.0.1-54, default: {} )
    • upgrade_schema: (optional boolean) Run schema upgrade on the leader instance.(Added in v2.0.2-3,default: false , overridden byenv TARANTOOL_UPGRADE_SCHEMA args --upgrade-schema )
  • box_opts: (optional table) tarantool extra box.cfg options (e.g. memtx_memory),that may require additional tuning

Returns:

true

Or

(nil)

(table) Error description

is_healthy ()

Check the cluster health. It is healthy if all instances are healthy.

The function is designed mostly for testing purposes.

Returns:

(boolean) true / false

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.

Global functions

_G.cartridge_get_schema ()

Get clusterwide DDL schema.

(Added in v1.2.0-28)

Returns:

(string) Schema in YAML format

Or

(nil)

(table) Error description

_G.cartridge_set_schema (schema)

Apply clusterwide DDL schema.

(Added in v1.2.0-28)

Parameters:

  • schema: (string) in YAML format

Returns:

(string) The same new schema

Or

(nil)

(table) Error description

Clusterwide DDL schema

get_schema ()

Get clusterwide DDL schema. It’s like _G.cartridge_get_schema, but isn’t non-global variable.

(Added in v2.0.1-54)

Returns:

(string) Schema in YAML format

Or

(nil)

(table) Error description

set_schema (schema)

Apply clusterwide DDL schema. It’s like _G.cartridge_set_schema, but isn’t non-global variable.

(Added in v2.0.1-54)

Parameters:

  • schema: (string) in YAML format

Returns:

(string) The same new schema

Or

(nil)

(table) Error description

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.
  • clock_delta: (number) Difference between remote clock and the current one (inseconds), obtained from the membership module (SWIM protocol).Positive values mean remote clock are ahead of local, and viceversa.

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 the given uuid.

Parameters:

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

admin_get_replicasets ([uuid])

Get replicasets list. Optionally filter out the replicaset with given uuid.

Parameters:

Returns:

({ReplicasetInfo,…})

Or

(nil)

(table) Error description

admin_probe_server (uri)

Discover an instance.

Parameters:

admin_enable_servers (uuids)

Enable nodes after they were disabled.

Parameters:

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

admin_disable_servers (uuids)

Temporarily diable nodes.

Parameters:

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

admin_bootstrap_vshard ()

Call vshard.router.bootstrap() . This function distributes all buckets across the replica sets.

Returns:

(boolean) true

Or

(nil)

(table) Error description

Automatic failover management

FailoverParams

Failover parameters.

(Added in v2.0.2-2)

Fields:

  • mode: (string) Supported modes are «disabled», «eventual» and «stateful»
  • state_provider: (optional string) Supported state providers are «tarantool» and «etcd2».
  • tarantool_params: (added in v2.0.2-2)
  • etcd2_params: (added in v2.1.2-26)
    • endpoints: (optional table) URIs that are used to discover and to access etcd cluster instances.(default: {'http://localhost:2379', 'http://localhost:4001'} )
    • username: (optional string) (default: «»)
    • password: (optional string) (default: «»)
  • lock_delay: (optional number) Timeout (in seconds), determines lock’s time-to-live (default: 10)

failover_get_params ()

Get failover configuration.

(Added in v2.0.2-2)

Returns:

(FailoverParams)

failover_set_params (opts)

Configure automatic failover.

(Added in v2.0.2-2)

Parameters:

  • opts:
    • mode: (optional string)
    • state_provider: (optional string)
    • tarantool_params: (optional table)
    • etcd2_params: (optional table) (added in v2.1.2-26)

Returns:

(boolean) true if config applied successfully

Or

(nil)

(table) Error description

failover_promote (replicaset_uuid[, opts])

Promote leaders in replicasets.

Parameters:

  • replicaset_uuid: (table) ] = leader_uuid }
  • opts:
    • force_inconsistency: (optional boolean) (default: false)

Returns:

(boolean) true On success

Or

(nil)

(table) Error description

admin_get_failover ()

Get current failover state.

(Deprecated since v2.0.2-2)

admin_enable_failover ()

Enable failover. (Deprecated since v2.0.1-95 in favor of cartridge.failover_set_params)

admin_disable_failover ()

Disable failover. (Deprecated since v2.0.1-95 in favor of cartridge.failover_set_params)

Managing cluster topology

admin_edit_topology (args)

Edit cluster topology. This function can be used for:

  • bootstrapping cluster from scratch
  • joining a server to an existing replicaset
  • creating new replicaset with one or more servers
  • editing uri/labels of servers
  • disabling and expelling servers

(Added in v1.0.0-17)

Parameters:

EditReplicasetParams

Replicatets modifications.

Fields:

EditServerParams

Servers modifications.

Fields:

  • uri: (optional string)
  • uuid: (string)
  • labels: (optional table)
  • disabled: (optional boolean)
  • expelled: (optional boolean) Expelling an instance is permanent and can’t be undone.It’s suitable for situations when the hardware is destroyed,snapshots are lost and there is no hope to bring it back to life.

JoinServerParams

Parameters required for joining a new server.

Fields:

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:

  1. Patches the current configuration.
  2. Validates topology on the current server.

III. Executes the preparation phase ( prepare_2pc ) on every server excluding expelled and disabled servers.

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:

Returns:

(boolean) true

Or

(nil)

(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 ]( https://tarantool.io/en/doc/latest/reference/reference_lua/net_box/#net-box-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. When the role is enabledlocally and current instance is healthy the remote netbox call issubstituted with a local Lua function call. When the option isdisabled it never tries to perform call locally and always usesnetbox connection, even to connect self.(default: true)
    • leader_only: (optional boolean) Perform a call only on the replica set leaders.(default: false)
    • uri: (optional string) Force a call to be performed on this particular uri.Disregards member status and opts.prefer_local .Conflicts with opts.leader_only = true .(added in v1.2.0-63)
    • remote_only: (deprecated) Use prefer_local instead.
    • timeout: passed to net.box conn:call options.
    • buffer: passed to net.box conn:call options.
    • on_push: passed to net.box conn:call options.
    • on_push_ctx: passed to net.box conn:call options.

Returns:

conn:call() result

Or

(nil)

(table) Error description

rpc_get_candidates (role_name[, opts])

List instances suitable for performing a remote call.

Parameters:

  • role_name: (string)
  • opts:
    • leader_only: (optional boolean) Filter instances which are leaders now.(default: false)
    • healthy_only: (optional boolean) Filter instances which have membership status healthy.(added in v1.1.0-11, default: true)

Returns:

({string,…}) URIs

Authentication and authorization

http_authorize_request (request)

Authorize an HTTP request.

Get username from cookies or basic HTTP authentication.

(Added in v1.1.0-4)

Parameters:

Returns:

(boolean) Access granted

http_render_response (response)

Render HTTP response.

Inject set-cookie headers into response in order to renew or reset the cookie.

(Added in v1.1.0-4)

Parameters:

Returns:

(table) The same response with cookies injected

http_get_username ()

Get username for the current HTTP session.

(Added in v1.1.0-4)

Returns:

(string or nil)

Deprecated functions

admin_edit_replicaset (args)

Edit replicaset parameters (deprecated).

(Deprecated since v1.0.0-17 in favor of cartridge.admin_edit_topology)

Parameters:

Returns:

(boolean) true

Or

(nil)

(table) Error description

admin_edit_server (args)

Edit an instance (deprecated).

(Deprecated since v1.0.0-17 in favor of cartridge.admin_edit_topology)

Parameters:

Returns:

(boolean) true

Or

(nil)

(table) Error description

admin_join_server (args)

Join an instance to the cluster (deprecated).

(Deprecated since v1.0.0-17 in favor of cartridge.admin_edit_topology)

Parameters:

Returns:

(boolean) true

Or

(nil)

(table) Error description

admin_expel_server (uuid)

Expel an instance (deprecated). Forever.

(Deprecated since v1.0.0-17 in favor of cartridge.admin_edit_topology)

Parameters:

Returns:

(boolean) true

Or

(nil)

(table) Error description