GPR

A GPR is a GPU Provisioning request to the EGS to provision GPUs to workspace for a requested duration. This topic describes the APIs to create and manage GPRs.

info

Across our documentation, we refer to the workspace as the slice workspace. The two terms are used interchangeably.

Create a GPR

Use this API to create a GPR.

Method and URL

POST /api/v1/gpr

Parameters

Parameter	Parameter Type	Description	Required
gprName	String	The name for the GPU provision request.	Mandatory
sliceName	String	The name of the workspace (slice) where the GPU resources are requested.	Mandatory
preferredClusters	Array of strings	The list of preferred clusters where the GPU resources can be provisioned. This field is required only when enableAutoClusterSelection is false. If enableAutoClusterSelection is true, this field must be empty.	Optional
enableAutoClusterSelection	Boolean	This is the parameter to enable or disable automatic cluster selection. If set to true, EGS automatically selects the best cluster based on resource availability and preferredClusters values must be empty. If set to false, EGS uses the preferredClusters list to select clusters.	Mandatory
enableAutoGpuSelection	Boolean	This is the parameter to enable or disable automatic GPU selection. If set to true, EGS automatically selects the best GPU shape based on resource availability. If set to false, EGS uses the instanceType parameter to select the GPU shape.	Mandatory
numberOfGPUs	Integer	The total number of GPUs required for the GPU request. The value must be greater than or equal to 1.	Mandatory
numberOfGPUNodes	Integer	Number of nodes required for the GPU request. The value must be greater than or equal to 1.	Mandatory
clusterName	String	The name of the cluster to which the GPU provision request is being created.	Mandatory
instanceType	String (as available on the inventory list)	GPU node instance type that you can get from the Inventory list details.	Mandatory
numberOfGPUNodes	Integer	Number of GPU Nodes that you want to request.	Mandatory
priority	String	The priority of the request. You can change the priority of a GPR in the queue. You can select a GPR and increase the priority number (low: 1-100, medium: 101-200, high: 201-300) to move a GPR higher in the queue.	Mandatory
memoryPerGPU	Integer	The memory per GPU is specified using this parameter. The default value is set if you do not pass this parameter.	Mandatory
gpuShape	String (as available on the inventory list)	The name of the GPU type that you can get from the List Inventory details.	Mandatory
exitDuration	Timestamp	The duration for which the GPU resources are required. The format is XdYhZm, where X is days, Y is hours, and Z is minutes. The value must be greater than zero. For example, the duration is 1d2h30m.	Mandatory
idleTimeOutDuration	Timestamp	The duration for which a GPU node can be considered idle before it can be used by another GPR.	Optional
enforceIdleTimeOut	Boolean	If you set the idleTimeOutDuration, then the value of this parameter is enabled by default. Set the value to false if you do not want it enforce the idle time out.	Optional
enableEviction	Boolean	Enable this option to enable auto-eviction of the low priority GPR.	Optional
requeueOnFailure	Boolean	Enable this option to requeue GPR in case it fails.	Optional

Example Scenarios

Example 1: Create a GPR with both cluster and GPU auto-selection Enabled

When both the enableAutoClusterSelection and enableAutoGpuSelection parameters are set to true, EGS will automatically select the optimal cluster and GPU shape based on resource availability.

Example Request

curl -X POST --location --globoff '{{host}}/api/v1/gpr' \
--data '{
    "gprName": "gpr-123",
    "clusterName": "worker-1",
    "sliceName": "dashboard",
    "numberOfGPUs": 1,
    "numberOfGPUNodes": 1,
    "exitDuration": "00d06h00m",
    "memoryPerGpu": 15,
    "priority": 1,
    "enableEviction": true,
    "enableAutoClusterSelection": true, // new field
    "enableAutoGpuSelection": true, // new field
    "idleTimeOutDuration": "10m",
    "enforceIdleTimeOut": true,
    "enableEviction": true,
    "requeueOnFailure": true
}'

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "gprId": "gpr-1bb22a0b-9388"
  }
}

Response: Bad Request

