plcontainer

Contents

Синтаксис
Команды и параметры
Примеры
Файл конфигурации PL/Container
- Обновление конфигурации PL/Container

Утилита plcontainer устанавливает Docker-образы и управляет конфигурацией PL/Container. Утилита содержит два набора команд:

команды image — для управления Docker-образами на хостах Greengage DB;
команды runtime — для управления файлом конфигурации PL/Container на экземплярах Greengage DB.

В файл конфигурации PL/Container можно добавлять информацию о Docker-образах: имя, расположение и общие каталоги. Файл конфигурации также можно редактировать.

Чтобы настроить PL/Container для использования Docker-образа, установите образ на все хосты Greengage DB и добавьте информацию о конфигурации в PL/Container.

Значения конфигурации PL/Container чувствительны к регистру: имена образов, идентификаторы выполнения, имена и значения параметров.

plcontainer [ <command> ] [-h | --help [<command>]] [ --verbose ]

где command — одна из следующих команд:

image-add { -f | --file } <image_file> [ -ulc | --use_local_copy ]
image-add { -u | --URL } <image_url>

image-delete { -i | --image } <image_name>

image-list

runtime-add { -r | --runtime } <runtime_id>
            { -i | --image } <image_name>
            { -l | --language } { python | python3 | r }
            [ { -v | --volume } <shared_volume> [ { -v | --volume } <shared_volume> ... ] ]
            [ { -s | --setting } <param>=<value> [ { -s | --setting } <param>=<value> ... ] ]

runtime-replace { -r | --runtime } <runtime_id>
                { -i | --image } <image_name>
                { -l | --language } { python | python3 | r }
                [ { -v | --volume } <shared_volume> [ { -v | --volume } <shared_volume> ... ] ]
                [ { -s | --setting } <param>=<value> [ { -s | --setting } <param>=<value> ... ] ]

runtime-show { -r | --runtime } <runtime_id>

runtime-delete { -r | --runtime } <runtime_id>

runtime-edit [ { -e | --editor } <editor> ]

runtime-backup { -f | --file } <config_file>

runtime-restore { -f | --file } <config_file>

runtime-verify

image-add <location>

Устанавливает Docker-образ на хосты Greengage DB. Укажите расположение файла Docker-образа на хосте или URL образа. Поддерживаемые параметры расположения:

{-f | --file} <image_file> — путь к tar-архиву Docker-образа в файловой системе локального хоста. Пример: файл образа в домашнем каталоге пользователя gpadmin: /home/gpadmin/test_image.tar.gz.
{-u | --URL} <image_url> — URL репозитория Docker и образа. Пример URL локального репозитория Docker: 192.168.0.1:5000/images/plc_python_shared:latest.

По умолчанию команда image-add копирует и устанавливает образ на каждый сегмент Greengage DB и резервный мастер-хост. При указании image_file с параметром [-ulc | --use_local_copy] утилита plcontainer устанавливает образ только на текущем хосте.

После установки Docker-образа используйте команду runtime-add для настройки PL/Container.

image-delete {-i | --image} <image_name>

Удаляет установленный Docker-образ со всех хостов Greengage DB.

image-list

Выводит список установленных Docker-образов на хосте. Команда показывает только образы локального хоста и не включает удаленные. Отображаются все установленные образы, включая те, которые были установлены напрямую через Docker.

runtime-add <runtime_id>

Добавляет информацию о конфигурации в файл PL/Container на всех хостах Greengage DB. Если runtime_id уже существует, утилита возвращает ошибку, и конфигурация не добавляется.

Поддерживаемые параметры:

{-i | --image} <image_name> — (обязательно) полное имя Docker-образа, установленного на хостах Greengage DB.

Если указанный образ не установлен, утилита выдает предупреждение.

Команда plcontainer image-list показывает информацию об установленных образах: имя и тег (столбцы Repository и Tag).

{-l | --language} python | python3 | r

