Workspaces

A Workspace is a simplified tool for researchers to conduct experiments, build AI models, access standard MLOps tools, and collaborate with their peers. Workspaces abstract complex concepts related to running containerized workloads in a Kubernetes environment and are built from predefined setups that include networking, storage, secrets and other resources. All the setup and configurations for research, including container images, data sets, resource requests, as well as all tools are included. for the research, in a single place. It answers the research needs while ensuring infrastructure owners keep control and allocation efficiency. A workspace is associated with a specific NVIDIA Run:ai project and you can have multiple workspaces under a specific project. For more information, see Workspaces.

Create a workspace.

post

Create a new workspace in a specific project in the cluster.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

and

Responses

202

Request completed successfully.

application/json

400

Bad submission request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

503

unexpected error

application/json

post

/api/v1/workloads/workspaces

HTTPcURLJavaScriptPython

POST /api/v1/workloads/workspaces HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3673

{
  "name": "my-workload-name",
  "useGivenNameAsPrefix": true,
  "projectId": 1,
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "spec": {
    "command": "python",
    "args": "-x my-script.py",
    "image": "python:3.8",
    "imagePullPolicy": "Always",
    "workingDir": "/home/myfolder",
    "createHomeDir": true,
    "probes": {
      "readiness": {
        "initialDelaySeconds": 1,
        "periodSeconds": 1,
        "timeoutSeconds": 1,
        "successThreshold": 1,
        "failureThreshold": 1,
        "handler": {
          "httpGet": {
            "path": "/",
            "port": 1,
            "host": "example.com",
            "scheme": "HTTP"
          }
        }
      }
    },
    "nodeType": "my-node-type",
    "nodePools": [
      "my-node-pool-a",
      "my-node-pool-b"
    ],
    "podAffinity": {
      "type": "Required",
      "key": "text"
    },
    "tty": true,
    "stdin": true,
    "environmentVariables": [
      {
        "name": "HOME",
        "value": "/home/my-folder",
        "secret": {
          "name": "postgress_secret",
          "key": "POSTGRES_PASSWORD"
        },
        "exclude": false,
        "description": "Home directory of the user."
      }
    ],
    "annotations": [
      {
        "name": "billing",
        "value": "my-billing-unit",
        "exclude": false
      }
    ],
    "labels": [
      {
        "name": "stage",
        "value": "initial-research",
        "exclude": false
      }
    ],
    "tolerations": [
      {
        "name": "text",
        "operator": "Equal",
        "key": "text",
        "value": "text",
        "effect": "NoSchedule",
        "seconds": 1,
        "exclude": false
      }
    ],
    "terminateAfterPreemption": false,
    "autoDeletionTimeAfterCompletionSeconds": 15,
    "terminationGracePeriodSeconds": 20,
    "backoffLimit": 3,
    "ports": [
      {
        "container": 8080,
        "serviceType": "LoadBalancer",
        "external": 30080,
        "toolType": "pytorch",
        "toolName": "my-pytorch",
        "name": "port-instance-a"
      }
    ],
    "exposedUrls": [
      {
        "container": 8080,
        "url": "https://my-url.com",
        "authorizedUsers": [
          "user-a",
          "user-b"
        ],
        "authorizedGroups": [
          "group-a",
          "group-b"
        ],
        "toolType": "jupyter",
        "toolName": "my-pytorch",
        "name": "url-instance-a"
      }
    ],
    "relatedUrls": [
      {
        "url": "https://my-url.com",
        "type": "wandb",
        "name": "url-instance-a"
      }
    ],
    "priorityClass": "build",
    "compute": {
      "gpuDevicesRequest": 1,
      "gpuRequestType": "portion",
      "gpuPortionRequest": 0.5,
      "gpuPortionLimit": 0.5,
      "gpuMemoryRequest": "10M",
      "gpuMemoryLimit": "10M",
      "cpuCoreRequest": 0.5,
      "cpuCoreLimit": 2,
      "cpuMemoryRequest": "20M",
      "cpuMemoryLimit": "30M",
      "largeShmRequest": false,
      "extendedResources": [
        {
          "resource": "hardware-vendor.example/foo",
          "quantity": 2,
          "exclude": false
        }
      ]
    },
    "storage": {
      "dataVolume": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "mountPath": "/mnt/data"
        }
      ],
      "pvc": [
        {
          "name": "storage-instance-a",
          "path": "/container/my-claim",
          "existingPvc": false,
          "claimName": "my-claim",
          "readOnly": false,
          "ephemeral": false,
          "claimInfo": {
            "size": "1G",
            "storageClass": "my-storage-class",
            "accessModes": {
              "readWriteOnce": true,
              "readOnlyMany": false,
              "readWriteMany": false
            },
            "volumeMode": "Filesystem"
          }
        }
      ],
      "hostPath": [
        {
          "name": "storage-instance-a",
          "path": "/container/directory",
          "readOnly": true,
          "mountPath": "/local/directory",
          "mountPropagation": "None"
        }
      ],
      "nfs": [
        {
          "name": "storage-instance-a",
          "path": "/container/nfs",
          "readOnly": true,
          "server": "my.nfs.com",
          "mountPath": "/local/nfs"
        }
      ],
      "git": [
        {
          "name": "storage-instance-a",
          "repository": "https://github.com/my-git/my-repo",
          "branch": "main",
          "revision": "text",
          "path": "/container/my-repository",
          "passwordSecret": "my-password-secret",
          "secretKeyOfUser": "User",
          "secretKeyOfPassword": "Password"
        }
      ],
      "configMapVolume": [
        {
          "name": "storage-instance-a",
          "configMap": "text",
          "mountPath": "text"
        }
      ],
      "secretVolume": [
        {
          "name": "storage-instance-a",
          "mountPath": "text",
          "secret": "text"
        }
      ],
      "s3": [
        {
          "name": "storage-instance-a",
          "bucket": "my-bucket",
          "path": "/container/my-bucket",
          "url": "https://s3.amazonaws.com",
          "accessKeySecret": "my-access-key-secret",
          "secretKeyOfAccessKeyId": "AccessKeyId",
          "secretKeyOfSecretKey": "SecretKey"
        }
      ]
    },
    "security": {
      "uidGidSource": "fromTheImage",
      "capabilities": [
        "CHOWN",
        "KILL"
      ],
      "seccompProfileType": "RuntimeDefault",
      "runAsNonRoot": true,
      "readOnlyRootFilesystem": false,
      "runAsUid": 500,
      "runAsGid": 30,
      "supplementalGroups": "2,3,5,8",
      "allowPrivilegeEscalation": false,
      "hostIpc": false,
      "hostNetwork": false
    }
  }
}

