Руководство для разработчика
Руководство для разработчика

Руководство для разработчика

Руководство для разработчика

Для разработки приложений используйте среду Tarantool Cartridge, которая установлена как компонент Tarantool Enterprise.

Ниже приведен список необходимых команд:

  1. Создайте приложение с поддержкой кластеров из шаблона:

    $ cartridge create --name <app_name> /path/to
    
  2. Разработайте приложение:

    $ cd /path/to/<app_name>
    $ ...
    
  3. Упакуйте приложение:

    $ cartridge pack [rpm|tgz] /path/to/<app_name>
    
  4. Разверните приложение:

    • Для пакета rpm:

      1. Загрузите пакет на все серверы, выделенные для Tarantool.

      2. Установите пакет:

        $ yum install <app_name>-<version>.rpm
        
      3. Запустите приложение.

        $ systemctl start <app_name>
        
    • Для архива tgz:

      1. Загрузите архив на все серверы, выделенные для Tarantool.

      2. Распакуйте архив:

        $ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
        
      3. Запустите приложение

        $ tarantool init.lua
        

Более подробную информацию с примерами см. в документации по Tarantool с открытым кодом:

Кроме того, в этом руководстве особое внимание уделяется функциям разработчика, специфичным для Enterprise-версии, которые доступны в дополнение к версии Tarantool с открытым исходным кодом в среде Tarantool Cartridge:

Реализация авторизации с использованием LDAP в веб-интерфейсе

Если в вашей организации есть сервер LDAP, можно подключить к нему Tarantool Enterprise для обработки авторизации. В этом случае следуйте общим рекомендациям <https://www.tarantool.io/en/doc/1.10/book/cartridge/cartridge_dev/#implementing-authorization-in-the-web-interface>`_ , где на первом шаге необходимо добавить модуль ldap в файл .rockspec в качестве зависимости; рекомендуется также реализовать функцию check_password следующим образом:

-- auth.lua
-- Require the LDAP module at the start of the file
local ldap = require('ldap')
...
-- Add a function to check the credentials
local function check_password(username, password)

    -- Configure the necessary LDAP parameters
    local user = string.format("cn=%s,ou=superheros,dc=glauth,dc=com", username)

    -- Connect to the LDAP server
    local ld, err = ldap.open("localhost:3893", user, password)

    -- Return an authentication success or failure
    if not ld then
       return false
    end
    return true
end
 ...

Формирование независимых от среды приложений

Tarantool Enterprise позволяет создавать независимые от среды приложения.

Независимое от среды приложение представляет собой сборку следующих компонентов (в одной директории):

  • файлы с кодом на Lua,
  • исполняемый файл tarantool,
  • подключенные внешние модули (при необходимости).

Запущенное с помощью исполняемого файла tarantool приложение обеспечивает работу сервиса.

Модули – это сторонние библиотеки на Lua, установленные в виртуальную среду (в директории приложения), которая аналогична virtualenv в Python и bundler в Ruby.

Структура такого приложения остается неизменной как на стадии разработки, так и на стадии производственной эксплуатации. Весь связанный с приложением код находится в одном месте, готов к упаковке и копированию на любой сервер.

Упаковка приложений

После определения пользовательских кластерных ролей и разработки приложения упакуйте его со всеми зависимостями (бинарные файлы модулей) и с исполняемым файлом tarantool.

Это позволит вам легко загружать, устанавливать и запускать приложение на любом сервере.

Чтобы упаковать приложение, выполните команду:

$ cartridge pack [rpm|tgz] /path/to/<app_name>

где укажите путь к вашей среде разработки (репозиторию Git, который содержит код приложения), а также один из параметров сборки:

  • rpm для сборки RPM-пакета (рекомендуется), или
  • tgz для сборки архива tar + gz (выберите этот параметр, только если у вас нет прав уровня root на серверах, выделенных для Tarantool Enterprise).