(Обязательно) Тип языка PL/Container. Поддерживаемые значения: python (PL/Python с Python 2), python3 (PL/Python с Python 3) и r (PL/R). При добавлении конфигурации новой среды выполнения утилита автоматически добавляет команду запуска на основе указанного языка.

Команда запуска для языка Python 2:

/clientdir/pyclient.sh

Команда запуска для языка Python 3:

/clientdir/py3client.sh

Команда запуска для языка R:

/clientdir/rclient.sh

{-r | --runtime} <runtime_id>

(Обязательно) Идентификатор выполнения. Это значение элемента id в файле конфигурации PL/Container. Максимальная длина: 63 байта.

Это имя указывается в пользовательской функции Greengage DB в строке # container.

{-s | --setting} <param>=<value>

(Опционально) Настройка для конфигурации выполнения. Параметр можно указывать несколько раз. Настройка применяется к конфигурации, указанной в runtime_id. Допустимые параметры:

cpu_share — лимит CPU для каждого контейнера в конфигурации выполнения. По умолчанию: 1024. Значение — относительный вес использования CPU по сравнению с другими контейнерами.
memory_mb — лимит памяти для каждого контейнера в конфигурации выполнения. По умолчанию: 1024. Значение — целое число, объем памяти в МБ.
resource_group_id — ресурсная группа для конфигурации выполнения. Ресурсная группа ограничивает общее использование CPU и памяти для всех контейнеров данной конфигурации. Укажите groupid ресурсной группы.
roles — роли Greengage DB, которым разрешен запуск контейнера для данной конфигурации. Можно указать одно имя роли или список через запятую. По умолчанию ограничений нет.
use_container_logging — включение или отключение логирования Docker для контейнера. Значение yes включает логирование. Значение no отключает логирование (по умолчанию).

Уровень логирования управляется параметром log_min_messages сервера Greengage DB. По умолчанию: warning.
enable_network — включение или отключение сетевого доступа для контейнера пользовательской функции. Значение yes разрешает функциям обращаться к сети. Значение no отключает сетевой доступ (по умолчанию).

{-v | --volume} <shared_volume>

(Опционально) Docker-том для монтирования. Параметр можно указывать несколько раз для определения нескольких томов.

Формат общего тома: <host-dir>:<container-dir>:[rw|ro]. Информация сохраняется как атрибуты элемента shared_directory в элементе runtime файла конфигурации PL/Container:

host-dir — абсолютный путь к каталогу на хосте. Пользователь gpadmin должен иметь доступ к этому каталогу.
container-dir — абсолютный путь к каталогу в Docker-контейнере.
[rw|ro] — режим доступа к каталогу хоста из контейнера: чтение/запись или только чтение.

При добавлении конфигурации новой среды выполнения утилита автоматически добавляет том только для чтения:

/usr/local/gpdb/bin/plcontainer_clients:/clientdir:ro

При необходимости можно указать дополнительные общие каталоги. Утилита вернет ошибку, если указанный container-dir совпадает с автоматически добавляемым или если несколько томов имеют одинаковый container-dir.

ВНИМАНИЕ

Предоставление доступа на чтение/запись к каталогу хоста требует особого внимания:

При указании доступа на чтение/запись убедитесь, что у каталога установлены правильные права доступа.
При выполнении пользовательских функций PL/Container несколько параллельно работающих контейнеров на хосте могут изменять данные в общем каталоге.

Убедитесь, что функции корректно работают при параллельном доступе к данным в каталоге хоста.

runtime-backup {-f | --file} <config_file>

Сохраняет файл конфигурации PL/Container в указанный файл на локальном хосте.

runtime-delete {-r | --runtime} <runtime_id>

Удаляет конфигурацию выполнения из файла PL/Container на всех экземплярах Greengage DB. Если указанный runtime_id не существует, утилита возвращает сообщение.

runtime-edit [{-e | --editor} <editor>]