{
  "name": "my-workload-name",
  "requestedName": "text",
  "workloadId": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": 1,
  "departmentId": 2,
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "createdBy": "[e-mail]",
  "createdAt": "2022-01-01T03:49:52.531Z",
  "desiredPhase": "Running",
  "actualPhase": "Creating",
  "spec": {
    "command": "python",
    "args": "-x my-script.py",
    "image": "python:3.8",
    "imagePullPolicy": "Always",
    "workingDir": "/home/myfolder",
    "createHomeDir": true,
    "probes": {
      "readiness": {
        "initialDelaySeconds": 1,
        "periodSeconds": 1,
        "timeoutSeconds": 1,
        "successThreshold": 1,
        "failureThreshold": 1,
        "handler": {
          "httpGet": {
            "path": "/",
            "port": 1,
            "host": "example.com",
            "scheme": "HTTP"
          }
        }
      }
    },
    "nodeType": "my-node-type",
    "nodePools": [
      "my-node-pool-a",
      "my-node-pool-b"
    ],
    "podAffinity": {
      "type": "Required",
      "key": "text"
    },
    "tty": true,
    "stdin": true,
    "environmentVariables": [
      {
        "name": "HOME",
        "value": "/home/my-folder",
        "secret": {
          "name": "postgress_secret",
          "key": "POSTGRES_PASSWORD"
        },
        "exclude": false,
        "description": "Home directory of the user."
      }
    ],
    "annotations": [
      {
        "name": "billing",
        "value": "my-billing-unit",
        "exclude": false
      }
    ],
    "labels": [
      {
        "name": "stage",
        "value": "initial-research",
        "exclude": false
      }
    ],
    "tolerations": [
      {
        "name": "text",
        "operator": "Equal",
        "key": "text",
        "value": "text",
        "effect": "NoSchedule",
        "seconds": 1,
        "exclude": false
      }
    ],
    "terminateAfterPreemption": false,
    "autoDeletionTimeAfterCompletionSeconds": 15,
    "terminationGracePeriodSeconds": 20,
    "backoffLimit": 3,
    "ports": [
      {
        "container": 8080,
        "serviceType": "LoadBalancer",
        "external": 30080,
        "toolType": "pytorch",
        "toolName": "my-pytorch",
        "name": "port-instance-a"
      }
    ],
    "exposedUrls": [
      {
        "container": 8080,
        "url": "https://my-url.com",
        "authorizedUsers": [
          "user-a",
          "user-b"
        ],
        "authorizedGroups": [
          "group-a",
          "group-b"
        ],
        "toolType": "jupyter",
        "toolName": "my-pytorch",
        "name": "url-instance-a"
      }
    ],
    "relatedUrls": [
      {
        "url": "https://my-url.com",
        "type": "wandb",
        "name": "url-instance-a"
      }
    ],
    "priorityClass": "build",
    "compute": {
      "gpuDevicesRequest": 1,
      "gpuRequestType": "portion",
      "gpuPortionRequest": 0.5,
      "gpuPortionLimit": 0.5,
      "gpuMemoryRequest": "10M",
      "gpuMemoryLimit": "10M",
      "cpuCoreRequest": 0.5,
      "cpuCoreLimit": 2,
      "cpuMemoryRequest": "20M",
      "cpuMemoryLimit": "30M",
      "largeShmRequest": false,
      "extendedResources": [
        {
          "resource": "hardware-vendor.example/foo",
          "quantity": 2,
          "exclude": false
        }
      ]
    },
    "storage": {
      "dataVolume": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "mountPath": "/mnt/data"
        }
      ],
      "pvc": [
        {
          "name": "storage-instance-a",
          "path": "/container/my-claim",
          "existingPvc": false,
          "claimName": "my-claim",
          "readOnly": false,
          "ephemeral": false,
          "claimInfo": {
            "size": "1G",
            "storageClass": "my-storage-class",
            "accessModes": {
              "readWriteOnce": true,
              "readOnlyMany": false,
              "readWriteMany": false
            },
            "volumeMode": "Filesystem"
          }
        }
      ],
      "hostPath": [
        {
          "name": "storage-instance-a",
          "path": "/container/directory",
          "readOnly": true,
          "mountPath": "/local/directory",
          "mountPropagation": "None"
        }
      ],
      "nfs": [
        {
          "name": "storage-instance-a",
          "path": "/container/nfs",
          "readOnly": true,
          "server": "my.nfs.com",
          "mountPath": "/local/nfs"
        }
      ],
      "git": [
        {
          "name": "storage-instance-a",
          "repository": "https://github.com/my-git/my-repo",
          "branch": "main",
          "revision": "text",
          "path": "/container/my-repository",
          "passwordSecret": "my-password-secret",
          "secretKeyOfUser": "User",
          "secretKeyOfPassword": "Password"
        }
      ],
      "configMapVolume": [
        {
          "name": "storage-instance-a",
          "configMap": "text",
          "mountPath": "text"
        }
      ],
      "secretVolume": [
        {
          "name": "storage-instance-a",
          "mountPath": "text",
          "secret": "text"
        }
      ],
      "s3": [
        {
          "name": "storage-instance-a",
          "bucket": "my-bucket",
          "path": "/container/my-bucket",
          "url": "https://s3.amazonaws.com",
          "accessKeySecret": "my-access-key-secret",
          "secretKeyOfAccessKeyId": "AccessKeyId",
          "secretKeyOfSecretKey": "SecretKey"
        }
      ]
    },
    "security": {
      "uidGidSource": "fromTheImage",
      "capabilities": [
        "CHOWN",
        "KILL"
      ],
      "seccompProfileType": "RuntimeDefault",
      "runAsNonRoot": true,
      "readOnlyRootFilesystem": false,
      "runAsUid": 500,
      "runAsGid": 30,
      "supplementalGroups": "2,3,5,8",
      "allowPrivilegeEscalation": false,
      "hostIpc": false,
      "hostNetwork": false
    }
  }
}

