Tvisor

A service that spawns and manages tarantool instances on a given machine.

Table of contents

• Getting started
  • Prerequisites
  • Download / Build
  • Run tests
  • Usage
• Documentation
• Configuration
• Args
• API
  • Start
  • Stop
  • Status
  • List
• Caution

Getting started

Prerequisites

• Go
• Mage
• Testify
• Mapstructure
• Git

To run tests:

• Python3

Download / Build

Using go get(GOPATH):

go get -u -d github.com/tarantool/tvisor
cd $GOPATH/src/github.com/tarantool/tvisor
mage build

Using Go Modules:

git clone https://github.com/tarantool/tvisor.git
cd tvisor
mage build

Run tests

mage -v test

Usage

See Args, Configuration and API sections belows for more details.

Run:

./tvisor --cfg="cfg.json" --addr="127.0.0.1:8080"

Start an instance:

curl --header "Content-Type: application/json" --request POST \
 --data '{"command_name":"start", "params":{"name": "test_instance", "env":["MYVAR=true"]}}' \
 http://127.0.0.1:8080/instance

{"id":1}

Stop the instance:

curl --header "Content-Type: application/json" --request POST \
 --data '{"command_name":"stop", "params":{"id": 1, "force": true}}' \
 http://127.0.0.1:8080/instance

{"done":true}

Get instance status:

curl --header "Content-Type: application/json" --request POST \
 --data '{"command_name":"status","params":{"id": 1}}' \
 http://127.0.0.1:8080/instance

{"status":{"name":"test_instance","status":"running","pid":741739,"env":["MYVAR=true"]}}

Get a list of instances:

curl --header "Content-Type: application/json" --request POST \
 --data '{"command_name":"list"}' \
 http://127.0.0.1:8080/instance

{"instances":{"1":{"name":"test_instance","status":"running","pid":741739,"env":["MYVAR=true"]}}}

Graceful terminate by sending SIGINT / SIGTERM:

2021/03/23 17:56:25 The service has been terminated.

Documentation

To read the documentation use:

• go doc
• godoc

Configuration

For configuration, JSON config is used with the following fields:

• instances_dir(string) - directory that stores executable files with .lua extension for running Instances. Default: /etc/tarantool/tvisor/instances
• termination_timeout(number) - time (in seconds) to wait for the Instance to terminate correctly. After this timeout expires, the SIGKILL signal will be used to stop the instance if the force option is true, else an error will be returned. Default: 30

Args

Arguments of tvisor:

• -cfg(string) - path to Tvisor config. Default: cfg.json
• -addr(string) - address to start the HTTP server(host:port). Default: 127.0.0.1:8080
• -help - help.

API

The HTTP API is used to interact with Tvisor. The request uses JSON describing the command sent by the POST method. Response - JSON containing the result of the command.

Command structure:

{
  "command_name": "command_name",
  "params": {
    "param_name1": "a",
    "param_name2": true,
    "param_name3": 2,
    "param_name4": ["a", "b", "c"]
  }
}

Now the following commands are available: start, stop, status, list.

Start

Run an instance by name.

Name: start

Parametrs:

• name(string) - name of instance to run (without .lua extension). The instance to start will be searched for in the inst_dir directory.
• restartable(bool) - the setting is responsible for the need to restart the instance on failure. Default: true.
• env(array of strings) - an array of environment variables that will be used when starting the instance.

Example:

{
  "command_name": "start",
  "params": {
    "name": "test_instance",
    "restartable": true,
    "env": [
      "MYVAR=true"
    ]
  }
}

Response:

• id(number) - instance ID. 0 is incorrect.

Example:

{
  "id": 1
}

Stop

Stop the instance by ID.

Name: stop

Parametrs:

• id(number) - instance ID. 0 is incorrect.
• force(bool) - if truein case of a graceful termination (SIGTERM) of the instance fails, a forced termination (SIGKILL) will be used. Default: true.

Example:

{
  "command_name": "stop",
  "params": {
    "id": 1,
    "force": true
  }
}

Response:

• done(bool) - true if successful.

Example:

{
  "done": true
}

Status

Returns the status of the instance by ID.

Name: status

Parametrs:

• id(number) - instance ID. 0 is incorrect.

Example:

{
  "command_name": "status",
  "params": {
    "id": 1,
  }
}

Response:

• status(JSON Obj) - an object describing the status of the instance.
  • name(string) - the name of the instance.
  • status(string) - describes the status of the instance. Available values: running / terminated.
  • pid(number) - a process ID.
  • restartable(bool) - the setting is responsible for the need to restart the instance on failure.
  • env(array of strings) - describes the environment settled by a client.

Example:

{
  "status": {
    "name": "test_instance",
    "status": "running",
    "pid": 741739,
    "restartable": true,
    "env": [
      "MYVAR=true"
    ]
  }
}

List

Returns a list of instances.

Name: list

Example:

{
  "command_name": "list"
}

Response:

• instances(array of status objs) - map of an instance ID to current status.

Example:

{
  "instances": {
    "1": {
      "name": "test_instance",
      "status": "running",
      "pid": 741739,
      "restartable": true,
      "env": [
        "MYVAR=true"
      ]
    }
  }
}

Caution

This service is in early alpha.