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 cluster health. |
Tables
VshardGroup | Vshard storage group configuration. |
Local Functions
bootstrap (roles, uuids, labels, vshard_group) | Bootstrap a new cluster. |
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_join_server (args) | Join an instance to the cluster. |
admin_edit_server (args) | Edit an instance. |
admin_expel_server (uuid) | Expel an instance. |
admin_enable_servers (uuids) | Enable nodes after they were disabled. |
admin_disable_servers (uuids) | Temporarily diable nodes. |
admin_edit_replicaset (args) | Edit replicaset parameters. |
admin_get_failover () | Get current failover state. |
admin_enable_failover () | Enable failover. |
admin_disable_failover () | Disable failover. |
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. |
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 cluster health.
It is healthy if all instances are healthy.
Returns:
-
boolean
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.
Local Functions
- bootstrap (roles, uuids, labels, vshard_group)
-
Bootstrap a new cluster.
It is bootstrapped with the only (current) instance. Later, you can join other instances using cartridge.admin.
Parameters:
- roles {string,...} roles to be enabled on the current instance
- uuids
- labels {[string]=string,...} labels for the current instance
- vshard_group string which vshard storage group to join to (for multi-group configuration only)
Cluster administration
- ServerInfo
-
Instance general information.
Fields:
- 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 given uuid.
Parameters:
- uuid string (optional)
Returns:
- admin_get_replicasets ([uuid])
-
Get replicasets list.
Optionally filter out the replicaset with given uuid.
Parameters:
- uuid string (optional)
Returns:
- admin_probe_server (uri)
-
Discover an instance.
Parameters:
- uri string
- admin_join_server (args)
-
Join an instance to the cluster.
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_edit_server (args)
-
Edit an instance.
Parameters:
- args
- uuid string
- uri optional string
- labels optional {[string]=string,...}
Returns:
-
boolean
true
Or
- nil
- table Error description
- args
- admin_expel_server (uuid)
-
Expel an instance.
Forever.
Parameters:
- uuid string
Returns:
-
boolean
true
Or
- nil
- table Error description
- 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_edit_replicaset (args)
-
Edit replicaset parameters.
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_get_failover ()
- Get current failover state.
- admin_enable_failover ()
- Enable failover.
- admin_disable_failover ()
- Disable failover.
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 the following servers: expelled, disabled, and servers being joined during this call.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 A patch to be applied.
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. (default: true)
- leader_only optional boolean Perform a call only on the replica set leaders. (default: false)
- 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