Get workspace data.

get

Retrieve workspace details using a workload id.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

workloadIdstring · uuidRequired

The Universally Unique Identifier (UUID) of the workload.

Responses

200

Executed successfully.

application/json

and

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/workloads/workspaces/{workloadId}

HTTPcURLJavaScriptPython

GET /api/v1/workloads/workspaces/{workloadId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "my-workload-name",
  "requestedName": "text",
  "workloadId": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": 1,
  "departmentId": 2,
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "createdBy": "[e-mail]",
  "createdAt": "2022-01-01T03:49:52.531Z",
  "desiredPhase": "Running",
  "actualPhase": "Creating",
  "spec": {
    "command": "python",
    "args": "-x my-script.py",
    "image": "python:3.8",
    "imagePullPolicy": "Always",
    "workingDir": "/home/myfolder",
    "createHomeDir": true,
    "probes": {
      "readiness": {
        "initialDelaySeconds": 1,
        "periodSeconds": 1,
        "timeoutSeconds": 1,
        "successThreshold": 1,
        "failureThreshold": 1,
        "handler": {
          "httpGet": {
            "path": "/",
            "port": 1,
            "host": "example.com",
            "scheme": "HTTP"
          }
        }
      }
    },
    "nodeType": "my-node-type",
    "nodePools": [
      "my-node-pool-a",
      "my-node-pool-b"
    ],
    "podAffinity": {
      "type": "Required",
      "key": "text"
    },
    "tty": true,
    "stdin": true,
    "environmentVariables": [
      {
        "name": "HOME",
        "value": "/home/my-folder",
        "secret": {
          "name": "postgress_secret",
          "key": "POSTGRES_PASSWORD"
        },
        "exclude": false,
        "description": "Home directory of the user."
      }
    ],
    "annotations": [
      {
        "name": "billing",
        "value": "my-billing-unit",
        "exclude": false
      }
    ],
    "labels": [
      {
        "name": "stage",
        "value": "initial-research",
        "exclude": false
      }
    ],
    "tolerations": [
      {
        "name": "text",
        "operator": "Equal",
        "key": "text",
        "value": "text",
        "effect": "NoSchedule",
        "seconds": 1,
        "exclude": false
      }
    ],
    "terminateAfterPreemption": false,
    "autoDeletionTimeAfterCompletionSeconds": 15,
    "terminationGracePeriodSeconds": 20,
    "backoffLimit": 3,
    "ports": [
      {
        "container": 8080,
        "serviceType": "LoadBalancer",
        "external": 30080,
        "toolType": "pytorch",
        "toolName": "my-pytorch",
        "name": "port-instance-a"
      }
    ],
    "exposedUrls": [
      {
        "container": 8080,
        "url": "https://my-url.com",
        "authorizedUsers": [
          "user-a",
          "user-b"
        ],
        "authorizedGroups": [
          "group-a",
          "group-b"
        ],
        "toolType": "jupyter",
        "toolName": "my-pytorch",
        "name": "url-instance-a"
      }
    ],
    "relatedUrls": [
      {
        "url": "https://my-url.com",
        "type": "wandb",
        "name": "url-instance-a"
      }
    ],
    "priorityClass": "build",
    "compute": {
      "gpuDevicesRequest": 1,
      "gpuRequestType": "portion",
      "gpuPortionRequest": 0.5,
      "gpuPortionLimit": 0.5,
      "gpuMemoryRequest": "10M",
      "gpuMemoryLimit": "10M",
      "cpuCoreRequest": 0.5,
      "cpuCoreLimit": 2,
      "cpuMemoryRequest": "20M",
      "cpuMemoryLimit": "30M",
      "largeShmRequest": false,
      "extendedResources": [
        {
          "resource": "hardware-vendor.example/foo",
          "quantity": 2,
          "exclude": false
        }
      ]
    },
    "storage": {
      "dataVolume": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "mountPath": "/mnt/data"
        }
      ],
      "pvc": [
        {
          "name": "storage-instance-a",
          "path": "/container/my-claim",
          "existingPvc": false,
          "claimName": "my-claim",
          "readOnly": false,
          "ephemeral": false,
          "claimInfo": {
            "size": "1G",
            "storageClass": "my-storage-class",
            "accessModes": {
              "readWriteOnce": true,
              "readOnlyMany": false,
              "readWriteMany": false
            },
            "volumeMode": "Filesystem"
          }
        }
      ],
      "hostPath": [
        {
          "name": "storage-instance-a",
          "path": "/container/directory",
          "readOnly": true,
          "mountPath": "/local/directory",
          "mountPropagation": "None"
        }
      ],
      "nfs": [
        {
          "name": "storage-instance-a",
          "path": "/container/nfs",
          "readOnly": true,
          "server": "my.nfs.com",
          "mountPath": "/local/nfs"
        }
      ],
      "git": [
        {
          "name": "storage-instance-a",
          "repository": "https://github.com/my-git/my-repo",
          "branch": "main",
          "revision": "text",
          "path": "/container/my-repository",
          "passwordSecret": "my-password-secret",
          "secretKeyOfUser": "User",
          "secretKeyOfPassword": "Password"
        }
      ],
      "configMapVolume": [
        {
          "name": "storage-instance-a",
          "configMap": "text",
          "mountPath": "text"
        }
      ],
      "secretVolume": [
        {
          "name": "storage-instance-a",
          "mountPath": "text",
          "secret": "text"
        }
      ],
      "s3": [
        {
          "name": "storage-instance-a",
          "bucket": "my-bucket",
          "path": "/container/my-bucket",
          "url": "https://s3.amazonaws.com",
          "accessKeySecret": "my-access-key-secret",
          "secretKeyOfAccessKeyId": "AccessKeyId",
          "secretKeyOfSecretKey": "SecretKey"
        }
      ]
    },
    "security": {
      "uidGidSource": "fromTheImage",
      "capabilities": [
        "CHOWN",
        "KILL"
      ],
      "seccompProfileType": "RuntimeDefault",
      "runAsNonRoot": true,
      "readOnlyRootFilesystem": false,
      "runAsUid": 500,
      "runAsGid": 30,
      "supplementalGroups": "2,3,5,8",
      "allowPrivilegeEscalation": false,
      "hostIpc": false,
      "hostNetwork": false
    }
  }
}