В результате будет создан пакет (или сжатый архив) с именем <имя_приложения>-<версия_тег>-<количество_коммитов> (например, myapp-1.2.1-12.rpm), который будет хранить ваше приложение в не зависимом от среды виде.

Далее переходите к развертыванию пакетных (или же архивированных) приложений на серверах.

Развертывание пакетных приложений

Чтобы развернуть пакетное приложение, выполните следующие действия на каждом сервере, выделенном для Tarantool Enterprise:

  1. Загрузите локально пакет, созданный на предыдущем шаге.

  2. Установите приложение:

    $ yum install <app_name>-<version>.rpm
    
  3. Запустите один или несколько экземпляров Tarantool с соответствующими сервисами, как описано ниже.

    • Отдельный экземпляр:

      $ systemctl start <app_name>
      

      Это запустит экземпляр сервиса systemd с прослушиванием по порту 3301.

    • Несколько экземпляров на одном или нескольких серверах:

      $ systemctl start <app_name>@instance_1
      $ systemctl start <app_name>@instance_2
      ...
      $ systemctl start <app_name>@instance_<number>
      

      где <app_name>@instance_<number> (<имя_приложения>@экземпляр_<число>) – это имя экземпляра сервиса systemd с инкрементным числом <number> (уникальным для каждого экземпляра), которое следует добавить к порту 3300 для настройки прослушивания (например, 3301, 3302 и т.д.).

  4. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

Чтобы остановить все сервисы на сервере, используйте команду systemctl stop и укажите имена экземпляров по одному. Например:

$ systemctl stop <app_name>@instance_1 <app_name>@instance_2 ... <app_name>@instance_<N>

Развертывание архивированных приложений

Тогда как пакет RPM по умолчанию помещает ваше приложение в /usr/share/tarantool/<имя_приложения> на вашем сервере, архив tar + gz не создает какую-либо структуру, помимо директории <имя_приложения>/, поэтому вы сами несете ответственность за правильность размещения приложения.

Примечание

Для развертывания рекомендуется использовать RPM-пакеты. Развертывайте архивы, только если у вас нет прав уровня root.

Чтобы разместить и развернуть приложение, выполните следующие действия на каждом сервере, выделенном для Tarantool Enterprise:

  1. Загрузите архив, распакуйте его и извлеките содержимое в директорию /home/<user>/apps:

    $ tar -xzvf <app_name>-<version>.tar.gz -C /home/<user>/apps
    
  2. Запустите экземпляры Tarantool с соответствующими сервисами.

    Для управления и конфигурации экземпляров используйте такие средства, как ansible, systemd и supervisord.

  3. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

Обновление кода

Все экземпляры в кластере должны использовать один и тот же код. Это относится ко всем компонентам: пользовательским ролям, приложениям, бинарным файлам модулей, исполняемым файлам tarantool и tarantoolctl (при необходимости).

Обратите внимание на возможную обратную совместимость, которую может принести с собой любой компонент. Это поможет вам выбрать сценарий для обновления в эксплуатационной среде. Имейте в виду, что вы несете ответственность за совместимость кода и обработку конфликтов в случае возникновения несоответствий.

Чтобы обновить любой из компонентов, подготовьте новую версию пакета (архива):

  1. Обновите необходимые файлы в вашей среде разработки (директории):
    • Ваш собственный исходный код: пользовательские роли и / или приложения.
    • Бинарные файлы модулей.
    • Исполняемые файлы. Замените их на файлы из нового комплекта.
  2. Увеличьте версию, как описано в разделе по управлению версиями приложения.
  3. Повторно упакуйте обновленные файлы, как описано в разделе по упаковке приложений.
  4. Выберите сценарий обновления, как описано в разделе по обновлению в эксплуатационной среде.

Запуск примеров приложений

Дистрибутив Enterprise включает в себя примеры приложений в директории examples/, которые демонстрируют основные функциональные возможности Tarantool.

Приложение кэширования со сквозной записью в PostgreSQL

Пример в pg_writethrough_cache/ показывает, как Tarantool может кэшировать данные, записанные через него в базу данных PostgreSQL для ускорения запросов на чтение.

