> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.        |

```yaml Specify run metadata theme={null}
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`. |

<CodeGroup>
  ```yaml Run resource specs with preset theme={null}
  resources:
    cluster: vessl-oci-sanjose
    preset: gpu-l4-small
  ```

  ```yaml Run resource specs with preset and node candidates theme={null}
  resources:
    cluster: my-on-premises-cluster
    preset: v100-1
    node_names:
      - "n01"
      - "n03"
      - "n04"
  ```
</CodeGroup>

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. |

<CodeGroup>
  ```yaml Run resource specs with requests theme={null}
  resources:
    cluster: vessl-oci-sanjose
    requests:
      cpu: "4"
      memory: 12Gi
      nvidia.com/gpu:
        device_type: V100
        quantity: "2"
  ```

  ```yaml Run resource specs with requests and node candidates theme={null}
  resources:
    cluster: my-on-premises-cluster
    requests:
      cpu: "4"
      memory: 12Gi
      nvidia.com/gpu:
        device_type: V100
        quantity: "2"
    node_names:
     - "n01"
     - "n03"
     - "n04"
  ```
</CodeGroup>

<Tip>You can list available clusters or resource specs with the CLI command: `vessl cluster list` or  `vessl resource list`.</Tip>

<CodeGroup>
  ```bash List VESSL clusters theme={null}
  pip install vessl
  vessl cluster list
  ```

  ```bash List resource specs theme={null}
  pip install vessl
  vessl resource list
  ```
</CodeGroup>

### 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. |

<CodeGroup>
  ```yaml Use a VESSL-managed image theme={null}
  image: quay.io/vessl-ai/torch:2.3.1-cuda12.1-r5
  ```

  ```yaml Use a public custom image theme={null}
  image: my-docker-account/public-repo-name:tag-name
  ```

  ```yaml Use a private custom image theme={null}
  image:
    url: my-docker-account/private-repo-name:tag-name
    credential_name: docker_hub_cred
  ```
</CodeGroup>

<Tip>You can list available VESSL-managed images with the CLI command: `vessl image list`.</Tip>

```bash List VESSL-manged images with the VESSL CLI theme={null}
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.                                                                               |

<CodeGroup>
  ```yaml String import value with prefix theme={null}
  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}
  ```

  ```yaml Verbose import value theme={null}
  import:
    /import/code:
      git:
        url: https://github.com/{accountName}/{repoName}
        ref: c0ffee
        credential_name: my-git-cred-name
    /import/dataset:
      dataset:
        organization_name: {organizationName}
        dataset_name: {datasetName}
    /import/model:
      model:
        organization_name: {organizationName}
        model_repository_name: {modelRepositoryName}
        model_number: {modelNumber}
    /import/artifact:
      artifact:
        organization_name: {organizationName}
        project_name: {projectName}
        name: {artifactName}
    /import/artifact-same-project:
      artifact:
        name: {artifactName}
    /import/s3:
      s3:
        bucket: {bucketName}
        prefix: {prefix}
        credential_name: my-s3-cred-name
    /import/gs:
      gs:
        bucket: {bucketName}
        prefix: {prefix}
        credential_name: my-gs-cred-name
  ```
</CodeGroup>

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)                     |

<CodeGroup>
  ```yaml String mount value with prefix theme={null}
  mount:
    /mount/dataset: vessl-dataset://{organizationName}/{datasetName}
    /mount/hostpath: hostpath://{path}
    /mount/nfs: nfs://{server}/{path}
  ```

  ```yaml Verbose mount value theme={null}
  mount:
    /mount/dataset:
      dataset:
        organization_name: {organizationName}
        dataset_name: {datasetName}
    /mount/hostpath:
      hostpath:
        path: {path}
      readonly: true
    /mount/nfs:
      nfs:
        server: {server}
        path: {path}
      readonly: false
  ```
</CodeGroup>

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. |

<CodeGroup>
  ```yaml String export value with prefix theme={null}
  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}
  ```

  ```yaml Verbose export value theme={null}
  export:
    /export/output-artifact:
      artifact:
    /export/backup-artifact:
      artifact:
        organization_name: {organizationName}
        project_name: {projectName}
        artifact_name: {artifactName}
    /export/dataset:
      dataset:
        organization_name: {organizationName}
        dataset_name: {datasetName}
    /export/model:
      model:
        organization_name: {organizationName}
        model_repository_name: {modelRepositoryName}
    /export/s3:
      s3:
        bucket: {bucketName}
        prefix: {prefix}
        endpoint: in-house.endpoint.co.kr
        credential_name: my-s3-cred-name
    /export/gs:
      gs:
        bucket: {bucketName}
        prefix: {prefix}
        credential_name: my-gs-cred-name
  ```
</CodeGroup>

### 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.      |

<CodeGroup>
  ```yaml Run a single command theme={null}
  run:
    - command: |
        python train.py --learning_rate=$learning_rate --batch_size=$batch_size
  ```

  ```yaml Run multiple commands theme={null}
  run:
    - workdir: /input/data1
      command: |
        python data_preprocessing.py
    - wait: 10s
    - workdir: /root/git-examples
      command: |
        python train.py --learning_rate=$learning_rate --batch_size=$batch_size
  ```
</CodeGroup>

### 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.                      |

```yaml Maximum runtime 24h and idle_timeout 120m theme={null}
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.                                                                             |

<CodeGroup>
  ```yaml Expose port by number theme={null}
  ports:
    - 3000
  ```

  ```yaml Expose port by name, number, and type theme={null}
  ports:
    - name: streamlit
      type: http
      port: 8501
  ```
</CodeGroup>

### 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.                                 |

```yaml Set multiple environment variables theme={null}
env:
  learning_rate: 0.001
  postgres_password:
    value: OUR_DB_PW
    secret: true
```