{
  "statusCode": 422,
  "status": "Error",
  "message": "Bad Request",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "",
    "data": "{\"error\":{\"Message\":\"Error while fetching GPR wait time\",\"Status\":422,\"DetailedError\":{\"Errormessage\":\"\\\"exitDuration\\\" is not allowed to be empty\",\"Reason\":\"\",\"Details\":\"\"},\"StatusCode\":422,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

Example 2: Create a GPR with Only Cluster Auto-Selection Enabled

When only the enableAutoClusterSelection is set to true, the preferredClusters parameter values must be empty. EGS automatically selects the best cluster based on resource availability.

Example Request

curl -X POST --location --globoff '{{host}}/api/v1/gpr' \
--data '{
    "gprName": "gpr-123",
    "clusterName": "worker-1",
    "sliceName": "dashboard",
    "numberOfGPUs": 2,
    "numberOfGPUNodes": 1,
    "instanceType": "n1-highcpu-2",
    "gpuShape": "Tesla-T4",
    "exitDuration": "00d06h00m",
    "memoryPerGpu": 15,
    "priority": 101,
    "enableEviction": true,
    "enableAutoClusterSelection": true, // field
    "enableAutoGpuSelection": false // new field
    "idleTimeOutDuration": "10m",
    "enforceIdleTimeOut": true,
    "enableEviction": true,
    "requeueOnFailure": true
}'

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "gprId": "gpr-1bb22a0b-9388"
  }
}

Response: Bad Request

{
  "statusCode": 422,
  "status": "Error",
  "message": "Bad Request",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "",
    "data": "{\"error\":{\"Message\":\"Error while fetching GPR wait time\",\"Status\":422,\"DetailedError\":{\"Errormessage\":\"\\\"exitDuration\\\" is not allowed to be empty\",\"Reason\":\"\",\"Details\":\"\"},\"StatusCode\":422,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

Example 3: Create a GPR with Only GPU Auto-Selection Enabled

When only the enableAutoGpuSelection parameter is set to true, skip providing the gpuShape and instanceType parameters values. EGS automatically selects the best GPU shape based on resource availability.

Example Request

curl -X POST --location --globoff '{{host}}/api/v1/gpr' \
--data '{
    "gprName": "tesla-workload",
    "clusterName": "worker-1",
    "sliceName": "dashboard",
    "preferredClusters": [
        "worker-4",
        "worker-1"
    ], // new field
    "numberOfGPUs": 1,
    "numberOfGPUNodes": 1,
    "exitDuration": "00d02h00m",
    "memoryPerGpu": 15,
    "priority": 101,
    "enableEviction": true,
    "enableAutoClusterSelection": false, // new field
    "enableAutoGpuSelection": true, // new field
    "idleTimeOutDuration": "10m",
    "enforceIdleTimeOut": true,
    "enableEviction": true,
    "requeueOnFailure": true
}' 

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "gprId": "gpr-1bb22a0b-9388"
  }
}

Response: Bad Request

{
  "statusCode": 422,
  "status": "Error",
  "message": "Bad Request",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "",
    "data": "{\"error\":{\"Message\":\"Error while fetching GPR wait time\",\"Status\":422,\"DetailedError\":{\"Errormessage\":\"\\\"exitDuration\\\" is not allowed to be empty\",\"Reason\":\"\",\"Details\":\"\"},\"StatusCode\":422,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

Example 4: Create a GPR with No Auto-Selection Enabled

When both the enableAutoClusterSelection and enableAutoGpuSelection parameters are set to false, the preferredClusters, gpuShape and instanceType parameters are required.

Example Request

curl -X POST --location --globoff '{{host}}/api/v1/gpr' \
--data '{

    "gprName": "tesla-workload",
    "clusterName": "worker-1",
    "sliceName": "dashboard",
    "preferredClusters": [
        "worker-4",
        "worker-3"
    ],
    "numberOfGPUs": 2,
    "numberOfGPUNodes": 1,
    "instanceType": "n1-highcpu-2",
    "gpuShape": "Tesla-T4",
    "exitDuration": "00d02h00m",
    "memoryPerGpu": 15,
    "priority": 1,
    "enableEviction": true,
    "enableAutoClusterSelection": false, // new field
    "enableAutoGpuSelection": false, // new field
    "idleTimeOutDuration": "10m",
    "enforceIdleTimeOut": true,
    "enableEviction": true,
    "requeueOnFailure": true
}'

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "gprId": "gpr-1bb22a0b-9388"
  }
}

Response: Bad Request

