Setting up Containerized UDFs
The process for setting up containerized UDFs is as follows:
1. Shut down Vector.
2. Install a container runtime capable of running Open Container Initiative (OCI) container images. Docker is one such runtime container. The installation process depends on the operating system and OCI runtime.
Note: We have tested and validated containerized services (including UDFs, Spark, Tensorflow) using Docker.
3. Download the UDF container image and configure the server to use containerized UDFs.
Linux:
For Linux, use the iisuudfc script:
iisuudfc -download_newest_compatible
Windows:
For Windows, use the following command to pull the Windows-based container:
docker pull actian/vectorwise7.0-udf-win:1.0.0
Note: To use the Windows container, Docker must be configured to use Windows containers and Hyper-V must be enabled.
Note: Windows Python UDFs use a Docker container based on the Microsoft Nano Server. This is not supported on the Windows Server 2019 hosts file. Please contact Actian Support if you need to run Python UDFs on Windows 2019.
4. Configure the database to use containerized UDFs. This step is applicable only to Windows.
a. In the config.dat file, specify the languages (other than SQL) for UDF implementation in the installation configuration parameter “ii.hostname.config.udf_languages”. You can also use the cbf command to change this configuration parameter.
Valid values for udf_languages are:
none - No languages are available; UDFs cannot be created.
javascript - (Default) Only JavaScript UDFs are available.
python - Only Python UDFs are available.
javascript,python - Both JavaScript and Python UDFs are available.
For example:
iisetres ii.hostname.config.udf_languages javascript,python
Notes:
• If the udf_languages configuration changes after the initial configuration, UDFs dependent on the initial language configuration will report an error when used in queries.
• If language support cannot be loaded for a specified language, the database will not start and the createdb command will fail.
b. Update the udf_engines.conf file in the II_SYSTEM/ingres/files directory as follows:
• Set enabled=0 in the [remote-process] section.
• Set enabled=1 in the [remote-container-win] section for Windows.
Note: Only one section can be enabled at a time in the udf_engines.conf file.
You may need to customize the [remote-container] configuration, as follows:
• command - If you are not using Docker as the container runtime, you must replace the command with the CLI command for your runtime tool. For Windows, verify that docker.exe is available via the path in the command. The path is preset to the default installation directory for docker but may need to be modified for your installation.
• port - The default port used to communicate between the database and UDF engine is based on the installation ID. Change this only if there is a conflict with the existing port.
• mounts -Two mounts map internal container paths to real paths on your server:
• II_SYSTEM/ingres/udf/import is used for all UDF imports (JS and Python).
• II_SYSTEM/ingres/udf/log is used to persist the UDF engine log file.
No other updates are required in the configuration file.
Note: To modify the command paths for Windows installations, you must escape all backslash characters with a backslash. Escaped quotes will also be needed if the path contains spaces.
c. Set the udf_engine parameter to “1” by running the following command:
iisetres ii.hostname.ingstart.*.udf_engine 1
Note: No change to existing UDF code is needed except for Javascript UDF import paths. All existing UDFs should continue to run assuming they are not accessing secured machine resources.
5. Restart the instance using ingstop and ingstart as an installation owner or DBA.
udf_engines.conf Example
The following is an example of udf_engines.conf for Windows:
######################################################
# X100 UDF engine configuration
#
# NOTE: ONLY ENABLE A SINGE SECTION BELOW
# Enable this section to use UDFs in an non-containerized process - NOT FOR PRODUCTION
[remote-process]
enabled=0
name=remote
port=0
host="127.0.0.1"
socket_retry=3
launch=1
is_container=no
processes=1
pool_limit=16
command ="x100_udf_engine --port $PORT --set system/udf_languages=$UDF_LANGUAGES --set system/udf_props=$UDF_PROPS --port_file \"$PORT_FILE_PATH\" --nosigint"
# Enable this section to use containerized UDFs in a container on Windows. The default container runtime is Docker.
[remote-container-win]
enabled=1
name=remote
port=32225
host="127.0.0.1"
socket_retry=3
launch=1
processes=1
is_container=yes
pool_limit=16
command="\"C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe\" run -p $PORT:32225 -m 512MB --rm --isolation=hyperv --mount type=bind,source=\"$II_SYSTEM\\ingres\\udf\\log\",target=C:/opt/Actian/vectorwise-udf/log,ro=0 --mount type=bind,source=\"$II_SYSTEM\\ingres\\udf\\import\",target=C:/opt/Actian/vectorwise-udf/import,ro=0 --name udf$INSTANCE_TAG actian/vector7.0-udf-win:1.0.0""