How to Use Custom Containers in Gradient Workflowsprivate

Gradient uses containers to create consistent, reproducible environments for your workloads. Containers define the runtime and dependencies that Gradient uses when running your code.

You can use one of Gradient’s preconfigured containers, a public container image, or your own private image.

Add a Container Registry

You can store credentials for private container registries in Gradient so they can be reused across your environment.

In the Gradient console, in the top-right corner, click your profile image, select Team Settings, and then click the Containers tab.

From the Containers page, you can add, edit, or delete registry connections.

Create a Container Registry Connection

To create a registry connection, click Add Registry, select the registry type, and then type the required credentials for that registry.

After saving, you can reference the registry by name in your configuration file or container spec.

Configure Container Registry

The following examples show how to connect different container registries to Gradient. Each example outlines the credentials required for that registry and how to reference the registry name in your container configuration.

image: registry.digitalocean.com/your-registry-name/image:tag
containerRegistry: My-Example-DO-Registry

image: example-repository/streamlit-app:latest
containerRegistry: My-Example-DockerHub-Repository

image: us-west1-docker.pkg.dev/project-name/repo-name/image:tag
containerRegistry: My-Example-GCR

image: ghcr.io/example-org/streamlit-app:latest
containerRegistry: My-Example-GHCR

image: example-registry.azurecr.io/streamlit-app:latest
containerRegistry: My-Example-ACR

Use Your Container

You can specify a container image directly in your YAML spec to define the environment for each step.

To use a public TensorFlow container, specify a container image like this:

image: tensorflow/tensorflow:2.7.0-gpu-jupyter

Gradient then automatically pulls and manages this image when your Workflow runs. To learn more, see the Workflow spec reference.

Build a Custom Container

You can build a custom Docker container and push it to a container registry, such as Docker Hub, DigitalOcean Container Registry, or NGC, for use in Gradient. Custom containers let you define the exact runtime, dependencies, and environment needed for your workloads.

Before you use a custom container, you need to create a machine with Docker CE, NVIDIA Docker, and NVIDIA drivers installed. These tools ensure your image is compatible with the GPU runtimes and dependencies that Gradient uses when running containers.

If your local environment doesn’t meet these requirements, you can use a Paperspace Linux-based machine instead.

Access Your Docker Hub

To access your Docker Hub, run the following command with your Docker Hub credentials like this:

docker login -u <username> -p <password>

Create a Dockerfile

After accessing your Docker Hub, create a Dockerfile to define your container’s environment, dependencies, and startup commands like this:

git clone https://github.com/gradient-ai/tensorflow-python
cd tensorflow-python

In this example, the image is a Paperspace-built TensorFlow 2.0 container optimized for GPU workloads.

You can modify the Dockerfile to include any additional dependencies or setup steps your application requires.

Build the Image

In the same directory as your Dockerfile, build your image with the following command:

docker build -t test-container .

Then, tag your image before pushing it to a registry like this:

docker tag test-container <docker-username>/test-container:latest

Push the Image

To push the image to your container registry, run the following command:

docker push <docker-username>/test-container:latest

Reference Your Custom Container

After your container is pushed to a registry, reference it in your configuration file or container spec like this:

image: <docker-username>/test-container:latest
containerRegistry: <your-registry-name>

Gradient then automatically pulls and runs the container in your environment.

Bring Your Custom Container to Workflows

You can use custom containers in Gradient Workflows to control the runtime environment for each step. This lets you include specific frameworks, libraries, or dependencies that your workflow needs.

When defining your Workflow step:

• For public images, specify the container path using the image key like this:

  image: paperspace/gradient-sdk

• For private images, specify both the image and containerRegistry keys to reference your saved registry credentials like this:

  image: registry.digitalocean.com/example-registry/my-image:latest
  containerRegistry: My-Example-DO-Registry

The value of containerRegistry must match the name of the registry connection you created in the Create a Registry Connection section above.

Learn more about structuring and managing Workflow steps in the Workflows overview.