# 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` )

  - swim_broadcast: (optional boolean) Announce own advertise_uri over UDP broadcast.Cartridge health-checks are governed by SWIM protocol. To simplifyinstances discovery on start it can UDP broadcast all networksknown from getifaddrs() C call. The broadcast is sent to severalports: default 3301, the <PORT> from the advertise_uri option,and its neighbours <PORT>+1 and <PORT>-1.(Added in v2.3.0-23,default: true, overridden byenv TARANTOOL_SWIM_BROADCAST,args –swim-broadcast)

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

  - webui_enabled: (optional boolean) whether WebUI and corresponding API (HTTP + GraphQL) should beinitialized. Ignored if `http_enabled` is `false` . Doesn’taffect `auth_enabled` .(Added in v2.4.0-38,default: true, overridden byenv `TARANTOOL_WEBUI_ENABLED` ,args `--webui-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)

  - http_host: (optional string) host to open administrative UI and API on(Added in v2.4.0-42,default: “0.0.0.0”, overridden byenv `TARANTOOL_HTTP_HOST` ,args `--http-host` )

  - webui_prefix: (optional string) modify WebUI and cartridge HTTP API routes(Added in v2.6.0-18,default: “”, overridden byenv `TARANTOOL_WEBUI_PREFIX` ,args `--webui-prefix` )

  - webui_enforce_root_redirect: (optional boolean) respond on GET / with a redirect to <WEBUI_PREFIX>/admin.(Added in v2.6.0-18,default: true, overridden byenv TARANTOOL_WEBUI_ENFORCE_ROOT_REDIRECT,args –webui-enforce-root-redirect)

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

  - roles_reload_allowed: (optional boolean) Allow calling cartridge.reload_roles.(Added in v2.3.0-73, default: `false` )

  - upload_prefix: (optional string) Temporary directory used for saving files during clusterwideconfig upload. If relative path is specified, it’s evaluatedrelative to the `workdir` .(Added in v2.4.0-43,default: `/tmp` , overridden byenv `TARANTOOL_UPLOAD_PREFIX` ,args `--upload-prefix` )

- 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

### reload_roles ()

Perform hot-reload of cartridge roles code.

This is an experimental feature, it’s only allowed if the application enables it explicitly: `cartridge.cfg({roles_reload_allowed = true})` .

Reloading starts by stopping all roles and restoring the initial state. It’s supposed that a role cleans up the global state when stopped, but even if it doesn’t, cartridge kills all fibers and removes global variables and HTTP routes.

All Lua modules that were loaded during cartridge.cfg are unloaded, including supplementary modules required by a role. Modules, loaded before cartridge.cfg aren’t affected.

Instance performs roles reload in a dedicated state `ReloadingRoles` . If reload fails, the instance enters the `ReloadError` state, which can later be retried. Otherwise, if reload succeeds, instance proceeds to the `ConfiguringRoles` state and initializes them as usual with `validate_config()` , `init()` , and `apply_config()` callbacks.

Returns:

(boolean) 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 a 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 a 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.

- zone: (string)

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

- uuid: (string) (optional)

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

### admin_get_replicasets ([uuid])

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

Parameters:

- uuid: (string) (optional)

Returns:

({ReplicasetInfo,…})

Or

(nil)

(table) Error description

### admin_probe_server (uri)

Discover an instance.

Parameters:

- uri: (string)

### admin_enable_servers (uuids)

Enable nodes after they were disabled.

Parameters:

- uuids: ({string,…})

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

### admin_disable_servers (uuids)

Temporarily diable nodes.

Parameters:

- uuids: ({string,…})

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

### admin_bootstrap_vshard (…)

Restart replication on specified instances.

(added in v2.6.0-43)

Parameters:

- …: ({string,) } uuids

Returns:

(boolean) true

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

- failover_timeout: (number) (added in v2.3.0-52)Timeout (in seconds), used by membership tomark `suspect` members as `dead` (default: 20)

- tarantool_params: (added in v2.0.2-2)

  - uri: (string)

  - password: (string)

- etcd2_params: (added in v2.1.2-26)

  - prefix: (string) Prefix used for etcd keys: <prefix>/lock and`<prefix>/leaders`

  - lock_delay: (optional number) Timeout (in seconds), determines lock’s time-to-live (default: 10)

  - 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: “”)

- fencing_enabled: (boolean) (added in v2.3.0-57)Abandon leadership when both the state provider quorum and atleast one replica are lost (suitable in stateful mode only,default: false)

- fencing_timeout: (number) (added in v2.3.0-57)Time (in seconds) to actuate fencing after the check fails(default: 10)

- fencing_pause: (number) (added in v2.3.0-57)The period (in seconds) of performing the check(default: 2)

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

  - failover_timeout: (optional number) (added in v2.3.0-52)

  - tarantool_params: (optional table)

  - etcd2_params: (optional table) (added in v2.1.2-26)

  - fencing_enabled: (optional boolean) (added in v2.3.0-57)

  - fencing_timeout: (optional number) (added in v2.3.0-57)

  - fencing_pause: (optional number) (added in v2.3.0-57)

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:

- args:

  - servers: (optional {EditServerParams,..})

  - replicasets: (optional {EditReplicasetParams,..})

### EditReplicasetParams

Replicatets modifications.

Fields:

- uuid: (optional string)

- alias: (optional string)

- roles: (optional {string,…})

- all_rw: (optional boolean)

- weight: (optional number)

- failover_priority: (optional {string,…}) array of uuids specifying servers failover priority

- vshard_group: (optional string)

- join_servers: (optional {JoinServerParams,…})

### EditServerParams

Servers modifications.

Fields:

- uri: (optional string)

- uuid: (string)

- zone: (optional 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:

- uri: (string)

- uuid: (optional string)

- zone: (optional string) (Added in v2.4.0-14)

- labels: (optional table)

## 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 executes following steps:

1. Patches the current configuration.

2. Validates topology on the current server.

III. Executes two-phase commit on all servers in the cluster excluding expelled and disabled ones.

Parameters:

- patch: (table)

Returns:

(boolean) true

Or

(nil)

(table) Error description

### config_force_reapply (uuids)

Forcefully apply config to the given instances.

In particular:

- Abort two-phase commit (remove `config.prepare` lock)

- Upload the active config from the current instance.

- Apply it (reconfigure all roles)

(Added in v2.3.0-68)

Parameters:

- uuids: ({string,…})

Returns:

(boolean) true

Or

(nil)

(table) Error description

## Inter-role interaction

### service_get (module_name)

Get a module from registry.

Parameters:

- module_name: (string)

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:

- module_name: (string)

- instance: (nil or table)

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. `rpc.call()` can only be used for functions defined in role return table unlike `net.box` `conn:call()` , which is used for global functions as well.

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

### Usage:

    -- myrole.lua
    return {
        role_name = 'myrole',
        add = function(a, b) return a + b end,
    }

    -- call it as follows:
    cartridge.rpc_call('myrole', 'add', {2, 2}) -- returns 4

### 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) The member is considered healthy ifit reports either `ConfiguringRoles` or `RolesConfigured` stateand its SWIM status is either `alive` or `suspect` (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:

- request: (table)

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:

- response: (table)

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:

- args:

  - uuid: (string)

  - alias: (string)

  - roles: (optional {string,…})

  - master: (optional {string,…}) Failover order

  - weight: (optional number)

  - vshard_group: (optional string)

  - all_rw: (optional boolean)

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:

- args:

  - uuid: (string)

  - uri: (optional string)

  - labels: (optional {[string]=string,…})

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:

- args:

  - uri: (string)

  - instance_uuid: (optional string)

  - replicaset_uuid: (optional string)

  - roles: (optional {string,…})

  - timeout: (optional number)

  - zone: (optional string) (Added in v2.4.0-14)

  - labels: (optional {[string]=string,…})

  - vshard_group: (optional string)

  - replicaset_alias: (optional string)

  - replicaset_weight: (optional number)

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:

- uuid: (string)

Returns:

(boolean) true

Or

(nil)

(table) Error description