Открывает XML-файл plcontainer_configuration.xml в указанном редакторе. По умолчанию используется vi.

При сохранении файл конфигурации обновляется на всех хостах Greengage DB. Если в файле есть ошибки, утилита не применяет изменения.

runtime-replace <runtime_id>

Заменяет конфигурацию выполнения в файле PL/Container на всех экземплярах Greengage DB. Если runtime_id не существует, конфигурация добавляется. Утилита автоматически добавляет команду запуска и общий каталог.

runtime-restore {-f | --file} <config_file>

Заменяет файл конфигурации PL/Container plcontainer_configuration.xml на всех экземплярах Greengage DB содержимым указанного файла с локального хоста.

runtime-show [{-r | --runtime} <runtime_id>]

Показывает конфигурацию выполнения PL/Container в читаемом формате. Если runtime_id не указан, показывается конфигурация всех идентификаторов выполнения.

runtime-verify

Проверяет согласованность конфигурации PL/Container на экземплярах Greengage DB с конфигурацией на мастере. При обнаружении несоответствий предлагает заменить удаленную копию локальной. Также выполняет валидацию XML.

-h | --help [<command>]

Показывает справку. Без указания команды выводит справку по всем командам plcontainer. С указанием команды выводит справку по конкретной команде.

--verbose

Включает подробное логирование.

Примеры команд для управления PL/Container:

Установка Docker-образа на все хосты Greengage DB. В данном примере образ загружается из файла. Утилита отображает прогресс установки на все хосты:
```
$ plcontainer image-add -f plcontainer-python3-image-2.4.0-gp6.tar.gz
```
После установки образа добавьте или обновите запись о среде выполнения в файле конфигурации PL/Container, чтобы дать PL/Container доступ к образу для запуска контейнеров.
Установка Docker-образа только на локальный хост Greengage DB:
```
$ plcontainer image-add -f plcontainer-python3-image-2.4.0-gp6.tar.gz --use_local_copy
```
Добавление записи о контейнере в файл конфигурации PL/Container. Пример добавляет конфигурацию для среды выполнения Python 3:
```
$ plcontainer runtime-add -r plc_python_shared -i python39.alpine:latest -l python3
```
Утилита показывает прогресс добавления конфигурации и ее распространения на все экземпляры.
Отображение конкретной среды выполнения с заданным идентификатором:
```
$ plcontainer runtime-show -r plc_python_shared
```
Редактирование конфигурации в интерактивном редакторе. Пример редактирования с помощью vim:
```
$ plcontainer runtime-edit -e vim
```
При сохранении утилита показывает прогресс копирования файла на хосты Greengage DB.
Сохранение текущей конфигурации PL/Container в файл. Пример сохранения в /home/gpadmin/saved_plc_config.xml:
```
$ plcontainer runtime-backup -f /home/gpadmin/saved_plc_config.xml
```
Замена файла конфигурации PL/Container содержимым XML-файла. Пример замены конфигурации файлом из каталога /home/gpadmin:
```
$ plcontainer runtime-restore -f /home/gpadmin/new_plcontainer_configuration.xml
```
Утилита показывает прогресс копирования обновленного файла на экземпляры Greengage DB.

Утилита Greengage DB plcontainer управляет файлами конфигурации PL/Container. Утилита обеспечивает согласованность файлов конфигурации на мастере и экземплярах сегментов.

ВНИМАНИЕ

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

PL/Container хранит файл конфигурации plcontainer_configuration.xml в каталоге данных каждого сегмента Greengage DB.

Следующий запрос выводит список каталогов данных кластера Greengage DB:

SELECT hostname, datadir
FROM gp_segment_configuration;

Пример файла конфигурации PL/Container находится в $GPHOME/share/postgresql/plcontainer.

Имена элементов, атрибутов и значения в XML-файле чувствительны к регистру.

Корневой элемент XML-файла — configuration, который содержит один или несколько элементов runtime. Идентификатор id элемента runtime указывается в строке # container: при определении функции PL/Container.

