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 the cluster health.

Tables

VshardGroup Vshard storage group configuration.

Global functions

_G.cartridge_get_schema () Get clusterwide DDL schema.
_G.cartridge_set_schema (schema) Apply clusterwide DDL schema.

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_enable_servers (uuids) Enable nodes after they were disabled.
admin_disable_servers (uuids) Temporarily diable nodes.
admin_get_failover () Get current failover state.
admin_enable_failover () Enable failover.
admin_disable_failover () Disable failover.

Managing cluster topology

admin_edit_topology (args) Edit cluster topology.
EditReplicasetParams Replicatets modifications.
EditServerParams Servers modifications.
JoinServerParams Parameters required for joining a new server.

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.
rpc_get_candidates (role_name[, opts]) List instances suitable for performing a remote call.

Authentication and authorization

http_authorize_request (request) Authorize an HTTP request.
http_render_response (response) Render HTTP response.
http_get_username () Get username for the current HTTP session.

Deprecated functions

admin_edit_replicaset (args) Edit replicaset parameters (deprecated).
admin_edit_server (args) Edit an instance (deprecated).
admin_join_server (args) Join an instance to the cluster (deprecated).
admin_expel_server (uuid) Expel an instance (deprecated).


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 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

  1. nil
  2. 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

  1. nil
  2. 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 (in seconds), obtained from the membership module (SWIM protocol). Positive values mean remote clock are ahead of local, and vice versa.
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

  1. nil
  2. table Error description
admin_get_replicasets ([uuid])
Get replicasets list. Optionally filter out the replicaset with given uuid.

Parameters:

Returns:

    {ReplicasetInfo,...}

Or

  1. nil
  2. 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

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

Parameters:

Returns:

    {ServerInfo,...}

Or

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

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:

I. Patches the current configuration.

II. 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

  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. When the role is enabled locally and current instance is healthy the remote netbox call is substituted with a local Lua function call. When the option is disabled it never tries to perform call locally and always uses netbox 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.

Returns:

    conn:call() result

Or

  1. nil
  2. 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

  1. nil
  2. 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

  1. nil
  2. 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

  1. nil
  2. 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

  1. nil
  2. table Error description
generated by LDoc 1.4.6 Last updated 2020-01-15 15:54:21