Container Management
This guide explains how to manage containers in Gradient to ensure reproducible results when using Notebooks, Workflows, and Deployments.
Overview​
Whether you are using Notebooks, Workflows, or Deployments, Gradient uses containers to provide a reproducible code execution environment.
In the case of notebooks, you can either use a preconfigured container or bring your own container. To learn more about that, see the Notebook Runtimes page.
For Workflows and Deployments, you can either use public containers or private containers to set up your environment. With public containers (for example tensorflow/tensorflow:2.7.0-gpu-jupyter if you wanted to use a generic Tensorflow environment) Gradient takes care of everything once you specify that as the image for your Workflow job. Learn more about Workflow specs on the Workflow specs page.
You can also use a private container in your Workflows and Deployments. Gradient makes it easy to store and manage your private container registry credentials which you can learn about below.
Container Registries​
You can store credentials for future use in Gradient resources through the Containers tab in your team settings. Access your team settings by clicking on your user image in the top right of the console.
Within the Containers tab you can add new container registries as well as edit or delete your existing registries.
Creating a New Container Registry Entry​
To create a new container registry connection, simply click the Add a New Container Registry button to generate the entry form that will allow you to enter in the following information:
name- This field is used to identify your registry across Paperspace resources and must be unique to your team.url- The url associated with the container registry. For example, if your container is hosted on Docker Hub, your url would behttps://index.docker.io/v1/. This supports an entire base url so you can use self-hosted options or cloud registries like Google Container Registry (GCR) that path mount your registry endpoint likegcr.io/my-project.namespace- This is the unique location within your registry outlining the location of your repository. This can include namespaces and sub-namespaces.
username- This is your username or ID login credential for the registry.password- This is your password or access key login credential for the registry. Where applicable, it is recommended you use an Access Token as your password.
Check this out to learn more about docker registries.
Additional Container Registry Examples​
Docker Hub
This is an example of how to register a Docker Hub container within Gradient. If the container you are trying to use is located in Docker Hub at example-repository/streamlit-app:latest then the following would be entered into each field:
After you have set up your container registry connection, you can reference the container in a deployment spec using:
Google Container Registry
This is an example of how to register a Google container within Gradient. If the container you are trying to use is located at http://us.gcr.io/example-project/streamlit-app/app-1:latest then the following would be entered into each field:
After you have set up your container registry connection, you can reference the container in a deployment spec using:
GitHub Container Registry
This is an example of how to register a GitHub container within Gradient. If the container you are trying to use is located at https://ghcr.io/example-org/streamlit-app:latest then the following would be entered into each field:
After you have set up your container registry connection, you can reference the container in a deployment spec using:
Azure Container Registry
This is an example of how to register an Azure container within Gradient. If the container you are trying to use is located at https://example-registry.azurecr.io/streamlit-app:latest then the following would be entered into each field:
After you have set up your container registry connection, you can reference the container in a deployment spec using:
Build a Custom Container​
Overview​
In this section we'll walk you through how to create a custom Docker container that you can push to a container registry like Docker Hub, and load that container into Gradient through a notebook, workflow, or deployment.
ProTip! Using a custom container does not require building one from scratch. See this article to access many freely available and up-to-date containers hosted on various container registries like Docker Hub, NGC, etc.
Getting Started​
You will need a computer with DockerCE, NVIDIA-docker, and NVIDIA Drivers installed. If you don't have an appropriate machine, you can use a Paperspace Linux machine.
From that machine, you'll need to log into your Docker Hub account using the following command in the terminal:
docker login -u <username> -p <password>
You can make your own Dockerfile from scratch or use another as a template, such as this example. For now, let's follow this provided sample.
Creating a Dockerfile on Your Machine​
First, clone the repo to your machine and navigate to the corresponding directory in your terminal:
git clone https://github.com/gradient-ai/tensorflow-python && cd tensorflow-python
Open the Dockerfile in the IDE of your choice and make edits as necessary. The provided Dockerfile sampled above pulls from Docker Hub a Paperspace-made TensorFlow image designed to run TensorFlow 2.0 on Paperspace GPUs.
Once your Dockerfile is updated, save it, and navigate back to the terminal.
Building the Docker Image​
Now that the Dockerfile is created, navigate in your terminal to the same directory your Dockerfile exists and build the image by running:
docker build -t <Name of image> .
Example: docker build test-container
Once you have created the image, you need to tag it so that it can be pushed to your Docker Hub repository. Tag the image using the image id or image name from the image you just created, your Docker Hub username, a name for the image, and a tag in the following format:
docker tag <Image ID/Image name> <Docker username>/<Image name>:<Tag>
Example: docker tag test-container paperspace/test-container:latest
Pushing to Docker Hub​
Now that we have created and tagged our container, we can push it to Docker Hub and use it within Gradient resources. Use the following docker push command to do so:
docker push <Docker username>/<Image name>:<Tag>
Bringing your Custom Container to Gradient​
After you've pushed your custom container to Docker Hub, NGC, etc., or you found a public container that is already there, it's time to pull it into Gradient!
Notebooks​
To run your image using Gradient Notebooks, click the Advanced options toggle on the Notebook create page. Follow the rest of the steps here to create your Notebook.
Container Requirements for Gradient Notebooks​
To run a custom container using a Gradient Notebook, JupyterLab must be installed on the image. The following are commands you can run in your Dockerfile to ensure the Notebook will run properly.
Dockerfile requirements- Install Python:
RUN apt-get update && apt-get install -y python3 python3-pip - Install JupyterLab:
RUN pip install jupyterlab(For more details, see http://jupyter.org/install)
Workflows​
Specify the path of the container e.g., paperspace/gradient-sdk from within a Workflow step using image. Learn more here.
Deployments​
If the image is public, specify the path to the image using the image key. If the image is private, you will also need to specify the containerRegistry which you will have setup in the Create a New Container Registry Entry section of this document.