Создаем свое первое приложение на Tarantool Cartridge

Здесь мы показываем, как сделать простое кластерное приложение.

Первым делом настройте среду разработки.

Затем создайте приложение с именем myapp. Выполните:

$ cartridge create --name myapp

Эта команда создает новое Tarantool Cartridge-приложение в директории ./myapp. Там теперь содержатся созданные по шаблону файлы и директории.

Войдите внутрь этой директории и запустите ваше приложение:

$ cd ./myapp
$ cartridge build
$ cartridge start

Эта команда собирает приложение локально, стартует 5 экземпляров Tarantool и stateboard (провайдер состояния), а затем запускает приложение в том виде, как оно было создано – без какой-либо интересной бизнес-логики.

Why 5 instances and a stateboard? See the instances.yml file in your application directory. It contains the configuration of all instances that you can use in the cluster. By default, it defines configuration for 5 Tarantool instances and a stateboard.

---
myapp.router:
  advertise_uri: localhost:3301
  http_port: 8081

myapp.s1-master:
  advertise_uri: localhost:3302
  http_port: 8082

myapp.s1-replica:
  advertise_uri: localhost:3303
  http_port: 8083

myapp.s2-master:
  advertise_uri: localhost:3304
  http_port: 8084

myapp.s2-replica:
  advertise_uri: localhost:3305
  http_port: 8085

myapp-stateboard:
  listen: localhost:4401
  password: passwd

Вы можете увидеть все эти экземпляры в веб-интерфейсе для управления кластером по адресу http://localhost:8081 (порт 8081 – это HTTP-порт первого экземпляра из файла instances.yml).

Теперь временно остановите кластер с помощью Ctrl + C.

Пора заняться написанием бизнес-логики для вашего приложения. Чтобы не слишком усложнять наш пример, возьмем канонический «Hello world!».

Переименуйте шаблонный файл app/roles/custom.lua в hello-world.lua.

$ mv app/roles/custom.lua app/roles/hello-world.lua

Это будет ваша роль. Роль в Tarantool Cartridge – это Lua-модуль, в котором реализованы специфичные для экземпляра Tarantool функции и логика. Далее мы покажем, как добавлять в роль свой код, собирать ее, назначать и тестировать.

У вашей роли уже есть некоторый код внутри функции init().

local function init(opts) -- luacheck: no unused args
    -- if opts.is_master then
    -- end

    local httpd = assert(cartridge.service_get('httpd'), "Failed to get httpd service")
    httpd:route({method = 'GET', path = '/hello'}, function()
        return {body = 'Hello world!'}
    end)

    return true
end

Этот код экспортирует конечную точку /hello для выполнения HTTP-запросов. Например, для первого экземпляра из файла instances.yml это будет http://localhost:8081/hello . Если вы зайдете по этому адресу в браузере после того, как роль будет назначена (чуть позже мы покажем, как это делается), то увидите на странице слова «Hello world!».

Добавим сюда еще немного кода.

local function init(opts) -- luacheck: no unused args
    -- if opts.is_master then
    -- end

    local httpd = cartridge.service_get('httpd')
    httpd:route({method = 'GET', path = '/hello'}, function()
        return {body = 'Hello world!'}
    end)

    local log = require('log')
    log.info('Hello world!')

    return true
end

Здесь мы пишем «Hello, world!» в консоль в момент назначения роли, что даст вам возможность отследить данное событие. Пока ничего сложного.

Далее изменим значение параметра role_name в «return»-блоке файла hello-world.lua. Этот блок находится в конце файла. Введенное имя роли вы увидите в веб-интерфейсе для управления кластером.

 return {
     role_name = 'Hello world!',
     init = init,
     stop = stop,
     validate_config = validate_config,
     apply_config = apply_config,
     -- dependencies = {'cartridge.roles.vshard-router'},
 }

Последнее, что осталось сделать — это добавить вашу роль в список доступных ролей кластера в файле init.lua, который находится в корневой директории проекта (myapp).

local cartridge = require('cartridge')

local ok, err = cartridge.cfg({
    roles = {
        'cartridge.roles.vshard-storage',
        'cartridge.roles.vshard-router',
        'cartridge.roles.metrics',
        'app.roles.hello-world',
    },
})

Теперь кластер будет знать про вашу роль.

Почему мы указали app.roles.hello-world? По умолчанию, имя роли в данном файле должно включать в себя полный путь от корня приложения (./myapp) до файла роли (app/roles/hello-world.lua).

Отлично! Роль готова. Теперь заново соберите и запустите ваше приложение:

$ cartridge build
$ cartridge start

Все экземпляры запущены, но они пока ничего не делают, а ждут, что им назначат роли.

Экземпляры (реплики) в кластере Tarantool Cartridge должны быть собраны в наборы реплик. Роли назначаются каждому набору, и любой экземпляр в наборе реплик видит все роли, которые назначены этому набору.

Давайте создадим набор реплик, в котором будет всего один экземпляр, и назначим этому набору вашу роль.

1. Откройте веб-интерфейс для управления кластером по адресу http://localhost:8081.

2. Рядом с экземпляром router нажмите кнопку Configure.

3. Установите флажок напротив роли Hello world!, чтобы назначить ее. Заметьте, что имя роли здесь совпадает с тем текстом, который вы задали в параметре role_name в файле hello-world.lua.

4. (По желанию) Задайте имя набора реплик, например «hello-world-replica-set».

   

5. Нажмите кнопку Create replica set. Информация о вашем наборе реплик появится в веб-интерфейсе.

   

Итак, ваша роль назначена. В консоли вы можете увидеть такое сообщение:

А если вы сейчас откроете в браузере страницу http://localhost:8081/hello , то увидите ответ вашей роли на HTTP GET-запрос.

Все работает! Что же дальше?

• Загляните в руководство администратора, чтобы настроить оставшиеся наборы реплик и опробовать разные кластерные возможности – например, включить восстановление после сбоев.
• Посмотрите руководство разработчика и реализуйте более сложную логику для вашей роли.
• Упакуйте ваше приложение для дальнейшего распространения. Вы можете выбрать любой из поддерживаемых видов пакетов: DEB, RPM, архив TGZ или Docker-образ. Архивы и пакеты можно разворачивать с помощью ansible-cartridge.
• Ознакомьтесь с документацией Cartridge.