.. _cartridge:

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


.. _cartridge.cfg:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 :ref:`cartridge.cfg <cartridge.cfg>` and  ``box.cfg``  options can be configured with
command-line arguments or environment variables.



**Parameters:**

- *opts:* Available options are:

  - *workdir:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_ 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) host to open administrative UI and API on(**Added** in v2.4.0-42default: "0.0.0.0", overridden byenv  ``TARANTOOL_HTTP_HOST`` ,args  ``--http-host`` )  
  - *alias:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) human-readable instance name that will be available in administrative UI(default: argparse instance name, overridden byenv `TARANTOOL_ALIAS`,args `--alias`)  
  - *roles:* (`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) user-provided set of callbacks related to authentication  
  - *console_sock:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Socket to start console listening on.(default: nil, overridden byenv  ``TARANTOOL_CONSOLE_SOCK`` ,args  ``--console-sock`` )  
  - *webui_blacklist:* (optional `{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 :ref:`cartridge.reload_roles <cartridge.reload_roles>`.(**Added** in v2.3.0-73, default:  ``false`` )  
  - *upload_prefix:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_) tarantool extra box.cfg options (e.g. memtx_memory),that may require additional tuning  

**Returns**:

true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.reload_roles:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 :ref:`cartridge.cfg <cartridge.cfg>` are unloaded,
including supplementary modules required by a role. Modules, loaded
before :ref:`cartridge.cfg <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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.is_healthy:

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


.. _cartridge.VshardGroup:

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


.. _cartridge._G.cartridge_get_schema:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_G.cartridge_get_schema ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get clusterwide DDL schema. 

(**Added** in v1.2.0-28)



**Returns**:

(`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Schema in YAML format


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge._G.cartridge_set_schema:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_G.cartridge_set_schema (schema)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Apply clusterwide DDL schema. 

(**Added** in v1.2.0-28)


**Parameters:**

- *schema:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) in YAML format  

**Returns**:

(`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) The same new schema


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


-------------------------------------------------------------------------------
Clusterwide DDL schema 
-------------------------------------------------------------------------------


.. _cartridge.get_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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Schema in YAML format


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.set_schema:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) in YAML format  

**Returns**:

(`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) The same new schema


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


-------------------------------------------------------------------------------
Cluster administration 
-------------------------------------------------------------------------------


.. _cartridge.ServerInfo:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ServerInfo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Instance general information.


**Fields:**

- *alias:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Human-readable instance name.  
- *uri:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *disabled:* (**boolean**)   
- *status:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Instance health.  
- *message:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Auxilary health status.  
- *replicaset:* (`ReplicasetInfo <cartridge.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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   


.. _cartridge.ReplicasetInfo:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ReplicasetInfo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Replicaset general information.


**Fields:**

- *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) The replicaset UUID.  
- *roles:* (`{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Roles enabled on the replicaset.  
- *status:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Replicaset health.  
- *master:* (`ServerInfo <cartridge.ServerInfo_>`_) Replicaset leader according to configuration.  
- *active_master:* (`ServerInfo <cartridge.ServerInfo_>`_) Active leader.  
- *weight:* (**number**) Vshard replicaset weight.Matters only if vshard-storage role is enabled.  
- *vshard_group:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Human-readable replicaset name.  
- *servers:* (`{ServerInfo,...} <cartridge.ServerInfo_>`_) Circular reference to all instances in the replicaset.  


.. _cartridge.admin_get_servers:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_get_servers ([uuid])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get servers list. 
Optionally filter out the server with the given uuid.


**Parameters:**

- *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)  (optional) 

**Returns**:

(`{ServerInfo,...} <cartridge.ServerInfo_>`_) 


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_get_replicasets:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_get_replicasets ([uuid])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


**Parameters:**

- *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)  (optional) 

**Returns**:

(`{ReplicasetInfo,...} <cartridge.ReplicasetInfo_>`_) 


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_probe_server:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_probe_server (uri)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Discover an instance.


**Parameters:**

- *uri:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   