Для примера приложения требуется развернутая база данных PostgreSQL и следующие модули сторонних библиотек:

$ tarantoolctl rocks install http
$ tarantoolctl rocks install pg
$ tarantoolctl rocks install argparse

Просмотрите код в файлах, чтобы понять, что может делать приложение.

Чтобы запустить приложение для локальной базы данных PostgreSQL, выполните команду:

$ tarantool cachesrv.lua --binary-port 3333 --http-port 8888 --database postgresql://localhost/postgres

Приложение кэширования с отложенной записью в Oracle

Пример в ora-writebehind-cache/ показывает, как Tarantool может кэшировать записи и помещать их в базу данных Oracle для ускорения как записи, так и чтения.

Требования приложения

Для примера приложения необходимы:

  • развернутая база данных Oracle;

  • инструменты Oracle: Instant Client and SQL Plus, оба версии 12.2;

    Примечание

    Если Oracle Instant Client выдает ошибки в файлах с расширением .so (динамические библиотеки Oracle), поместите их в какую-либо директорию и добавьте ее в переменную окружения LD_LIBRARY_PATH.

    Например: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/<путь_к_файлам_so>

  • модули сторонних библиотек, перечисленные в файле rockspec.

Чтобы установить модули, выполните следующую команду в директории examples/ora_writebehind_cache:

$ tarantoolctl rocks make oracle_rb_cache-0.1.0-1.rockspec

Если у вас нет развернутого экземпляра Oracle под рукой, запустите пустой объект в контейнере Docker:

  1. В браузере войдите в Реестр контейнеров Oracle, выберите Database (База данных) и примите «Корпоративные условия и ограничения Oracle».

  2. В директории ora-writebehind-cache/ войдите в репозиторий под учетной записью Oracle, получите данные и запустите образ с помощью подготовленных скриптов

    $ docker login container-registry.oracle.com
    Login:
    Password:
    Login Succeeded
    $ docker pull container-registry.oracle.com/database/enterprise:12.2.0.1
    $ docker run -itd \
       -p 1521:1521 \
       -p 5500:5500 \
       --name oracle \
       -v "$(pwd)"/setupdb/configDB.sh:/home/oracle/setup/configDB.sh \
       -v "$(pwd)"/setupdb/runUserScripts.sh:/home/oracle/setup/runUserScripts.sh \
       -v "$(pwd)"/startupdb:/opt/oracle/scripts/startup \
       container-registry.oracle.com/database/enterprise:12.2.0.1
    

Когда всё будет готово, запустите пример приложения.

Запуск кэширования с отложенной записью

Чтобы запустить приложение, выполните следующую команду в директории examples/ora_writebehind_cache:

$ tarantool init.lua

Данное приложение поддерживает следующие запросы:

  • Получение данных: GET http://<host>:<http_port>/account/id;

  • Добавление: POST http://<host>:<http_port>/account/ со следующими данными:

    {"clng_clng_id":1,"asut_asut_id":2,"creation_data":"01-JAN-19","navi_user":"userName"}
    
  • Обновление: POST http://<host>:<http_port>/account/id с теми же данными, что и в запросе на добавление;

  • Удаление: DELETE http://<host>:<http_port>/account/id,где id – это идентификатор учетной записи.

Взгляните на примеры скриптов CURL в директории examples/ora_writebehind_cache/testing и просмотрите файл README.md для получения дополнительной информации об их использовании.

Простейшее приложение в Docker

Пример в директории docker/ содержит простейшее приложение, которое можно упаковать в контейнер Docker и запустить на CentOS 7.

Файл hello.lua представляет собой элементарную точку входа в приложение, поэтому вы можете добавить туда собственный код.

  1. Чтобы создать контейнер, выполните команду:

    $ docker build -t tarantool-enterprise-docker -f Dockerfile ../..
    
  2. Чтобы запустить его:

    $ docker run --rm -t -i tarantool-enterprise-docker