PL/Container Architecture

Example of the process flow:

Consider a query that selects table data using all available segments, and transforms the data using a PL/Container function. On the first call to a function in a segment container, the query executor on the master host starts the container on that segment host. It then contacts the running container to obtain the results. The container might respond with a Service Provider Interface (SPI) - a SQL query executed by the container to get some data back from the database - returning the result to the query executor.

A container running in standby mode waits on the socket and does not consume any CPU resources. PL/Container memory consumption depends on the amount of data cached in global dictionaries.

The container connection is closed by closing the Greenplum Database session that started the container, and the container shuts down.

About PL/Container 3 Beta

PL/Container 3 is currently a Beta feature, and provides only an Beta R Docker image for executing functions; Python images are not yet available. Save and uninstall any existing PL/Container software before you install PL/Container 3 Beta.

• Install Docker
• Install PL/Container
• Install the PL/Container Docker images
• Test the PL/Container installation

The following sections describe these tasks in detail.

Prerequisites

• For PL/Container 2.1.x use Greenplum Database 6 on CentOS 7.x (or later), RHEL 7.x (or later), or Ubuntu 18.04.
  Note: PL/Container 2.1.x supports Docker images with Python 3 installed.
• For PL/Container 3 Beta use Greenplum Database 6.1 or later on CentOS 7.x (or later), RHEL 7.x (or later), or Ubuntu 18.04.
• The minimum Linux OS kernel version supported is 3.10. To verfiy your kernel release use:

  $ uname -r

• The minimum Docker versions on all hosts needs to be Docker 19.03.

Install Docker

To use PL/Container you need to install Docker on all Greenplum Database host systems. These instructions show how to set up the Docker service on CentOS 7 but RHEL 7 is a similar process.

These steps install the docker package and start the Docker service as a user with sudo privileges.

1. Ensure the user has sudo privileges or is root.
2. Install the dependencies required for Docker:

   sudo yum install -y yum-utils device-mapper-persistent-data lvm2

3. Add the Docker repo:

   sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

4. Update yum cache:

   sudo yum makecache fast

5. Install Docker:

   sudo yum -y install docker-ce

6. Start Docker daemon:

   sudo systemctl start docker

7. On each Greenplum Database host, the gpadmin user should be part of the docker group for the user to be able to manage Docker images and containers. Assign the Greenplum Database administrator gpadmin to the group docker:

   sudo usermod -aG docker gpadmin

8. Exit the session and login again to update the privileges.
9. Configure Docker to start when the host system starts:

   sudo systemctl enable docker.service

   sudo systemctl start docker.service

10. Run a Docker command to test the Docker installation. This command lists the currently running Docker containers.

    docker ps

11. After you install Docker on all Greenplum Database hosts, restart the Greenplum Database system to give Greenplum Database access to Docker.

    gpstop -ra

For a list of observations while using Docker and PL/Container, see the Notes section. For a list of Docker reference documentation, see Docker References.

Install PL/Container

Install the PL/Container language extension using the gppkg utility.

1. Download the "PL/Container for RHEL 7" package that applies to your Greenplum Database version, from the VMware Tanzu Network. PL/Container is listed under Greenplum Procedural Languages.
2. As gpadmin, copy the PL/Container language extension package to the master host.
3. Run the package installation command:

   gppkg -i plcontainer-2.1.1-rhel7-x86_64.gppkg

4. Source the file $GPHOME/greenplum_path.sh:

   source $GPHOME/greenplum_path.sh

5. Make sure Greenplum Database is up and running:

   gpstate -s

   If it's not, start it:

   gpstart -a

6. For PL/Container version 3 Beta only, add the plc_coordinator shared library to the Greenplum Database shared_preload_libraries server configuration parameter. Be sure to retain any previous setting of the parameter. For example:

   gpconfig -s shared_preload_libraries
   Values on all segments are consistent
   GUC          : shared_preload_libraries
   Master  value: diskquota
   Segment value: diskquota
   gpconfig -c shared_preload_libraries -v 'diskquota,plc_coordinator'

7. Restart Greenplum Database:

   gpstop -ra

8. Login into one of the available databases, for example:

   psql postgres

9. Register the PL/Container extension, which installs the plcontainer utility:

   CREATE EXTENSION plcontainer; 

   You'll need to register the utility separately on each database that might need the PL/Container functionality.

Install PL/Container Docker Images

Install the Docker images that PL/Container will use to create language-specific containers to run the UDFs.

• Download the files that contain the Docker images from the VMware Tanzu Network. For example, for Greenplum 6.5, click on "PL/Container Docker Image for Python 2.1.1" which downloads plcontainer-python-image-2.1.1-gp6.tar.gz with Python 2.7.12 and the Python Data Science Module Package.

  If you require different images from the ones provided by Pivotal Greenplum, you can create custom Docker images, install the image and add the image to the PL/ Container configuration.

• If you are using PL/Container 3 Beta, note that this Beta version is compatible only with the associated plcontainer-r-image-3.0.0-beta-gp6.tar.gz image.

