Skip to content

instances.yaml

The description of what runs on a host: half of the pair an application runs from, next to the cluster config config.yaml. It is in .templates/<name>/ of a project or a package, or in <root>/etc/<app>/ for the pair of a host. See Instances.

"*":
  restart: on-failure
router-001:
  restart: always
  stop_timeout: 60s
gateway:
  binary: gateway
  args: [--port, "8080"]
  env: {GATEWAY_MODE: production}
  logrotate_signal: SIGHUP
legacy:
  script: init.lua
tcm:
  kind: tcm
  http: 127.0.0.1:8080

The document maps instance names to records. A name with no record, storage-001:, is a Tarantool instance with every field at its default. The instances start in the order they are written; those "*" stands for take its place, in the order of their names.

An instance name cannot be empty, . or .., or hold a slash or a control character: it names the directories of the instance. YAML aliases and merge keys are not supported.

The kind of a record

Record Kind
neither binary nor script a Tarantool instance configured by the cluster config; it must be in the topology of config.yaml
script a Tarantool instance configured by its script; see Run a box.cfg application
binary an external process; see Run an external process
kind: tcm TCM, the Tarantool Cluster Manager of the application; see Run TCM

binary and script are mutually exclusive. Neither the name of a script instance, nor of an external process, nor of TCM can be an instance of the topology. A description has one record of TCM at most.

The record "*" - quoted, as * alone is a YAML alias - stands for every instance of the topology no other record names. It cannot have binary, script, kind or the fields of TCM, so TCM is never one of the instances of "*": it is named. A record of an instance of the topology replaces "*" for it whole, taking none of its fields.

Fields

Field Kinds Default
restart all no no, on-failure or always: when the watchdog starts the instance again after it exits on its own
stop_signal all SIGTERM the signal a stop sends: SIGINT or INT
stop_timeout all 30s how long a stop waits before it kills the instance; a positive duration such as 10s or 1m30s
env all environment variables on top of the environment of tt
script script the Lua script, relative to the application directory
binary external the program: a path, relative to the application directory, when it has a slash; otherwise a name, looked up in .rocks/bin/ of the application and then on PATH
args external the arguments of the program, a list of strings
workdir external the data directory the working directory, relative to the application directory
logrotate_signal external none the signal tt instance logrotate sends the process
kind TCM tcm, its only value
http TCM 127.0.0.1:8080 the address TCM listens on, host:port; 0.0.0.0:8080 listens on every interface
config TCM settings of TCM of your own, a YAML file merged over the config tt writes; relative to the directory of instances.yaml
password_file TCM admin.secret in the data directory, generated the file with the password of the first login of admin; relative to the directory of instances.yaml

TCM takes restart, stop_signal, stop_timeout and env as an external process does, and cannot have binary, script, args, workdir or logrotate_signal: tt finds its binary and writes its config. env reaches TCM, which ranks its TCM_* variables above its config file.

Under systemd, restart becomes Restart= of the unit and stop_timeout its TimeoutStopSec=; see Run instances under systemd.

Under --integrity-check the env of a Tarantool instance is refused: the values belong in the cluster config. See Sign packages.