search

tarantool / tt

Command-line utility to manage Tarantool applications
Other
101 stars 12 forks source link
cli go tarantool

readme

Tarantool CLI

Go Reference Go Report Release Full CI

Tarantool CLI - command line utility for managing Tarantool packages and Tarantool-based applications.

Contents

Intro

tt is tarantool's instance and environment management utility and is used to develop, deploy, run and operate applications.

One of the basic concepts that tt introduces is "environment". The "environment" is an isolated workspace for the tarantool application suite. tt.yaml configuration file defines the root and configuration of the environment. When tt is installed from a repository by a package manager (apt, rpm, ...) a "system" config file (/etc/tarantool/tt.yaml) is included which forms the "system" environment - the case when tt replaces the tarantoolctl. In case we want to form a local environment (very convenient during development), we use a "local" tt.yaml generated with the tt init command. In this way, the user/developer can have a large number of different "environments" in the system in which different versions of both tarantool/tt and the applications being developed will be used.

The example of a typical "environment":

graph LR
    %% Colors %%
    classDef lime fill:#C7EA46,stroke:#000,color:#000

    subgraph dot[Environment root]
      config
      bin
      modules
      local_reps
      inst_enabled[instances.enabled]
    end
    subgraph local_reps[Local repositories]
      dist[distfiles]
      rocks[rocks]
    end
    subgraph app1_files[Application]
        app_dir[app]
        app_dir --> init(init.lua):::lime
        app_dir --> |multi-instance|instances(instances.yaml):::lime
        app_dir --> |3.0|cluster_config(config.yaml):::lime
        app_dir --> var[var]
        var --> run[run] --> inst11[instance]
        inst11 --> pid1(tt.pid):::lime
        inst11 --> control1(tarantool.control):::lime
        inst11 --> binary1(tarantool.sock):::lime

        var --> log1[log] --> inst12[instance] --> logfile1(tt.log):::lime

        var --> lib1[lib] --> inst13[instance]--> xlogs1(*.xlog,*.snap):::lime
    end

    root[.] --> config(tt.yaml):::lime

    bin --> bin_dir(tarantool<br/>tarantool-ee<br/>tt-ee<br/>tt):::lime
    root --> bin[bin]

    modules --> modules_dir(ext_module_1<br/>ext_module_2):::lime
    root --> modules[modules]

    root --> dist
    root --> rocks
    inst_enabled --> app_dir

Getting started

Installation

TT can be installed from the deb / rpm repository "tarantool/modules".

Install the tarantool repositories:

https://www.tarantool.io/en/download/os-installation/

Install TT:

apt-get install tt
yum install tt
dnf install tt

On Gentoo Linux, the TT can be installed from the Tarantool Gentoo Overlay:

emerge tt

On MacOS, the TT can be installed from brew:

brew install tt

You can also install Tarantool CLI by downloading archive with pre-built binary for your OS from GitHub's Releases page.

However, on MacOS to run that binary you will need to do additional steps:

  1. After first try to run binary, you will encounter an error:

    MacOS error.

  2. To fix it, you should go to 'system settings->privacy and security', then scroll down and find:

    MacOS settings.

  3. Click on 'Allow Anyway' and you should be able to use Tarantool Cli.

Build from source

Prerequisites

To run tests:

Build

git clone https://github.com/tarantool/tt --recursive
cd tt

You can build a binary without OpenSSL and TLS support for development purposes:

TT_CLI_BUILD_SSL=no mage build
mage build

You can build a binary with statically linked OpenSSL. This build type is used for releases:

TT_CLI_BUILD_SSL=static mage build

Finally, you can build a binary with dynamically linked OpenSSL for development purposes:

TT_CLI_BUILD_SSL=shared mage build

Dependencies

tt rocks runtime dependencies:

tt install && search runtime dependencies:

Run tests

Disable etcd service:

systemctl stop etcd
systemctl disable etcd

Create a virtual environment and install tests requirements:

python3 -m venv .venv

source .venv/bin/activate

pip install -r test/requirements.txt

Once inside the virtual environment, run default set of tests (excluding slow tests):

mage test

To run full set of tests:

mage testfull

Configuration

Taratool CLI can be launched in several modes:

Configuration file

By default, configuration file is named tt.yaml.

You can specify the path to the configuration file by using the --cfg command line option or by setting the TT_CLI_CFG environment variable. The TT_CLI_CFG variable has a lower priority than the --cfg option.