Delete a workspace.

delete

Delete a workspace using the workspace id.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

workloadIdstring · uuidRequired

The Universally Unique Identifier (UUID) of the workload.

Responses

202

Accepted.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

delete

/api/v1/workloads/workspaces/{workloadId}

HTTPcURLJavaScriptPython

DELETE /api/v1/workloads/workspaces/{workloadId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "code": 202,
  "message": "Request has been accepted."
}

Suspend a workspace.

post

Suspend a workspace using the workspace id.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

workloadIdstring · uuidRequired

The Universally Unique Identifier (UUID) of the workload.

Responses

202

Accepted.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post

/api/v1/workloads/workspaces/{workloadId}/suspend

HTTPcURLJavaScriptPython

POST /api/v1/workloads/workspaces/{workloadId}/suspend HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "code": 202,
  "message": "Request has been accepted."
}

Resume a workspace.

post

Resume the workspace operation using the workspace id.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

workloadIdstring · uuidRequired

The Universally Unique Identifier (UUID) of the workload.

Responses

202

Accepted.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post

/api/v1/workloads/workspaces/{workloadId}/resume

HTTPcURLJavaScriptPython

POST /api/v1/workloads/workspaces/{workloadId}/resume HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "code": 202,
  "message": "Request has been accepted."
}