.. _cartridge.admin_enable_servers:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_enable_servers (uuids)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enable nodes after they were disabled.


**Parameters:**

- *uuids:* (`{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(`{ServerInfo,...} <cartridge.ServerInfo_>`_) 


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_disable_servers:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_disable_servers (uuids)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Temporarily diable nodes.


**Parameters:**

- *uuids:* (`{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(`{ServerInfo,...} <cartridge.ServerInfo_>`_) 


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_bootstrap_vshard:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_bootstrap_vshard ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Call  ``vshard.router.bootstrap()`` . 
This function distributes all buckets across the replica sets.



**Returns**:

(**boolean**) `true`


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


-------------------------------------------------------------------------------
Automatic failover management 
-------------------------------------------------------------------------------


.. _cartridge.FailoverParams:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FailoverParams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Failover parameters. 

(**Added** in v2.0.2-2)


**Fields:**

- *mode:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Supported modes are "disabled", "eventual" and "stateful"  
- *state_provider:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *password:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

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

  - *prefix:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_) URIs that are used to discover and to access etcd cluster instances.(default:  ``{'http://localhost:2379', 'http://localhost:4001'}`` )  
  - *username:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) (default: "")  
  - *password:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) (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)  


.. _cartridge.failover_get_params:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
failover_get_params ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get failover configuration. 

(**Added** in v2.0.2-2)



**Returns**:

(`FailoverParams <cartridge.FailoverParams_>`_) 


.. _cartridge.failover_set_params:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
failover_set_params (opts)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Configure automatic failover. 

(**Added** in v2.0.2-2)


**Parameters:**

- *opts:* 

  - *mode:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *state_provider:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *failover_timeout:* (optional **number**) (added in v2.3.0-52)  
  - *tarantool_params:* (optional `table <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   
  - *etcd2_params:* (optional `table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) (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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.failover_promote:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
failover_promote (replicaset_uuid[, opts])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Promote leaders in replicasets.


**Parameters:**

- *replicaset_uuid:* (`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) ] = leader_uuid }  
- *opts:* 

  - *force_inconsistency:* (optional **boolean**) (default: **false**)  


**Returns**:

(**boolean**) true On success


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_get_failover:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_get_failover ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get current failover state. 

(**Deprecated** since v2.0.2-2)




.. _cartridge.admin_enable_failover:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_enable_failover ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enable failover. 
(**Deprecated** since v2.0.1-95 in favor of
:ref:`cartridge.failover_set_params <cartridge.failover_set_params>`)




.. _cartridge.admin_disable_failover:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_disable_failover ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disable failover. 
(**Deprecated** since v2.0.1-95 in favor of
:ref:`cartridge.failover_set_params <cartridge.failover_set_params>`)




-------------------------------------------------------------------------------
Managing cluster topology 
-------------------------------------------------------------------------------


.. _cartridge.admin_edit_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,..} <cartridge.EditServerParams_>`_)   
  - *replicasets:* (optional `{EditReplicasetParams,..} <cartridge.EditReplicasetParams_>`_)   



.. _cartridge.EditReplicasetParams:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EditReplicasetParams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Replicatets modifications.


**Fields:**

- *uuid:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *alias:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *roles:* (optional `{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *all_rw:* (optional **boolean**)   
- *weight:* (optional **number**)   
- *failover_priority:* (optional `{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) array of uuids specifying servers failover priority  
- *vshard_group:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *join_servers:* (optional `{JoinServerParams,...} <cartridge.JoinServerParams_>`_)   


.. _cartridge.EditServerParams:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EditServerParams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Servers modifications.


**Fields:**

- *uri:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *zone:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *labels:* (optional `table <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   
- *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.  


.. _cartridge.JoinServerParams:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
JoinServerParams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Parameters required for joining a new server.


**Fields:**

- *uri:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *uuid:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *zone:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) (**Added** in v2.4.0-14)  
- *labels:* (optional `table <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   


-------------------------------------------------------------------------------
Clusterwide configuration 
-------------------------------------------------------------------------------


.. _cartridge.config_get_readonly:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_)  (optional) 

**Returns**:

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) 


.. _cartridge.config_get_deepcopy:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_)  (optional) 