Ниже приведен пример файла. Обратите внимание, что все элементы, имена и атрибуты в XML чувствительны к регистру.

<?xml version="1.0" ?>
<configuration>
    <runtime>
        <id>plc_python_shared</id>
        <image>python39.alpine:latest</image>
        <command>/clientdir/py3client.sh</command>
        <shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>
    </runtime>
    <runtime>
        <id>plc_r_shared</id>
        <image>r.alpine:latest</image>
        <command>/clientdir/rclient.sh</command>
        <shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>
        <setting use_container_logging="yes"/>
        <setting enable_network="no"/>
        <setting roles="gpadmin,user1"/>
    </runtime>
</configuration>

Ниже приведены описания XML-элементов и атрибутов в файле конфигурации PL/Container.

configuration

Корневой элемент XML-файла.

runtime

Элемент для каждого конкретного контейнера, доступного в системе. Является дочерним элементом configuration.

id

(Обязательно) Значение используется для ссылки на Docker-контейнер из пользовательской функции PL/Container. Значение id должно быть уникальным в конфигурации. id должен начинаться с символа или цифры (a-z, A-Z или 0-9) и может содержать символы, цифры или символы _ (подчеркивание), . (точка) или - (тире). Максимальная длина — 63 байта.

id определяет, какой Docker-образ использовать при создании контейнера PL/Container для выполнения пользовательской функции.

image

(Обязательно) Полное имя Docker-образа, включая тег. Укажите его так же, как при запуске контейнера в Docker. Несколько элементов runtime могут ссылаться на один и тот же образ. Таким образом, в Docker они будут представлены идентичными контейнерами.

Например, два элемента runtime с разными id могут использовать один и тот же Docker-образ python39.alpine:latest.

command

(Обязательно) Команда, которая должна выполняться внутри контейнера для запуска клиентского процесса. При создании элемента runtime утилита plcontainer автоматически добавляет этот элемент на основе указанного языка (-l).

Элемент command для языка Python 2:

<command>/clientdir/pyclient.sh</command>

Элемент command для языка Python 3:

<command>/clientdir/py3client.sh</command>

Элемент command для языка R:

<command>/clientdir/rclient.sh</command>

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

ПРИМЕЧАНИЕ

Этот элемент нельзя установить напрямую с помощью утилиты plcontainer. Для изменения используйте команду plcontainer runtime-edit.

shared_directory

(Опционально) Указывает общий Docker-том для контейнера и определяет параметры доступа. Разрешены несколько элементов shared_directory. Каждый элемент shared_directory указывает один общий том. XML-атрибуты для элемента shared_directory:

host — путь к каталогу на хосте.
container — путь к каталогу внутри контейнера.
access — уровень доступа к каталогу хоста: ro (только чтение) или rw (чтение/запись).

При создании элемента runtime утилита plcontainer автоматически добавляет элемент shared_directory:

<shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>

Для каждого элемента runtime атрибут container элементов shared_directory должен быть уникальным. Например, нельзя использовать два элемента shared_directory с container="/clientdir" в одном runtime.

ВНИМАНИЕ

Доступ для чтения-записи к каталогу хоста требует особой осторожности. Убедитесь, что каталог на хосте имеет корректные права доступа. При одновременном запуске нескольких Docker-контейнеров PL/Container несколько функций могут изменять данные в каталоге хоста. Убедитесь, что функции корректно обрабатывают параллельный доступ к данным.

setting

(Опционально) Этот элемент указывает информацию о конфигурации Docker-контейнера. Каждый элемент setting содержит один атрибут. Атрибут элемента указывает информацию о логировании, памяти или сети. Например, для включения логирования используется следующий элемент:

<setting use_container_logging="yes"/>

Ниже перечислены допустимые атрибуты:

cpu_share: (Опционально) Определяет долю CPU, выделяемую каждому контейнеру PL/Container в среде выполнения. Значение атрибута — положительное целое число. Значение по умолчанию: 1024. Это число задает относительный вес использования CPU по сравнению с другими контейнерами.

Например, контейнер с cpu_share 2048 получает в два раза больше времени процессора, чем контейнер со значением по умолчанию 1024.
memory_mb="<size>": (Опционально) Указывает объем памяти в МБ, доступный каждому контейнеру. Каждый контейнер запускается с этим объемом RAM и с двойным объемом подкачки. Потребление памяти ограничивается настройками cgroups хост-системы, и при превышении контейнер завершает работу.
resource_group_id="<rg_groupid>": (Опционально) Определяет groupid ресурсной группы для конфигурации выполнения PL/Container. Ресурсная группа ограничивает общее использование CPU и памяти для всех контейнеров с этой конфигурацией. Необходимо указать groupid ресурсной группы. Если ресурсная группа не назначена, контейнеры ограничены только системными ресурсами.
roles="<list_of_roles>": (Опционально) Указывает имя роли Greengage DB или список ролей, разделенных запятыми. PL/Container запускает контейнер с этой конфигурацией только для указанных ролей. Если атрибут не задан, любой пользователь Greengage DB может запустить контейнер с этой конфигурацией. Например, вы создаете пользовательскую функцию с языком plcontainer и конфигурацией выполнения # container:, для которой указан атрибут roles. При запуске функции PL/Container проверяет, входит ли роль пользователя в список, и запускает контейнер только в случае совпадения.
use_container_logging="{yes | no}": (Опционально) Включает или отключает логирование Docker для контейнера. Значение yes включает логирование. Значение no отключает логирование (по умолчанию).
enable_network="{yes | no}": (Опционально) Включает или отключает сетевой доступ для контейнера пользовательской функции. Значение yes разрешает сетевой доступ. Значение no запрещает сетевой доступ (по умолчанию).

Вы можете добавить элемент runtime в файл конфигурации PL/Container с помощью команды plcontainer runtime-add. Параметры команды задают информацию, такую как идентификатор выполнения, Docker-образ и язык. Для обновления существующего элемента runtime используйте команду plcontainer runtime-replace. Утилита синхронизирует изменения файла конфигурации на мастере и всех экземплярах сегментов.

Файл конфигурации PL/Container может содержать несколько элементов runtime, ссылающихся на один и тот же Docker-образ, указанный в XML-элементе image. В приведенном примере элементы runtime имеют идентификаторы plc_python_128 и plc_python_256 и оба ссылаются на Docker-образ python39.alpine:latest. Первый элемент runtime имеет лимит RAM 128 МБ, а второй — 256 МБ.

<configuration>
  <runtime>
    <id>plc_python_128</id>
    <image>python39.alpine:latest</image>
    <command>/clientdir/py3client.sh</command>
    <shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>
    <setting memory_mb="128"/>
  </runtime>
  <runtime>
    <id>plc_python_256</id>
    <image>python39.alpine:latest</image>
    <command>/clientdir/py3client.sh</command>
    <shared_directory access="ro" container="/clientdir" host="/usr/local/gpdb/bin/plcontainer_clients"/>
    <setting memory_mb="256"/>
    <setting resource_group_id="24993"/>
  </runtime>
</configuration>

Изменения конфигурации, выполненные через утилиту, применяются к XML-файлам на всех сегментах Greengage DB. Однако текущие запущенные сессии PL/Container используют конфигурацию, которая была активна при их запуске. Чтобы обновить конфигурацию PL/Container в запущенной сессии, выполните следующую команду:

SELECT * FROM plcontainer_refresh_config;

Эта команда вызывает функцию PL/Container, которая обновляет конфигурацию сессии на мастере и всех сегментах.

pgbouncer

psql

plcontainer

Синтаксис

Команды и параметры

Примеры

Файл конфигурации PL/Container

Обновление конфигурации PL/Container