# Workspace Templates

This section explains how to create workspace templates for reuse during workload submission. To manage templates, see [Workload Templates](https://run-ai-docs.nvidia.com/self-hosted/2.22/workloads-in-nvidia-run-ai/workload-templates).

{% hint style="info" %}
**Note**

**Flexible workload templates** is disabled by default and requires **Flexible workload submission** to be enabled. If unavailable, your administrator must enable both settings under **General settings** → Workloads → Flexible workload submission and Flexible workload templates.
{% endhint %}

## Adding a New Template

1. To add a new template, go to Workload manager → Templates.
2. Click **+NEW TEMPLATE** and select **Workspace** from the dropdown menu**.**
3. Within the new workspace template form, select the **scope**.
4. Enter a unique **name** for the workspace template. If the name already exists in the project, you will be requested to submit a different name.
5. Click **CONTINUE**

### Setting Up an Environment

**Load from existing setup**

1. Click the **load** icon. A side pane appears, displaying a list of available environments. Select an environment from the list.
2. Optionally, customize any of the environment's predefined fields as shown below. The changes will apply to this template only and will not affect the selected environment.
3. Alternatively, click the **➕** icon in the side pane to create a new environment. For step-by-step instructions, see [Environments](https://run-ai-docs.nvidia.com/self-hosted/2.22/workloads-in-nvidia-run-ai/assets/environments).

**Provide your own settings**

Manually configure the settings below as needed.

**Configure environment**

1. Add the **Image URL** or update the URL of the existing setup.
2. Set the condition for pulling the image by selecting the **image pull policy**. It is recommended to pull the image only if it's not already present on the host.
3. Set the connection for your **tool(s)**. If you are loading from existing setup, the tools are configured as part of the environment.
   * Select the connection type - **External URL** or **NodePort:**
     * **Auto generate** - A unique URL / port is automatically created for each workload using the environment.
     * **Custom URL** / **Custom port** - Manually define the URL or port. For custom port, make sure to enter a port between `30000` and `32767.` If the node port is already in use, the workload will fail and display an error message.
   * Modify who can **access** the tool:
     * By default, **All authenticated users** is selected giving access to everyone within the organization's account.
     * For **Specific group(s)**, enter **group names** as they appear in your identity provider. You must be a member of one of the groups listed to have access to the tool.
     * For **Specific user(s)**, enter a valid email address or username. If you remove yourself, you will lose access to the tool.
4. Set the **command and arguments** for the container running the workspace. If no command is added, the container will use the image's default command (entry-point):
   * Modify the existing command or click **+COMMAND & ARGUMENTS** to add a new command.
   * Set multiple arguments separated by spaces, using the following format (e.g.: `--arg1=val1`).
5. Set the **environment variable(s)**:
   * Modify the existing environment variable(s) or click **+ENVIRONMENT VARIABLE**. The existing environment variables may include instructions to guide you with entering the correct values.
   * You can either select **Custom** to define your own variable or choose from a predefined list of [**Secrets**](https://run-ai-docs.nvidia.com/self-hosted/2.22/assets/credentials#creating-secrets-in-advance) or [**ConfigMaps**](https://run-ai-docs.nvidia.com/self-hosted/2.22/assets/datasources#creating-configmaps-in-advance).
6. Enter a path pointing to the **container's working directory**.
7. Set where the UID, GID, and supplementary groups for the container should be taken from. If you select **Custom**, you'll need to manually enter the **UID,** **GID and** **Supplementary groups values.**
8. Select additional Linux capabilities for the container from the dropdown menu. This grants certain privileges to a container without granting all the root user's privileges.

### Setting Up Compute Resources

{% hint style="info" %}
**Note**

GPU memory limit is disabled by default. If unavailable, your administrator must enable it under **General settings** → Resources → GPU resource optimization.
{% endhint %}

**Load from existing setup**

1. Click the **load** icon. A side pane appears, displaying a list of available compute resources. Select a compute resource from the list.
2. Optionally, customize any of the compute resource's predefined fields. The changes will apply to this template only and will not affect the selected compute resource.
3. Alternatively, click the **➕** icon in the side pane to create a new compute resource. For step-by-step instructions, see [Compute resources](https://run-ai-docs.nvidia.com/self-hosted/2.22/workloads-in-nvidia-run-ai/assets/compute-resources).

**Provide your own settings**

Manually configure the settings below as needed.

**Configure compute resources**

1. Set the number of **GPU devices** per pod (physical GPUs).
2. Enable **GPU fractioning** to set the GPU memory per device using either a fraction of a GPU device's memory **(% of device)** or a GPU memory unit **(MB/GB)**:
   * **Request** - The minimum GPU memory allocated per device. Each pod in the workspace receives at least this amount per device it uses.
   * **Limit** - The maximum GPU memory allocated per device. Each pod in the workspace receives **at most** this amount of GPU memory for each device(s) the pod utilizes. This is disabled by default, to enable see the above note.
3. Set the **CPU resources**
   * Set **CPU compute resources** per pod by choosing the unit (**cores** or **millicores**):
     * **Request** - The minimum amount of CPU compute provisioned per pod. Each running pod receives this amount of CPU compute.
     * **Limit** - The maximum amount of CPU compute a pod can use. Each pod receives **at most** this amount of CPU compute. By default, the limit is set to **Auto** which means that the pod may consume up to the node's maximum available CPU compute resources.
   * Set the **CPU memory per pod** by selecting the unit (**MB** or **GB**):
     * **Request** - The minimum amount of CPU memory provisioned per pod. Each running pod receives this amount of CPU memory.
     * **Limit** - The maximum amount of CPU memory a pod can use. Each pod receives at most this amount of CPU memory. By default, the limit is set to **Auto** which means that the pod may consume up to the node's maximum available CPU memory resources.
4. Set **extended resource(s)**
   * Enable **Increase shared memory size** to allow the shared memory size available to the pod to increase from the default 64MB to the node's total available memory or the CPU memory limit, if set above.
   * Click **+EXTENDED RESOURCES** to add resource/quantity pairs. For more information on how to set extended resources, see the [Extended resources](https://kubernetes.io/docs/tasks/configure-pod-container/extended-resource/) and [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) guides.
5. Click **+TOLERATION** to allow the workspace to be scheduled on a node with a matching taint. Select the **operator** and the **effect**:
   * If you select **Exists**, the effect will be applied if the key exists on the node.
   * If you select **Equals**, the effect will be applied if the key and the value set match the value on the node.

### Setting Up Data & Storage

{% hint style="info" %}
**Note**

* Data volumes is disabled by default. If unavailable, your administrator must enable it under **General settings** → Workloads → Data volumes.
* If Data volumes is not enabled, **Data & storage** appears as **Data sources** only, and no data volumes will be available.
  {% endhint %}

**Load from existing setup**

1. Click the **load** icon. A side pane appears, displaying a list of available data sources/volumes. Select a data source/volume from the list.
2. Optionally, customize any of the data source's predefined fields as shown below. The changes will apply to this template only and will not affect the selected data source:
   * **Container path** - Enter the **container path** to set the **data target location**.
   * **ConfigMap** **sub-path** - Specify a **sub-path** (file/key) inside the ConfigMap to mount (for example, `app.properties`). This lets you mount a single file from an existing ConfigMap.
3. Alternatively, click the **➕** icon in the side pane to create a new data source/data volume. For step-by-step instructions, see [Data sources](https://run-ai-docs.nvidia.com/self-hosted/2.22/workloads-in-nvidia-run-ai/assets/datasources) or [Data volumes](https://run-ai-docs.nvidia.com/self-hosted/2.22/workloads-in-nvidia-run-ai/assets/data-volumes).

**Configure data sources for a one-time configuration**

{% hint style="info" %}
**Note**

[PVCs](https://run-ai-docs.nvidia.com/self-hosted/2.22/assets/datasources#pvc), [Secrets](https://run-ai-docs.nvidia.com/self-hosted/2.22/assets/datasources#secret), [ConfigMaps](https://run-ai-docs.nvidia.com/self-hosted/2.22/assets/datasources#configmap) and [Data volumes](https://run-ai-docs.nvidia.com/self-hosted/2.22/workloads-in-nvidia-run-ai/assets/data-volumes) cannot be added as a one-time configuration.
{% endhint %}

1. Click the **➕** icon and choose the data source from the dropdown menu. You can add multiple data sources.
2. Once selected, set the **data origin** according to the required fields and enter the **container path** to set the **data target location**.
3. Select **Volume** to allocate a storage space to your workspace that is persistent across restarts:
   * Set the **Storage class** to **None** or select an existing storage class from the list. To add new storage classes, and for additional information, see [Kubernetes storage classes](https://run-ai-docs.nvidia.com/self-hosted/2.22/infrastructure-setup/procedures/shared-storage). If the administrator defined the storage class configuration, the rest of the fields will appear accordingly.
   * Select one or more **access mode(s)** and define the **claim size** and its **units**.
   * Select the **volume mode.** If you select **Filesystem** (default), the volume will be mounted as a filesystem, enabling the usage of directories and files. If you select **Block**, the volume is exposed as a block storage, which can be formatted or used directly by applications without a filesystem.
   * Set the **Container path** with the volume target location.
   * Set the volume persistency to **Persistent** if the volume and its data should be deleted when the workspace is deleted or **Ephemeral** if the volume and its data should be deleted every time the workspace's status changes to “Stopped”.

### Setting Up General Settings

{% hint style="info" %}
**Note**

The following general settings are optional.
{% endhint %}

1. Set the **workload priority**. Choose the appropriate priority level for the workload. Higher-priority workloads are scheduled before lower-priority ones. See [Workload priority control](https://run-ai-docs.nvidia.com/self-hosted/2.22/platform-management/runai-scheduler/scheduling/workload-priority-control) for more details.
2. Set the **grace period** for workload preemption. This is a buffer that allows a preempted workload to reach a safe checkpoint before it is forcibly preempted. Enter a timeframe between 0 sec and 5 min.
3. Set the **backoff limit** before workload failure. The backoff limit is the maximum number of retry attempts for failed workloads. After reaching the limit, the workload status will change to "Failed." Enter a value between 0 and 100.
4. Set the **timeframe for auto-deletion** after workload completion or failure. The time after which a completed or failed workload is deleted; if this field is set to 0 seconds, the workload will be deleted automatically. This setting does not affect log retention. Log retention is managed separately.
5. Set **annotations(s).** Kubernetes annotations are key-value pairs attached to the workload. They are used for storing additional descriptive metadata to enable documentation, monitoring and automation.
6. Set **labels(s).** Kubernetes labels are key-value pairs attached to the workload. They are used for categorizing to enable querying

### Completing the Template

1. Before finalizing your template, review your configurations and make any necessary adjustments.
2. Click **CREATE TEMPLATE**

## Using API

Go to the [Workload templates](https://run-ai-docs.nvidia.com/api/2.22/workloads/workload-templates) API reference to view the available actions.