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 callbox.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 theTARANTOOL_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 envTARANTOOL_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
)
- workdir
optional string
a directory where all data will be stored: snapshots, wal logs and cartridge config file.
(default: ".", overridden by
env
- 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
- opts Available options are:
- 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
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:
- uuid string (optional)
Returns:
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:
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:
Or
- nil
- table Error description
- admin_disable_servers (uuids)
-
Temporarily diable nodes.
Parameters:
- uuids {string,...}
Returns:
Or
- nil
- 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:
- 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:
- 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 entireconf
. Any attempt to modify the section or its children will raise an error.Parameters:
- section_name string (optional)
Returns:
- config_get_deepcopy ([section_name])
-
Get a read-write deep copy of the clusterwide configuration.
Returns either
conf[section_name]
or entireconf
. Changing it has no effect unless it's used to patch clusterwide configuration.Parameters:
- section_name string (optional)
Returns:
- 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:
- patch table
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:
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 withopts.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()
resultOr
- 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:
- 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
- args
- 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
- args
- 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
- labels optional {[string]=string,...}
- vshard_group optional string
- replicaset_alias optional string
- replicaset_weight optional number
Returns:
-
boolean
true
Or
- nil
- table Error description
- args
- 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