Deploy Teradata Jupyter extensions to JupyterHub

Author: Hailing Jiang
Last updated: November 17th, 2021

Overview

For customers who have their own JupyterHub clusters, there are two options to integrate Teradata Jupyter extensions into the existing clusters:

  1. Use Teradata Jupyter Docker image.

  2. Customize an existing Docker image to include Teradata extensions.

This page contains detailed instructions on the two options. Instructions are based on the assumption that the customer JupyterHub deployment is based on Zero to JupyterHub with Kubernetes.

If you need a new instance of Vantage, you can install a free version called Vantage Express in the cloud on Google Cloud, Azure, and AWS. You can also run Vantage Express on your local machine using VMware, VirtualBox, or UTM.

Use Teradata Jupyter Docker image

Teradata provides a ready-to-run Docker image that builds on the jupyter/datascience-notebook image. It bundles the Teradata SQL kernel, Teradata Python and R libraries and drivers and Teradata extensions for Jupyter to make you productive while interacting with Teradata database. The image also contains sample notebooks that demonstrate how to use the SQL kernel, extensions and Teradata libraries.

You can use this image in the following ways:

  • Start a personal Jupyter Notebook server in a local Docker container

  • Run JupyterLab servers for a team using JupyterHub

For instructions to start a personal JupyterLab server in a local Docker container, please see installation guide. This section will focus on how to use the  Teradata Jupyter Docker image in a customer’s existing JupyterHub environment.

Install Teradata Jupyter Docker image in your registry

  1. Go to Vantage Modules for Jupyter page and download the Docker image. It is a tarball with name in this format teradatajupyterlabext_VERSION.tar.gz.

  2. Load the image:

    docker load -i teradatajupyterlabext_VERSION.tar.gz
  3. Push the image to your Docker registry:

    docker push

    You may want to consider changing the name of the loaded image for simplicity:

    docker tag OLD_IMAGE_NAME NEW_IMAGE_NAME

Use Teradata Jupyter Docker image in JupyterHub

  1. To use the Teradata Jupyter Docker image directly in your JupyterHub cluster, modify the override file as described in herein the JupyterHub documentation. Replace REGISTRY_URL and VERSION with appropriate values from the step above:

    singleuser:
      image:
      name: REGISTRY_URL/teradatajupyterlabext_VERSION
      tag: latest
  2. Apply the changes to the cluster as described in JupyterHub documentation.

    You can use multiple profiles to allow users to select which image they want to use when they log in to JupyterHub. For detailed instructions and examples on configuring multiple profiles, please see JupyterHub documentation.

Customize Teradata Jupyter Docker image

If your users need some packages or notebooks that are not bundled in the Teradata Jupyter Docker image, we recommend that you use Teradata image as a base image and build a new one on top of it.

Here is an example Dockerfile that builds on top of Teradata image and adds additional packages and notebooks. Use the Dockerfile to build a new Docker image, push the image to a designated registry, modify override file as shown above to use the new image as singleuser image, apply the changes to the cluster as described above. Replace REGISTRY_URL and VERSION with appropriate values:

FROM REGISTRY_URL/teradatajupyterlabext_VERSION:latest

# install additional packages
RUN pip install --no-cache-dir astropy

# copy notebooks
COPY notebooks/. /tmp/JupyterLabRoot/DemoNotebooks/

Customize an existing Docker image to include Teradata extensions

If you prefer, you can include the Teradata SQL kernel and extensions into into an existing image you are currently using.

  1. Go to Vantage Modules for Jupyter page to download the zipped Teradata Jupyter extensions package bundle.  Assuming your existing docker image is Linux based, you will want to use the Linux version of the download.  Otherwise, download for the platform you are using.  The .zip file contains the Teradata SQL Kernel, extensions and sample notebooks.

  2. Unzip the bundle file to your working directory.

  3. Below is an example Dockerfile to add Teradata Jupyter extensions to your existing Docker image. Use the Dockerfile to build a new Docker image, push the image to a designated registry, modify override file as shown above to use the new image as singleuser image, apply the changes to the cluster:

    FROM REGISTRY_URL/your-existing-image:tag
    ENV NB_USER=jovyan \
      HOME=/home/jovyan \
      EXT_DIR=/opt/teradata/jupyterext/packages
    
    USER root
    
    ##############################################################
    # Install kernel and copy supporting files
    ##############################################################
    
    # Copy the kernel
    COPY ./teradatakernel /usr/local/bin
    RUN chmod 755 /usr/local/bin/teradatakernel
    
    # Copy directory with kernel.json file into image
    COPY ./teradatasql teradatasql/
    
    ##############################################################
    # Switch to user jovyan to copy the notebooks and license files.
    ##############################################################
    
    USER $NB_USER
    
    # Copy notebooks
    COPY ./notebooks/ /tmp/JupyterLabRoot/TeradataSampleNotebooks/
    
    # Copy license files
    COPY ./ThirdPartyLicenses /tmp/JupyterLabRoot/ThirdPartyLicenses/
    
    USER root
    
    # Install the kernel file to /opt/conda jupyter lab instance
    RUN jupyter kernelspec install ./teradatasql --prefix=/opt/conda
    
    ##############################################################
    # Install Teradata extensions
    ##############################################################
    
    COPY ./teradata_*.tgz $EXT_DIR
    
    WORKDIR $EXT_DIR
    
    RUN jupyter labextension install --no-build teradata_database* && \
      jupyter labextension install --no-build teradata_resultset* && \
      jupyter labextension install --no-build teradata_sqlhighlighter* && \
      jupyter labextension install --no-build teradata_connection_manager* && \
      jupyter labextension install --no-build teradata_preferences* && \
      jupyter lab build --dev-build=False --minimize=False && \
      rm -rf *
    
    WORKDIR $HOME
    
    # Give back ownership of /opt/conda to  jovyan
    RUN chown -R jovyan:users /opt/conda
    
    # Jupyter will create .local directory
    RUN rm -rf $HOME/.local
  4. You can optionally install Teradata package for Python and Teradata package for R. See the following pages for details:

Did this page help?