**Returns**:

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) 


.. _cartridge.config_patch_clusterwide:

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

I. Patches the current configuration.

II. 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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   

**Returns**:

(**boolean**) true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.config_force_reapply:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(**boolean**) true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


-------------------------------------------------------------------------------
Inter-role interaction 
-------------------------------------------------------------------------------


.. _cartridge.service_get:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
service_get (module_name)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get a module from registry.


**Parameters:**

- *module_name:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(**nil**) 


**Or**

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) instance


.. _cartridge.service_set:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *instance:* (**nil** or `table <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   

**Returns**:

(**nil**) 


-------------------------------------------------------------------------------
Cross-instance calls 
-------------------------------------------------------------------------------


.. _cartridge.rpc_call:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *fn_name:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *args:* (`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_)  (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 <https://www.lua.org/manual/5.1/manual.html#5.4>`_) 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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Usage:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: lua

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

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

.. _cartridge.rpc_get_candidates:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
rpc_get_candidates (role_name[, opts])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

List instances suitable for performing a remote call.


**Parameters:**

- *role_name:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
- *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,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) URIs


-------------------------------------------------------------------------------
Authentication and authorization 
-------------------------------------------------------------------------------


.. _cartridge.http_authorize_request:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   

**Returns**:

(**boolean**) Access granted


.. _cartridge.http_render_response:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://www.lua.org/manual/5.1/manual.html#5.5>`_)   

**Returns**:

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) The same response with cookies injected


.. _cartridge.http_get_username:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
http_get_username ()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Get username for the current HTTP session. 

(**Added** in v1.1.0-4)



**Returns**:

(`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_ or **nil**) 


-------------------------------------------------------------------------------
Deprecated functions 
-------------------------------------------------------------------------------


.. _cartridge.admin_edit_replicaset:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_edit_replicaset (args)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Edit replicaset parameters (*deprecated*). 

(**Deprecated** since v1.0.0-17 in favor of :ref:`cartridge.admin_edit_topology <cartridge.admin_edit_topology>`)



**Parameters:**

- *args:* 

  - *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *alias:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *roles:* (optional `{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *master:* (optional `{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_) Failover order  
  - *weight:* (optional **number**)   
  - *vshard_group:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *all_rw:* (optional **boolean**)   


**Returns**:

(**boolean**) true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_edit_server:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_edit_server (args)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Edit an instance (*deprecated*). 

(**Deprecated** since v1.0.0-17 in favor of :ref:`cartridge.admin_edit_topology <cartridge.admin_edit_topology>`)



**Parameters:**

- *args:* 

  - *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *uri:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *labels:* (optional `{[string]=string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   


**Returns**:

(**boolean**) true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_join_server:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_join_server (args)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Join an instance to the cluster (*deprecated*). 

(**Deprecated** since v1.0.0-17 in favor of :ref:`cartridge.admin_edit_topology <cartridge.admin_edit_topology>`)



**Parameters:**

- *args:* 

  - *uri:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *instance_uuid:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *replicaset_uuid:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *roles:* (optional `{string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *timeout:* (optional **number**)   
  - *zone:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_) (**Added** in v2.4.0-14)  
  - *labels:* (optional `{[string]=string,...} <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *vshard_group:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *replicaset_alias:* (optional `string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   
  - *replicaset_weight:* (optional **number**)   


**Returns**:

(**boolean**) true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


.. _cartridge.admin_expel_server:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
admin_expel_server (uuid)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expel an instance (*deprecated*). 
Forever.

(**Deprecated** since v1.0.0-17 in favor of :ref:`cartridge.admin_edit_topology <cartridge.admin_edit_topology>`)



**Parameters:**

- *uuid:* (`string <https://www.lua.org/manual/5.1/manual.html#5.4>`_)   

**Returns**:

(**boolean**) true


**Or**

(**nil**) 

(`table <https://www.lua.org/manual/5.1/manual.html#5.5>`_) Error description