• Use the plcontainer image-add command to install an image on all Greenplum Database hosts. Provide the -f option to specify the file system location of a downloaded image file. For example:

  # Install a Python 2 based Docker image
  plcontainer image-add -f /home/gpadmin/plcontainer-python-image-2.1.1-gp6.tar.gz
              
  # Install a Python 3 based Docker image
  plcontainer image-add -f /home/gpadmin/plcontainer-python3-image-2.1.1-gp6.tar.gz
              
  # Install an R based Docker image
  plcontainer image-add -f /home/gpadmin/plcontainer-r-image-2.1.1-gp6.tar.gz
  
  # Install the Beta R image for use with PL/Container 3.0.0 Beta
  plcontainer image-add -f /home/gpadmin/plcontainer-r-image-3.0.0-beta-gp6.tar.gz

  The utility displays progress information, similar to:

  20200127:21:54:43:004607 plcontainer:mdw:gpadmin-[INFO]:-Checking whether docker is installed on all hosts...
  20200127:21:54:43:004607 plcontainer:mdw:gpadmin-[INFO]:-Distributing image file /home/gpadmin/plcontainer-python-images-1.5.0.tar to all hosts...
  20200127:21:54:55:004607 plcontainer:mdw:gpadmin-[INFO]:-Loading image on all hosts...
  20200127:21:55:37:004607 plcontainer:mdw:gpadmin-[INFO]:-Removing temporary image files on all hosts...

  By default, the image-add command copies the image to each Greenplum Database segment and standby master host, and installs the image. When you specify the [-ulc | --use_local_copy] option, plcontainer installs the image only on the host on which you execute the command. Use this option when the PL/Container image already resides on disk on a host.

  For more information on image-add options, visit the plcontainer reference page.

• To display the installed Docker images on the local host use:

  $ plcontainer image-list

  REPOSITORY	TAG	IMAGE ID	CREATED
  pivotaldata/plcontainer_r_shared	devel	7427f920669d	10 months ago
  pivotaldata/plcontainer_python_shared	devel	e36827eba53e	10 months ago
  pivotaldata/plcontainer_python3_shared	devel	y32827ebe55b	5 months ago

• Add the image information to the PL/Container configuration file using plcontainer runtime-add, to allow PL/Container to associate containers with specified Docker images.

  Use the -r option to specify your own user defined runtime ID name, use the -i option to specify the Docker image, and the -l option to specify the Docker image language. When there are multiple versions of the same docker image, for example 1.0.0 or 1.2.0, specify the TAG version using ":" after the image name.

  # Add a Python 2 based runtime
  plcontainer runtime-add -r plc_python_shared -i pivotaldata/plcontainer_python_shared:devel -l python
              
  # Add a Python 3 based runtime that is supported with PL/Container 2.1.x
  plcontainer runtime-add -r plc_python3_shared -i pivotaldata/plcontainer_python3_shared:devel -l python3
              
  # Add an R based runtime
  plcontainer runtime-add -r plc_r_shared -i pivotaldata/plcontainer_r_shared:devel -l r

  The utility displays progress information as it updates the PL/Container configuration file on the Greenplum Database instances.

  For details on other runtime-add options, see the plcontainer reference page.

• Optional: Use Greenplum Database resource groups to manage and limit the total CPU and memory resources of containers in PL/Container runtimes. In this example, the Python runtime will be used with a preconfigured resource group 16391:.

  plcontainer runtime-add -r plc_python_shared -i pivotaldata/plcontainer_python_shared:devel -l
        python -s resource_group_id=16391

  For more information about enabling, configuring, and using Greenplum Database resource groups with PL/Container, see PL/Container Resource Management .

You can now create a simple function to test your PL/Container installation.

Test the PL/Container Installation

plcontainer runtime-show

PL/Container Runtime Configuration: 
---------------------------------------------------------
  Runtime ID: plc_python_shared
  Linked Docker Image: pivotaldata/plcontainer_python_shared:devel
  Runtime Setting(s): 
  Shared Directory: 
  ---- Shared Directory From HOST '/usr/local/greenplum-db/./bin/plcontainer_clients' to Container '/clientdir', access mode is 'ro'
---------------------------------------------------------

You can also view the PL/Container configuration information with the plcontainer runtime-show -r <runtime_id> command. You can view the PL/Container configuration XML file with the plcontainer runtime-edit command.

Use the psql utility and select an existing database:

psql postgres;

If the PL/Container extension is not registered with the selected database, first enable it using:

postgres=# CREATE EXTENSION plcontainer;

Create a simple function to test your installation; in the example, the function will use the runtime plc_python_shared:

postgres=# CREATE FUNCTION dummyPython() RETURNS text AS $$
# container: plc_python_shared
return 'hello from Python'
$$ LANGUAGE plcontainer;

And test the function using:

postgres=# SELECT dummyPython();
    dummypython    
-------------------
 hello from Python
(1 row)

postgres=# CREATE FUNCTION dummyR() RETURNS text AS $$
# container: plc_r_shared
return ('hello from R')
$$ LANGUAGE plcontainer;
CREATE FUNCTION
postgres=# select dummyR();
    dummyr    
--------------
 hello from R
(1 row)

For further details and examples about using PL/Container functions, see PL/Container Functions .