{
  "statusCode": 422,
  "status": "Error",
  "message": "Bad Request",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "",
    "data": "{\"error\":{\"Message\":\"Error while fetching GPR wait time\",\"Status\":422,\"DetailedError\":{\"Errormessage\":\"\\\"exitDuration\\\" is not allowed to be empty\",\"Reason\":\"\",\"Details\":\"\"},\"StatusCode\":422,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

Edit a GPR

Use this API to update a queued-GPR details or early release a provisioned GPR.

note

If the GPR is already provisioned (GPUs allocated to the workspace), then use the GPR edit API call with the Early Release option to release GPUs, and delete the GPR. If GPR is still in the queued state, then use delete GPR API to delete it.

Method and URL

PUT /api/v1/gpr

Parameters

Parameter	Parameter Type	Description	Required
earlyRelease	Boolean	The value can be set to true if you want to early release a GPR. The default value is false.	Optional
gprID	String	The ID of the GPR that you want to edit.	Mandatory
gprName	String	The name of the GPR that you want to edit.	Mandatory
priority	String	The priority of the GPR that you want to edit.	Optional
enableEviction	Boolean	Enable this option to enable auto-eviction of the low priority GPR.	Optional
requeueOnFailure	Boolean	Enable this option to requeue GPR in case it fails.	Optional

Example Request

curl -X PUT --location --globoff --request PUT '{{host}}/api/v1/gpr' \
--data '{
    "gprId":"{{gprId}}",
    //"priority": 105,
    //"earlyRelease": true,
    //"gprName": "created-by-core-apis",
    "enableEviction":true,
    "requeueOnFailure":true
}

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {}
}

Response: Early Release a GPR Inability

{
  "statusCode": 500,
  "status": "Error",
  "message": "Unable to Early Release",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "Unable to Early Release",
    "data": "{\"error\":{\"Message\":\"Error while updating a GPR\",\"Status\":500,\"DetailedError\":{\"Errormessage\":\"Cannot update early release of GPR in Queued state\",\"Reason\":\"\",\"Details\":\"\"},\"StatusCode\":500,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

View a GPR

Use this API to view a GPR by its ID.

Method and URL

GET /api/v1/gpr/gpr?gprId=<GPR Id>

Parameters

Parameter	Parameter Type	Description	Required
gprId	String	The ID of the GPR whose details you want to get.	Mandatory

Example Request

curl -X GET  --location --globoff '{{host}}/api/v1/gpr/gpr?gprId=gpr-b900c98b-27a6'

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "gprId": "gpr-b900c98b-27a6",
    "sliceName": "pink",
    "clusterName": "worker-1",
    "numberOfGPUs": 1,
    "numberOfGPUNodes": 1,
    "instanceType": "n1-highcpu-2",
    "memoryPerGPU": 15,
    "priority": 201,
    "gpuSharingMode": "Virtual Machine",
    "estimatedStartTime": "2024-12-24T08:13:08Z",
    "estimatedWaitTime": "0h0m0s",
    "exitDuration": "0h1m0s",
    "earlyRelease": false,
    "gprName": "created-by-coreapi",
    "gpuShape": "Tesla-T4",
    "multiNode": false,
    "dedicatedNodes": false,
    "enableRDMA": false,
    "enableSecondaryNetwork": false,
    "status": {
      "provisioningStatus": "Queued",
      "failureReason": "",
      "numGpusAllocated": 0,
      "startTimestamp": "",
      "completionTimestamp": "",
      "cost": "",
      "nodes": null,
      "internalState": "",
      "retryCount": 0,
      "delayedCount": 0
    },
    "enforceIdleTimeOut": true,
    "idleTimeOutDuration": "0h1m0s",
    "enableEviction": true,
    "requeueOnFailure": true
  }
}

Response: Not Found

