Module cartridge

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.Can be set only once, before the first run of Cartridge application, and can’t bechanged after that.(default: 30000, overridden byenv TARANTOOL_BUCKET_COUNT ,args --bucket-count )
  • rebalancer_mode: (optional number) rebalancer_mode for vshard cluster. See vshard doc for more details.(default: «auto», overridden byenv TARANTOOL_REBALANCER_MODE ,args --rebalancer-mode )
  • vshard_groups: (optional table) vshard storage groups.``{group_name = VshardGroup, …}`` , {'group1', 'group2', ...} or``{group1 = VshardGroup, „group2“, …}`` .default group name: default
  • 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.

Hot-reload could be forbidden in runtime with forbid_reload function.

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

Or

(nil)

(table) Error description

VshardGroup

Vshard storage group configuration.

Every vshard storage must be assigned to a group.

Fields:

• bucket_count: (number) Bucket count for the storage group.

_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

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

ServerInfo

Instance general information.

Fields:

• alias: (string) Human-readable instance name.
• uri: (string)
• uuid: (string)
• disabled: (boolean)
• electable: (boolean)
• rebalancer: (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.
• rebalancer: (boolean) Is rebalancer enabled on this replicaset.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_get_uris (filter)

Get servers uri list.

Parameters:

• filter: (optional function) function(x: ServerInfo) -> boolean

Returns:

table {uri1, uri2, …}

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 disable nodes.

Parameters:

• uuids: ({string,…})

Returns:

({ServerInfo,…})

Or

(nil)

(table) Error description

admin_restart_replication (…)

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

FailoverParams

Failover parameters.

(Added in v2.0.2-2)

Fields:

• mode: (string) Supported modes are «disabled», «eventual», «stateful» or «raft»
• 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)
• leader_autoreturn: (boolean) (added in v2.7.7)If enabled, then switched leader will return after ` autoreturn_delay `(default: false)
• autoreturn_delay: (number) (added in v2.7.7)Time (in seconds) until failover try to return leader to the first nodein ` failover_priority `(default: 300)
• check_cookie_hash: (boolean) (added in v2.7.8)If enabled, then check that nobody else uses this stateboard(default: true)

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)
  • leader_autoreturn: (optional boolean) (added in v2.7.7)
  • autoreturn_delay: (optional number) (added in v2.7.7)
  • check_cookie_hash: (optional boolean) (added in v2.7.8)

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)
  • skip_error_on_change: (optional boolean) Skip etcd error if vclockkeeper was changed between calls (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)

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)
• rebalancer: (optional boolean)
• 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)
• electable: (optional boolean)
• rebalancer: (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)

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

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)

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)
  • labels: (optional table) Filter instances that have the specified labels. Adding labels is possible via theedit_topology method or via graphql.Example: rpc.call(„role“, „func“, {}, { labels = { [„msk“] = „dc“ } })
  • 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.
  • is_async: 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 candidates suitable for performing a remote call. Candidates are deduced from a local config and membership, which may differ from replica to replica (e.g. during patch_clusterwide ). It may produce invalid candidates.

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)
  • labels: (optional table) Filter instances that have the specified labels. Adding labels is possible via theedit_topology method or via graphqlExample: rpc.get_candidates(„role“, { labels = {[„msk“] = „dc“} })

Returns:

({string,…}) URIs

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)

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