Run YAML

VESSL Run is configured through a single YAML file.

Field types

Metadata

name, description, and tags fields are the metadata of Run. They should be ideally represent the specific characteristics or purposes of your run for better identification.

Name	Type	Required	Description
name	string	Required	The name of the run.
description	string	Optional	The description of the run.
tags	list	Optional	The tags of the run.

Specify run metadata

name: stable-diffusion
description: This is the inference example of stable diffusion.
tags:
- "best"
- "A100-80g"
- "20epochs"

Resources

resources specifies the resource specs to use for run. Use preset provided by VESSL or request the desired resource with requests.

0. Common fields

Name	Type	Required	Description
cluster	string	Optional	The cluster to be used for the run. (default: VESSL-managed cluster)
node_names	list	Optional	Specify candidate nodes for workload assignment. If it’s not set, we’ll find any available node.

1. Using preset with common fields

Name	Type	Required	Description
preset	string	Required without requests	The name of resource spec preset that specified in VESSL. If the preset is not specified, we will offer the best option for you based on reqeusts.

Run resource specs with preset

resources:
  cluster: vessl-gcp-oregon
  preset: gpu-l4-small

2. Using requests with common fields (Upcomming feature)

Name	Type	Required	Description
requests	map	Required without preset	The desired resource specs.
cpu	string	Optional	The number of cpu cores.
memory	string	Optional	The memory size in GB.
nvidia.com/gpu	map	Optional	The device_type and quanity of the NVIDIA GPU to be used for the run.

Run resource specs with requests

resources:
  cluster: vessl-gcp-oregon
  requests:
    cpu: "4"
    memory: 12Gi
    nvidia.com/gpu:
      device_type: V100
      quantity: "2"

You can list available clusters or resource specs with the CLI command: vessl cluster list or vessl resource list.

List VESSL clusters

pip install vessl
vessl cluster list

Container Image

The image field is a string that specifies the container image to be used in the run. This is typically a Docker image that includes all the necessary dependencies and environment for your machine learning model.

Name	Type	Required	Description
image	string or map	Requried	Container image url or map of url and credential_name.
url	string	Optional	Container image url.
credential_name	string	Optional	Registered credential name at VESSL for private image usage.

Use a VESSL-managed image

image: quay.io/vessl-ai/torch:2.3.1-cuda12.1-r5

You can list available VESSL-managed images with the CLI command: vessl image list.

List VESSL-manged images with the VESSL CLI

pip install vessl
vessl image list

Volumes

There are three type of volumes: import, mount, and export. Each field is a map that specifies a target path as a key and a source information as a value. The value is either a simple string with prefix or another map that holds more detailed information.

1. Import The import type signifies that the data will be downloaded from the source to a target path in the running container.

Prefix	Type	Required	Description
git://	string	Optional	Import a git repository. The repository will be cloned into the specified target path when container starts.
vessl-dataset://	string	Optional	Import a dataset stored in VESSL Dataset.
vessl-model://	string	Optional	Import a model stored in VESSL Model Registry.
vessl-artifact://	string	Optional	Import an artifact stored in VESSL Artifact.
s3://	string	Optional	Import an AWS S3 bucket.
gs://	string	Optional	Import a Google Cloud Storage.

String import value with prefix

import:
  /import/code: git://github.com/{accountName}/{repoName}
  /import/dataset: vessl-dataset://{organizationName}/{datasetName}
  /import/model: vessl-model://{organizationName}/{modelRepositoryName}/{modelNumber}
  /import/artifact: vessl-artifact://{organiztionName}/{projectName}/{artifactName}
  /import/s3: s3://{bucketName}/{path}
  /import/gs: gs://{buckeName}/{path}

2. Mount The mount type means that the data will be directly mounted to a target path in the run container, providing direct access to the user.

Prefix	Type	Required	Description
vessl-dataset://	string	Optional	Mount a dataset stored in VESSL Dataset.
hostpath://	string	Optional	Mount a file or directory from the host node’s filesystem.
nfs://	string	Optional	Mount a Network File System(NFS).
readonly	boolean	Optional	True if readonly mode. (default: True)

String mount value with prefix

mount:
  /mount/dataset: vessl-dataset://{organizationName}/{datasetName}
  /mount/hostpath: hostpath://{path}
  /mount/nfs: nfs://{server}/{path}

3. Export The export type is desgined for uploading data from a path in the run container to a target path after run execution.

Prefix	Type	Required	Description
vessl-artifact://	string	Optional	Export to VESSL Artifact.
vessl-dataset://	string	Optional	Export to VESSL Dataset.
vessl-model://	string	Optional	Export to VESSL Model.
s3://	string	Optional	Export to Amazon S3 bucket.
gs://	string	Optional	Export to Google Cloud Storage.

String export value with prefix

export:
  /export/output-artifact: vessl-artifact://
  /export/backup-artifact: vessl-artifact://{organizationName}/{projectName}/{artifactName}
  /export/dataset: vessl-dataset://{organizationName}/{datasetName}
  /export/model: vessl-model://{organizationName}/{modelRepositoryName}
  /export/s3: s3://{buckeName}/{prefix}
  /export/gs: gs://{bucketName}/{prefix}

Run Command

The run field is a list that contains commands to be run in the container. Each item in the list is a map with the following keys. run could be empty if it’s an interactive run.

Name	Type	Required	Description
workdir	string	Optional	The working directory for the command.
command	string	Required	The command to be run.
wait	string	Optional	How long to wait after a command.

Run a single command

run:
  - command: |
      python train.py --learning_rate=$learning_rate --batch_size=$batch_size

Interactive

The interactive field is used to specify if the run allows interactive communication with the user. It provides multiple ways to interact with the container during the run, such as JupyterLab, SSH, or a custom service via specified ports.

Name	Type	Required	Description
interactive	map	Optional	Mark run as an interactive type that includes max_runtime, jupyter, and idle_timeout
max_runtime	string	Required	The amount of time to run. Set 0 for infintie use.
jupyter	map	Required	Jupyter configurations that includes idle_timeout
idle_timeout	string	Required	The amount of time a server can be inactive before it will be culled.

Maximum runtime 24h and idle_timeout 120m

interactive:
  max_runtime: 24h
  jupyter:
    idle_timeout: 120m

Ports

The ports field is a list of map that specifies the port information to expose.

Name	Type	Required	Description
ports	list	Optional	List of port numbers or port information that includes name, type, and port to expose.
name	string	Optional	The port name.
type	string	Optional	The protocol of port. (http or tcp)
port	int	Optional	The port number.

Expose port by number

ports:
  - 3000

Environment Variables

The env field is a map that specifies the environment variables for the run. Each key-value pair in this map represents an environment variable and its value.

Name	Type	Required	Description
env	map	Optional	Key-value pairs for environment variables in the run container.
value	string	Optional	Value of environment variables.
secret	boolean	Optional	True if the variable is secret.

Set multiple environment variables

env:
  learning_rate: 0.001
  postgres_password:
    value: OUR_DB_PW
    secret: true