{
  "statusCode": 404,
  "status": "UNKNOWN",
  "message": "UNKNOWN",
  "data": null,
  "error": {
    "errorKey": "UNKNOWN",
    "message": "UNKNOWN",
    "data": "{\"error\":{\"Message\":\"Error while fetching GPRs\",\"Status\":404,\"DetailedError\":{\"Errormessage\":\"gpuprovisioningrequests.gpr.kubeslice.io \\\"gpr-1bb22a0b-9388-x\\\" not found\",\"Reason\":\"NotFound\",\"Details\":\"\"},\"StatusCode\":404,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

List GPRs by a Slice Workspace

Use this API to list GPRs associated with a slice workspace. The response includes GPR status and other details for each GPR associated with the slice workspace.

Method and URL

GET /api/v1/gpr/list?sliceName=<workspace>

Parameters

Parameter	Parameter Type	Description	Required
workspace	String	The name of the slice whose GPRs you want to list.	Mandatory

Example Request

curl -X GET  --location --globoff '{{host}}/api/v1/gpr/list?sliceName=workspace1'

Example Responses

Response: Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "items": [
      {
        "gprId": "gpr-1bb22a0b-9388",
        "sliceName": "workspace1",
        "clusterName": "worker-1",
        "numberOfGPUs": 1,
        "numberOfGPUNodes": 1,
        "instanceType": "n1-standard-8",
        "memoryPerGPU": 15,
        "priority": 201,
        "gpuSharingMode": "Virtual Machine",
        "estimatedStartTime": "2024-10-22T11:12:38Z",
        "estimatedWaitTime": "0h0m0s",
        "exitDuration": "1h15m0s",
        "earlyRelease": true,
        "gprName": "gpr1",
        "gpuShape": "Tesla-T4",
        "multiNode": false,
        "dedicatedNodes": false,
        "enableRDMA": false,
        "enableSecondaryNetwork": false,
        "status": {
          "provisioningStatus": "Queued",
          "failureReason": "",
          "numGpusAllocated": 0,
          "startTimestamp": "",
          "completionTimestamp": "",
          "cost": "",
          "nodes": ["gke-dev-2-gke-cluste-dev-2-gke-cluste-9d71107a-hs19"],
          "internalState": "Queued",
          "retryCount": 0,
          "delayedCount": 0
        },
        "enforceIdleTimeOut": true,
        "idleTimeOutDuration": "0h1m0s"
      },
      {
        "gprId": "gpr-5d278fd3-e868",
        "sliceName": "workspace1",
        "clusterName": "worker-1",
        "numberOfGPUs": 1,
        "numberOfGPUNodes": 1,
        "instanceType": "n1-standard-8",
        "memoryPerGPU": 15,
        "priority": 101,
        "gpuSharingMode": "Virtual Machine",
        "estimatedStartTime": "2024-10-22T06:30:39Z",
        "estimatedWaitTime": "0h0m0s",
        "exitDuration": "0h10m0s",
        "earlyRelease": false,
        "gprName": "rag-gpr-1",
        "gpuShape": "Tesla-T4",
        "multiNode": false,
        "dedicatedNodes": false,
        "enableRDMA": false,
        "enableSecondaryNetwork": false,
        "status": {
          "provisioningStatus": "Complete",
          "failureReason": "",
          "numGpusAllocated": 0,
          "startTimestamp": "",
          "completionTimestamp": "2024-10-22T06:41:17Z",
          "cost": "",
          "nodes": ["gke-dev-2-gke-cluste-dev-2-gke-cluste-9d71107a-hs19"],
          "internalState": "Released",
          "retryCount": 0,
          "delayedCount": 0
        },
        "enforceIdleTimeOut": true,
        "idleTimeOutDuration": "0h1m0s"
      }
    ]
  }
}

Response: Not Found

{
  "statusCode": 404,
  "status": "Error",
  "message": "Slice Workspace Not Found",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "Slice Workspace Not Found",
    "data": "{\"error\":{\"Message\":\"Error in listing GPR's for slice evening-x\",\"Status\":404,\"DetailedError\":{\"Errormessage\":\"sliceconfigs.controller.kubeslice.io \\\"evening-x\\\" not found\",\"Reason\":\"NotFound\",\"Details\":\"\"},\"StatusCode\":404,\"ReferenceDocumentation\":\"NA\"}}"
  }
}

Delete a GPR

Use this API to delete a queued GPR. You cannot delete provisioned GPR using this API call.

note

If the GPR is already provisioned, then use GPR edit API call with the Early Release option to release the GPUs, and delete the GPR.

Method and URL

DELETE /api/v1/gpr

Parameters

Parameter	Parameter Type	Description	Required
gprId	String	The ID of the queued GPR that you want to delete.	Mandatory

Example Request

curl -X DELETE --location --globoff '{{host}}/api/v1/slice-workspace/kube-config' \
--data '{ "gprId": "gpr-e4e38fc5-4742"}'

Example Responses

Response Success

{
  "statusCode": 200,
  "status": "OK",
  "message": "Success",
  "data": {}
}

Response: Cannot delete

{
  "statusCode": 500,
  "status": "Error",
  "message": "Cannot delete",
  "data": null,
  "error": {
    "errorKey": "",
    "message": "UNKNOWN",
    "data": "{\"error\":{\"Message\":\"Error while deleting GPR\",\"Status\":500,\"DetailedError\":{\"Errormessage\":\"Cannot delete GPR in Successful state\",\"Reason\":\"\",\"Details\":\"\"},\"StatusCode\":500,\"ReferenceDocumentation\":\"NA\"}}"
  }
}