Example of configuration file format:

env:
  instances_enabled: path/to/available/applications
  bin_dir: path/to/bin_dir
  inc_dir: path/to/inc_dir
  restart_on_failure: bool
  tarantoolctl_layout: bool
modules:
  directory: path/to/modules/dir
app:
  run_dir: path/to/run_dir
  log_dir: path/to/log_dir
  wal_dir: var/lib
  vinyl_dir: var/lib
  memtx_dir: var/lib
repo:
  rocks: path/to/rocks
  distfiles: path/to/install
ee:
  credential_path: path/to/file
templates:
  - path: path/to/templates_dir1
  - path: path/to/templates_dir2

env

modules

app

repo

ee

templates

Creating tt environment

tt environment can be created using init command:

$ tt init

tt init searches for existing configuration files in current directory:

If there are no existing configs in current directory, tt init generates default tt.yaml and creates a set of environment directories. Here is and example of the default environment filesystem tree:

.
├── bin
├── include
├── distfiles
├── instances.enabled
├── modules
├── tt.yaml
└── templates

Where:

External modules

External module - any executable file stored in modules directory. Module must be able to handle --description and --help flags. When calling with --description flag, module should print a short description of module to stdout. When calling with --help flag, module should print a help information about module to stdout.

Tarantool CLI already contains a basic set of modules. You can overload these with external ones, or extend functionality with your own module. Modules getting from directory, which specified in directory field (see example above).

For example, you have an external version module. When you type tt version, the external version module will be launched. To run the internal implementation, use the --internal (-I) flag. If there is no executable file with the same name, the internal implementation will be started.

You can use any external module that doesn't have any internal implementation. For example, you have module named example-module. Just type tt example-module to run it.

To see list of available modules, type tt -h.

CLI Args

Arguments of Tarantool CLI:

Autocompletion

You can generate autocompletion for bash or zsh shell:

. <(tt completion bash)

Enter tt, press tab and you will see a list of available modules with descriptions. Also, autocomplete supports external modules.

For commands, which argument is app or instance, autocompletion will show suitable apps, in case of the pattern doesn't contain delimiter :, and suitable instances otherwise.

For tt create command it will show a list of built-in templates and templates from the configuration file.

TT usage

Working with a set of instances

tt can manage a set of instances based on one source file.

To work with a set of instances, you need: a directory where the files will be located: init.lua and instances.yml.

Instances are described in instances.yml with format:

instance_name:
  parameter: value

The dot character in instance names is reserved for system use. Also, if an instance name ends with -stateboard, it will be recognized as stateboard. If it is necessary for a certain instance to work on a source file other than init.lua, then you need to create a script with a name in the format: instance_name.init.lua.

The following environment variables are associated with each instance:

Example

Working with application templates

tt can create applications from templates.

To work with application template, you need:

Application template may contain:

Template manifest MANIFEST.yaml has the following format:

description: Template description
vars:
    - prompt: User name
      name: user_name
      default: admin
      re: ^\w+$

    - prompt: Retry count
      default: "3"
      name: retry_count
      re: ^\d+$
pre-hook: ./hooks/pre-gen.sh
post-hook: ./hooks/post-gen.sh
include:
- init.lua
- instances.yml

Where:

There are pre-defined variables that can be used in template text: name - application name. It is set to --name CLI argument value.

Don't include the .rocks directory in your application template. To specify application dependencies, use the .rockspec.

Custom template example

Working with tt daemon (experimental)

tt daemon module is used to manage tt daemon on a given machine. This way instances can be operated remotely. Daemon can be configured with tt_daemon.yaml config.

tt_daemon.yaml file format:

daemon:
      run_dir: path
      log_dir: path
      log_file: string (file name)
      listen_interface: string
      port: num
      pidfile: string (file name)

Where:

TT daemon example

Setting Tarantool configuration parameters via environment variables

Using tt, you can specify configuration parameters via special environment variables even on Tarantool versions that does not natively support it. The name of a variable should have the following pattern: TT_<NAME>, where <NAME> is the uppercase name of the corresponding box.cfg parameter.

Add current environment binaries location to the PATH variable.

You can add current environment binaries location to the PATH variable:

. <(tt env)

Also TARANTOOL_DIR variable is set.

Commands

Common description. For a detailed description, use tt help command .