Skip to main content

GraphQL

Many of the Shakudo Platform features are supported through the platform dashboard as well as GraphQL. GraphQL method is particularly useful when some actions are easier done algorithmically such as spinning up many jobs at once.

Below are some common graphql queries for submission, checking status, etc.


Common Use Cases

Get Sessions

Description

Retrieves a list of Sessions

query hyperhubSessions($limit: Int!, $email: String, $status: String, $imageType: String) {
hyperHubSessions(orderBy:{startTime: desc}, take: $limit, where: {
hyperplaneUserEmail: {equals: $email},
imageType: {equals: $imageType},
status: {equals: $status},
}) {
id
hyperplaneUserEmail
status
imageType
jLabUrl
notebookURI
estimatedCost
resourceCPUlimit
resourceRAMlimit
resourceCPUrequest
resourceRAMrequest
gpuRequest
startTime
}
countHyperHubSessions
}

Sample Variables

{
"limit": 10,
"email": "demo@shakudo.io",
"status": "in progress"
}

Parameters

FieldTypeDescription
limitInt!The maximum number of records to show in the result. (required)
emailStringShakudo platform user email for the user who created the session
imageTypeStringName of the Shakudo platform EC. For example, "basic"
statusStringUnderlying Kubernetes job status

Response Type

Array of HyperHubSessions

Sample Response

{
"data": {
"hyperHubSessions": [
{
"id": "49475b67-3f8f-43c1-9f42-7b2175d1e679",
"hyperplaneUserEmail": "demo@shakudo.io",
"status": "in progress",
"imageType": "basic",
"jLabUrl": "client.hyperplane.dev/jupyterlabUrl/",
"notebookURI": "ssh demo-pvc-entry@demo.dev",
"estimatedCost": null,
"resourceCPUlimit": null,
"resourceRAMlimit": null,
"resourceCPUrequest": null,
"resourceRAMrequest": null,
"gpuRequest": null,
"startTime": "2023-07-05T16:25:45.676Z"
}
],
"countHyperHubSessions": 22
}
}

Create Session

Description

Creates a Session

Creating using createHyperHubSession parameters


query GetHyperplaneUserId($hyperplaneUserEmail: String!){
hyperplaneUsers(where: {email: {equals: $hyperplaneUserEmail}}) {
id
email
}
}

# billingProjectName optional
query GetBillingProjectId($billingProjectName: String){
billingProjects(where: {name: {equals: $billingProjectName}}) {
id
name
}
}

# userPvcName and displayName optional
query GetUserPvcId($userPvcName: String, $displayName: String){
userPvcs(where: {
pvcName: {equals: $userPvcName},
displayName: {equals: $displayName}
}) {
id
pvcName
displayName
}
}

mutation createSession(
$imageType: String!
$hyperplaneUserId: String!
$hyperplaneUserEmail: String!
$timeout: Int!
$collaborative: Boolean!
$imageHash: String!
$userPvcName: String = ""
$userPvc: UserPvcCreateNestedOneWithoutHyperHubSessionInput
$billingProjectId: String!
) {
createHyperHubSession(
data: {
imageType: $imageType
timeout: $timeout
collaborative: $collaborative
imageHash: $imageHash
group: ""
hyperplaneUser: { connect: { id: $hyperplaneUserId } }
billingProject: { connect: { id: $billingProjectId } }
userPvc: $userPvc
userPvcName: $userPvcName
hyperplaneUserEmail: $hyperplaneUserEmail
}
) {
id
hyperplaneUserEmail
status
imageType
jLabUrl
estimatedCost
resourceCPUlimit
resourceRAMlimit
resourceCPUrequest
resourceRAMrequest
gpuRequest
startTime
completionTime
timeout
group
billingProjectId
podSpec
}
}

Sample Variables

Retrieve $hyperplaneUserId using GetHyperplaneUserId and $billingProjectId using GetBillingProjectId

Default Drive

{
"collaborative": false,
"imageType": "basic",
"imageHash": "",
"timeout": 900,
"hyperplaneUserEmail": "demo@shakudo.io",
"hyperplaneUserId": "93c6c00a-14b7-4cf7-845d-70d9e779b2cd", # From GetHyperplaneUserId
"billingProjectId": "8359f1f9-2eca-465b-9ac5-7cdb0e97e73f" # From GetBillingProjectId
}

Custom Drive

{
"collaborative": false,
"imageType": "basic",
"imageHash": "",
"timeout": 900,
"userPvcName": "demo-user-pvc-name",
"displayName": "demo drive",
"hyperplaneUserId": "93c6c00a-14b7-4cf7-845d-70d9e779b2cd", # From GetHyperplaneUserId
"billingProjectId": "8359f1f9-2eca-465b-9ac5-7cdb0e97e73f" # From GetBillingProjectId
"userPvc": { "connect": { "id": "bb2eeed2-6032-4036-9e8f-e757235533bb" }}, # From GetUserPvcId
"hyperplaneUserEmail": "demo@shakudo.io"
}

Parameters

FieldTypeDefinition
imageTypeString! (required)Name of Shakudo platform EC
hyperplaneUserIdString! (required)Shakudo platform user account ID
hyperplaneUserEmailString! (required)Shakudo platform user account email
collaborativeBoolean! (required)Enables collaborative mode. Collaborative mode allows multiple users to work together in the same session environment.
timeoutInt! (required)The maximum time in seconds that the pipeline may run, starting from the moment of job submission. Default: -1, ie. never timeout; 86400 on dashboard
imageHashString! (required)URL of custom image, "" if using a default image like basic
userPvcNameString ("" if not provided)Persistent volume name as found in Kubernetes. Typically includes the drive name found on the dashboard. Default: "" (empty string) which corresponds with default drive claim-{user-email}
userPvcUserPvcShakudo session persistent volume (drive) details. Can either provide identifiers to connect to an existing drive or can provide values to create a new drive. Default: not present, which corresponds with default drive claim-{user-email}. Note: userPvc ID must correspond with same userPvc as userPvcName.
displayNameStringDrive (PVC) display name as visible on UI dashboard
billingProjectIdString! (required)ID for billing project that user would like Session costs to contribute. Can either provide identifiers to connect to an existing billing project or can provide values to create a new billing project. Can get from GetBillingProjectId.
billingProjectNameStringName of billing project as shown on UI dashboard

Response Type

HyperHubSession

Sample Response

{
"data": {
"createHyperHubSession": {
"id": "0b8b90c7-b3d6-43d7-a34a-27a9b17521b4",
"hyperplaneUserEmail": "demo@shakudo.io",
"status": "pending",
"imageType": "basic",
"jLabUrl": null,
"estimatedCost": null,
"resourceCPUlimit": null,
"resourceRAMlimit": null,
"resourceCPUrequest": null,
"resourceRAMrequest": null,
"gpuRequest": null,
"startTime": "2023-07-06T21:14:29.245Z",
"completionTime": null,
"timeout": 900,
"group": "",
"billingProjectId": "bb2eeed2-6032-4036-9e8f-e757235533bb",
"podSpec": null
}
}
}

Creating using PodSpec JSON (getHyperhubSessionDefaultPodSpec)

**Getting PodSpec JSON**

query GetHyperhubSessionPodSpec($imageType: String, $userPvcName: String, $userEmail: String!, $imageUrl: String) {
getHyperhubSessionPodSpec(
imageType: $imageType,
userPvcName: $userPvcName,
userEmail: $userEmail,
imageUrl: $imageUrl
)
}

Sample Variables

{
"imageType": "basic",
"userEmail": "demo@shakudo.io"
}

****Parameters****

FieldTypeDescription
imageUrlStringURL of custom image, same as imageHash
userPvcNameStringPersistent volume name as found in Kubernetes. Typically includes the drive name found on the dashboard. Default: "" (empty string) which corresponds with default drive claim-{user-email}
userEmailString! (required)Shakudo platform user account email
imageTypeStringName of Shakudo platform Podspec/Image

Creating Session with PodSpec JSON

query GetHyperplaneUserId($userEmail: String!){
hyperplaneUsers(where: {email: {equals: $userEmail}}) {
id
email
}
}

mutation CreateSessionWithPodSpecJSON(
$userEmail: String!
$hyperplaneUserId: String!
$userPvcName: String = ""
$podSpec: JSON
) {
createHyperHubSession(
data: {
hyperplaneUserEmail: $userEmail,
hyperplaneUser: { connect: { id: $hyperplaneUserId } },
userPvcName: $userPvcName
podSpec: $podSpec
}
) {
id
hyperplaneUserEmail
status
imageType
jLabUrl
estimatedCost
resourceCPUlimit
resourceRAMlimit
resourceCPUrequest
resourceRAMrequest
gpuRequest
startTime
completionTime
timeout
group
billingProjectId
}
}

Sample Variables

Note: podSpec field contains result of GetHyperhubSessionPodSpec and the corresponding getHyperHubSessionDefaultPodSpec field in the query’s result object. ie.

{
"imageType": "basic",
"userEmail": "demo@shakudo.io",
"hyperplaneUserId": "bb2eeed2-6032-4036-9e8f-e757235533bb",
"podSpec": <getHyperHubSessionDefaultPodSpec result>
}

Parameters

FieldTypeDescription
userEmailString! (required)Shakudo platform user account email
hyperplaneUserIdString! (required)Shakudo platform user account ID
podSpecJSONShakudo platform PodSpec config object as a JSON object, originates from getHyperHubSessionDefaultPodSpec
userPvcNameString (”” if not provided)Added as a parameter to align field in UI

Response Type

HyperHubSession

Sample Response

{
"data": {
"createHyperHubSession": {
"id": "bb2eeed2-6032-4036-9e8f-e757235533bb",
"hyperplaneUserEmail": "demo@shakudo.io",
"status": "pending",
"imageType": "basic",
"jLabUrl": null,
"estimatedCost": null,
"resourceCPUlimit": null,
"resourceRAMlimit": null,
"resourceCPUrequest": null,
"resourceRAMrequest": null,
"gpuRequest": null,
"startTime": "2023-07-05T16:26:06.346Z",
"completionTime": null,
"timeout": -1,
"group": null,
"billingProjectId": null
}
}
}

Stop Session


mutation stopSession($id: String!) {
updateHyperHubSession(where: {id: $id}, data: {
status: {set: "cancelled"}
}) {
id
status
}
}

Sample Variables

{ 
"id": "9276a796-229f-4ede-a2cf-a7cf329dab6a"
}

Parameters

FieldTypeDescription
idString! (required)Session ID

Response Type

HyperHubSession

Sample Response

{
"data": {
"updateHyperHubSession": {
"id": "9276a796-229f-4ede-a2cf-a7cf329dab6a",
"status": "cancelled"
}
}
}

Count Sessions

Description

Count the number of sessions based on the filters provided by the parameters.

query CountHyperhubSessions($email: String, $imageType: String, $status: String) {
countHyperHubSessions(whereOveride: {
hyperplaneUserEmail: {equals: $email},
imageType: {equals: $imageType}
status: {equals: $status}
})
}

Sample Variables

{
"email": "demo@shakudo.io",
"imageType": "basic",
"status": "in progress"
}

Parameters

FieldTypeDescription
emailStringShakudo platform user email for the user who created the session
imageTypeStringName of the Shakudo platform Podspec/Image, e.g., "basic"
statusStringThe status of the Kubernetes job that runs the pipeline job

Response Type

HyperHubSession

Sample Response

{
"data": {
"countHyperHubSessions": 1
}
}

Create a Pipeline Job using createPipelineJob Parameters

Description

Creates a Shakudo platform job, which allows users to run task scripts using custom configurations, either immediately as an “Immediate job”, at scheduled intervals as a “Scheduled Job”, or indefinitely as a “Service”.

Immediate jobs: schedule = "immediate"

Scheduled jobs: schedule != "immediate", schedule is set to cron schedule expression, eg. * * * * * for a job running every minute

Service: timeout and activeTimeout set to -1 , schedule="immediate" and exposedPort != null, particularly set to a valid port

mutation CreatePipelineJob(
$type: String!
$timeout: Int!
$activeTimeout: Int
$maxRetries: Int!
$yamlPath: String!
$exposedPort: String
$schedule: String
$parameters: ParameterCreateNestedManyWithoutPipelineJobInput
$gitServer: HyperplaneVCServerCreateNestedOneWithoutPipelineJobsInput
$hyperplaneUserEmail: String!
$branchName: String
) {
createPipelineJob(
data: {
jobType: $type
timeout: $timeout
activeTimeout: $activeTimeout
maxRetries: $maxRetries
pipelineYamlPath: $yamlPath
exposedPort: $exposedPort
parameters: $parameters
schedule: $schedule
hyperplaneVCServer: $gitServer
hyperplaneUserEmail: $hyperplaneUserEmail
branchName: $branchName
}
) {
id
jobName
pipelineYamlPath
schedule
status
statusReason
output
startTime
completionTime
daskDashboardUrl
timeout
outputNotebooksPath
activeTimeout
maxRetries
exposedPort
jobType
parameters {
key
value
}
}
}

Parameters

FieldTypeDescription
typeString! (required)Name of Shakudo platform Podspec/Image, default or custom. Example: "basic"
timeoutInt! (required)The maximum time in seconds that the pipeline may run, starting from the moment of job submission. Default: -1 (never timeout). Example: 86400
activeTimeoutIntThe maximum time in seconds that the pipeline may run once it is picked up. Default: -1 (never timeout). Example: 86400
maxRetriesInt! (required)The maximum number of attempts to run your pipeline job before returning an error, even if timeouts are not reached. Default: 2
yamlPathStringThe relative path to the .yaml file used to run this pipeline job. Example: "example_notebooks/pipelines/python_hello_world_pipeline/pipeline.yaml"
exposedPortStringOnly enabled for Shakudo Services. The port that Services use to expose the pod to other pods within the cluster. Its presence is a current indicator of whether a job is a Service.
scheduleStringEither "immediate" for an immediate job or a cron schedule expression for a scheduled job at the specified interval.
parametersParameterCreateNestedManyWithoutPipelineJobInputKey-value pairs that can be used within the container environment
gitServerHyperplaneVCServerCreateNestedOneWithoutPipelineJobsInputGit server object, retrievable by searching git servers by name (hyperplaneVCServers) and using resulting id in the following manner: { connect: { id: <gitServerId> } }
hyperplaneUserEmailString! (required)Shakudo platform user email
branchNameStringThe name of the specific git branch that contains the pipeline YAML file and pipeline scripts. If commitID is not specified, the latest commit is used. If not specified, default branch is used.

Please note that the exclamation mark ! indicates that the field is required.

Sample Variables

{
"type": "basic",
"timeout": 86400,
"activeTimeout": 86400,
"maxRetries": 2,
"yamlPath": "examples/pipeline.yaml",
"hyperplaneUserEmail": "demo@shakudo.io",
"branchName": "main"
}

Response Type

PipelineJob

Sample Response

{
"data": {
"createPipelineJob": {
"id": "7b728979-71b7-426c-9847-6fe3e29a6438",
"pipelineYamlPath": "examples/pipeline.yaml",
"schedule": "immediate",
"status": "pending",
"statusReason": null,
"output": null,
"startTime": "2023-06-30T16:03:42.668Z",
"completionTime": null,
"daskDashboardUrl": null,
"timeout": 86400,
"outputNotebooksPath": null,
"activeTimeout": 86400,
"maxRetries": 2,
"exposedPort": null,
"jobType": "basic",
"parameters": []
}
}
}

Create a Scheduled Job using createPipelineJob Parameters

Description

Create a scheduled job by specifying a cron schedule. Use the following guide to create a suitable expression for a specific schedule.

Sample Variables

{
"type": "basic",
"timeout": 86400,
"maxRetries": 2,
"schedule": "* * * * *",
"yamlPath": "examples/pipeline.yaml",
"hyperplaneUserEmail": "demo@shakudo.io",
"branchName": "demo"
}

Response Type

PipelineJob

Sample Response

{
"data": {
"createPipelineJob": {
"id": "9276a796-229f-4ede-a2cf-a7cf329dab6a",
"pipelineYamlPath": "examples/pipeline.yaml",
"schedule": "* * * * *",
"status": "pending",
"statusReason": null,
"output": null,
"startTime": "2023-06-30T16:03:42.668Z",
"completionTime": null,
"daskDashboardUrl": null,
"timeout": 86400,
"outputNotebooksPath": null,
"activeTimeout": 86400,
"maxRetries": 2,
"exposedPort": null,
"jobType": "basic",
"parameters": []
}
}
}

Create a PipelineJob using PodSpec JSON (getPipelineJobPodSpec)

Description

Create an immediate or scheduled job using a PodSpec JSON object that is customizable. Use the following guide to create a suitable expression for a specific schedule.

query GetPipelineJobPodSpec(
$parameters: ParametersInput
$gitServerName: String = ""
$noGitInit: Boolean = false
$imageUrl: String = ""
$userEmail: String!
$noHyperplaneCommands: Boolean = false
$commitId: String = ""
$branchName: String
$pipelineYamlPath: String = ""
$debuggable: Boolean = false
$jobType: String = ""
) {
getPipelineJobPodSpec(
parameters: $parameters
gitServerName: $gitServerName
noGitInit: $noGitInit
imageUrl: $imageUrl
userEmail: $userEmail
noHyperplaneCommands: $noHyperplaneCommands
pipelineYamlPath: $pipelineYamlPath
commitId: $commitId
branchName: $branchName
debuggable: $debuggable
jobType: $jobType
)
}

Sample Variables

{
"jobType": "basic",
"userEmail": "demo@shakudo.io",
"pipelineYamlPath": "examples/pipeline.yaml",
"branchName": "demo"
}

Parameters

FieldTypeDescription
parametersParametersInputList of key-value parameters that are injected into the Job environment and can be used as environment variables
gitServerNameString ("" if not provided)Git Server name, corresponds with name field in HyperplaneVCServer, which is the display name assigned on the dashboard
noGitInitBoolean (false if not provided)False if git server is to be set up using default Shakudo platform workflow. Default: false
imageUrlString ("" if not provided)If the image is custom, then the image URL can be provided
userEmailString! (required)Shakudo platform user account email
noHyperplaneCommandsBooleanFalse if using default Shakudo platform commands on job creation. Required to use Shakudo platform jobs through the pipeline YAML, but not required if the image has its own setup. Default: false
commitIdString ("" if not provided)The commit ID with the versions of the pipeline YAML file and pipeline scripts wanted. Ensure that both are present if the commit ID is used. If left empty, assume that the latest commit on the branch is used
branchNameStringThe name of the specific git branch that contains the pipeline YAML file and pipeline scripts. If commitID is not specified, the latest commit is used. If not specified, default branch is used.
pipelineYamlPathString ("" if not provided)The relative path to the .yaml file used to run this pipeline job
debuggableBoolean (false if not provided)Whether to enable SSH-based debugging for the job, check the following tutorial for more details
jobTypeString ("" if not provided)Name of Shakudo platform Podspec/Image, default or custom
mutation CreatePipelineJob(
$jobName: String
$pipelineYamlPath: String!
$podSpec: JSON!
$schedule: String
$userEmail: String!
) {
createPipelineJob (data: {
jobName: $jobName
pipelineYamlPath: $pipelineYamlPath
podSpec: $podSpec
schedule: $schedule
hyperplaneUserEmail: $userEmail
}
) {
id
jobName
pipelineYamlPath
schedule
status
statusReason
output
startTime
completionTime
daskDashboardUrl
timeout
outputNotebooksPath
activeTimeout
maxRetries
exposedPort
jobType
parameters {
key
value
}
}
}
FieldTypeDefinition
jobNameStringPlain display name of job viewable from the dashboard, not necessarily unique.
pipelineYamlPathString!The relative path to the .yaml file used to run this pipeline job
podSpecJSON!Shakudo platform PodSpec environment config object as JSON
scheduleStringEither "immediate" for an immediate job or a cron schedule expression for a scheduled job.
userEmailString!Shakudo user account email

Sample Variables

podSpec will be the result of GetPipelineJobPodSpec from the field getPipelineJobPodSpec

{
"jobType": "basic",
"userEmail": "demo@shakudo.io",
"branchName": "demo",
"pipelineYamlPath": "examples/pipeline.yaml",
"jobName": "test-create-pipeline-job-with-podSpec",
"podSpec": <GetPipelineJobPodSpec getPipelineJobPodSpec field result>
}

Response Type

PipelineJob

Sample Response

{
"data": {
"createPipelineJob": {
"id": "9f8f0524-6d67-4996-bd45-8a2434d97c1f",
"pipelineYamlPath": "examples/pipeline.yaml",
"schedule": "* * * * *",
"status": "pending",
"statusReason": null,
"output": null,
"startTime": "2023-06-30T16:03:42.668Z",
"completionTime": null,
"daskDashboardUrl": null,
"timeout": 86400,
"outputNotebooksPath": null,
"activeTimeout": 86400,
"maxRetries": 2,
"exposedPort": null,
"jobType": "basic",
"parameters": []
}
}
}

Cancel a Pipeline Job

Description

Cancel a job (Stop job from running).

Find PipelineJob by jobName or another non-unique identifier, optional if user has ID

query ($jobName: String) {
pipelineJobs(where: {jobName: {equals: $jobName} }) {
id
pipelineYamlPath
schedule
status
statusReason
startTime
completionTime
timeout
outputNotebooksPath
activeTimeout
jobType
parameters {
key
value
}
}
}

Sample Variables

{
"jobName": "foo"
}

Parameters

FieldTypeDescription
jobNameStringPlain display name of job viewable from the dashboard, not necessarily unique.

Use PipelineJob ID to cancel the job

mutation ($id: String!) {
updatePipelineJob(where: {id: $id},
data: {
status: {set: "cancelled"}
}) {
id
}
}

Sample Variables

{
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8"
}

Parameters

FieldTypeDescription
idString! (required)Pipeline Job ID

Response Type

PipelineJob

Sample Response

{
"data": {
"updatePipelineJob": {
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8"
}
**** }
}

Get Job Status

query GetPipelineJobStatus($id: String!){
pipelineJob(where: {id: $id }) {
status
statusReason
}
}

Sample Variables

{
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8"
}

Parameters

FieldTypeDescription
idString! (required)Pipeline Job ID

Response Type

PipelineJob

Sample Response

{
"data": {
"pipelineJob": {
"status": "done",
"statusReason": null
}
}
}

Get Job Status Statistics

Description

Count the number of jobs based on their statuses. For example, failed, pending, or cancelled jobs. The timeFrame parameter specifies the timeframe which will be considered.

For instance:

  • T_10M = past 10 minutes
  • T_24H = past 24 hours
query {
COUNT_ALL_TOTAL: getJobStat(stat: COUNT_ALL, timeFrame: TOTAL)
COUNT_CANCELLED_TOTAL: getJobStat(stat: COUNT_CANCELLED, timeFrame: TOTAL)
COUNT_DONE_TOTAL: getJobStat(stat: COUNT_DONE, timeFrame: TOTAL)
COUNT_FAILED_TOTAL: getJobStat(stat: COUNT_FAILED, timeFrame: TOTAL)
COUNT_IN_PROGRESS_TOTAL: getJobStat(
stat: COUNT_IN_PROGRESS
timeFrame: TOTAL
)
COUNT_PENDING_TOTAL: getJobStat(stat: COUNT_PENDING, timeFrame: TOTAL)
COUNT_SCHEDULED_TOTAL: getJobStat(stat: COUNT_SCHEDULED, timeFrame: TOTAL)
COUNT_TIMED_OUT_TOTAL: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: TOTAL)
COUNT_ALL_T_10M: getJobStat(stat: COUNT_ALL, timeFrame: T_10M)
COUNT_CANCELLED_T_10M: getJobStat(stat: COUNT_CANCELLED, timeFrame: T_10M)
COUNT_DONE_T_10M: getJobStat(stat: COUNT_DONE, timeFrame: T_10M)
COUNT_FAILED_T_10M: getJobStat(stat: COUNT_FAILED, timeFrame: T_10M)
COUNT_IN_PROGRESS_T_10M: getJobStat(
stat: COUNT_IN_PROGRESS
timeFrame: T_10M
)
COUNT_PENDING_T_10M: getJobStat(stat: COUNT_PENDING, timeFrame: T_10M)
COUNT_SCHEDULED_T_10M: getJobStat(stat: COUNT_SCHEDULED, timeFrame: T_10M)
COUNT_TIMED_OUT_T_10M: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: T_10M)
COUNT_ALL_T_1H: getJobStat(stat: COUNT_ALL, timeFrame: T_1H)
COUNT_CANCELLED_T_1H: getJobStat(stat: COUNT_CANCELLED, timeFrame: T_1H)
COUNT_DONE_T_1H: getJobStat(stat: COUNT_DONE, timeFrame: T_1H)
COUNT_FAILED_T_1H: getJobStat(stat: COUNT_FAILED, timeFrame: T_1H)
COUNT_IN_PROGRESS_T_1H: getJobStat(stat: COUNT_IN_PROGRESS, timeFrame: T_1H)
COUNT_PENDING_T_1H: getJobStat(stat: COUNT_PENDING, timeFrame: T_1H)
COUNT_SCHEDULED_T_1H: getJobStat(stat: COUNT_SCHEDULED, timeFrame: T_1H)
COUNT_TIMED_OUT_T_1H: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: T_1H)
COUNT_ALL_T_24H: getJobStat(stat: COUNT_ALL, timeFrame: T_24H)
COUNT_CANCELLED_T_24H: getJobStat(stat: COUNT_CANCELLED, timeFrame: T_24H)
COUNT_DONE_T_24H: getJobStat(stat: COUNT_DONE, timeFrame: T_24H)
COUNT_FAILED_T_24H: getJobStat(stat: COUNT_FAILED, timeFrame: T_24H)
COUNT_IN_PROGRESS_T_24H: getJobStat(
stat: COUNT_IN_PROGRESS
timeFrame: T_24H
)
COUNT_PENDING_T_24H: getJobStat(stat: COUNT_PENDING, timeFrame: T_24H)
COUNT_SCHEDULED_T_24H: getJobStat(stat: COUNT_SCHEDULED, timeFrame: T_24H)
COUNT_TIMED_OUT_T_24H: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: T_24H)
}

Sample Variables

getJobStat(stat: COUNT_ALL, timeFrame: TOTAL)

Response Type

Int

Sample Response

{
"data": {
"getJobStat": 105179
}
}

Get Scheduled Jobs Status Statistics

Description

Count the number of scheduled jobs based on their statuses, particularly failed, pending, or cancelled jobs. status: SCHEDULED to each getJobStat query to isolated *scheduled* jobs.

query {
COUNT_ALL_TOTAL: getJobStat(stat: COUNT_ALL, timeFrame: TOTAL, status: SCHEDULED)
COUNT_CANCELLED_TOTAL: getJobStat(stat: COUNT_CANCELLED, timeFrame: TOTAL, status: SCHEDULED)
COUNT_DONE_TOTAL: getJobStat(stat: COUNT_DONE, timeFrame: TOTAL, status: SCHEDULED)
COUNT_FAILED_TOTAL: getJobStat(stat: COUNT_FAILED, timeFrame: TOTAL, status: SCHEDULED)
COUNT_IN_PROGRESS_TOTAL: getJobStat(
stat: COUNT_IN_PROGRESS
timeFrame: TOTAL
)
COUNT_PENDING_TOTAL: getJobStat(stat: COUNT_PENDING, timeFrame: TOTAL, status: SCHEDULED)
COUNT_SCHEDULED_TOTAL: getJobStat(stat: COUNT_SCHEDULED, timeFrame: TOTAL, status: SCHEDULED)
COUNT_TIMED_OUT_TOTAL: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: TOTAL, status: SCHEDULED)
COUNT_ALL_T_10M: getJobStat(stat: COUNT_ALL, timeFrame: T_10M)
COUNT_CANCELLED_T_10M: getJobStat(stat: COUNT_CANCELLED, timeFrame: T_10M, status: SCHEDULED)
COUNT_DONE_T_10M: getJobStat(stat: COUNT_DONE, timeFrame: T_10M, status: SCHEDULED)
COUNT_FAILED_T_10M: getJobStat(stat: COUNT_FAILED, timeFrame: T_10M, status: SCHEDULED)
COUNT_IN_PROGRESS_T_10M: getJobStat(
stat: COUNT_IN_PROGRESS
timeFrame: T_10M
)
COUNT_PENDING_T_10M: getJobStat(stat: COUNT_PENDING, timeFrame: T_10M, status: SCHEDULED)
COUNT_SCHEDULED_T_10M: getJobStat(stat: COUNT_SCHEDULED, timeFrame: T_10M, status: SCHEDULED)
COUNT_TIMED_OUT_T_10M: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: T_10M, status: SCHEDULED)
COUNT_ALL_T_1H: getJobStat(stat: COUNT_ALL, timeFrame: T_1H, status: SCHEDULED)
COUNT_CANCELLED_T_1H: getJobStat(stat: COUNT_CANCELLED, timeFrame: T_1H, status: SCHEDULED)
COUNT_DONE_T_1H: getJobStat(stat: COUNT_DONE, timeFrame: T_1H, status: SCHEDULED)
COUNT_FAILED_T_1H: getJobStat(stat: COUNT_FAILED, timeFrame: T_1H, status: SCHEDULED)
COUNT_IN_PROGRESS_T_1H: getJobStat(stat: COUNT_IN_PROGRESS, timeFrame: T_1H, status: SCHEDULED)
COUNT_PENDING_T_1H: getJobStat(stat: COUNT_PENDING, timeFrame: T_1H, status: SCHEDULED)
COUNT_SCHEDULED_T_1H: getJobStat(stat: COUNT_SCHEDULED, timeFrame: T_1H, status: SCHEDULED)
COUNT_TIMED_OUT_T_1H: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: T_1H, status: SCHEDULED)
COUNT_ALL_T_24H: getJobStat(stat: COUNT_ALL, timeFrame: T_24H)
COUNT_CANCELLED_T_24H: getJobStat(stat: COUNT_CANCELLED, timeFrame: T_24H, status: SCHEDULED)
COUNT_DONE_T_24H: getJobStat(stat: COUNT_DONE, timeFrame: T_24H, status: SCHEDULED)
COUNT_FAILED_T_24H: getJobStat(stat: COUNT_FAILED, timeFrame: T_24H, status: SCHEDULED)
COUNT_IN_PROGRESS_T_24H: getJobStat(
stat: COUNT_IN_PROGRESS
timeFrame: T_24H
, status: SCHEDULED
)
COUNT_PENDING_T_24H: getJobStat(stat: COUNT_PENDING, timeFrame: T_24H, status: SCHEDULED)
COUNT_SCHEDULED_T_24H: getJobStat(stat: COUNT_SCHEDULED, timeFrame: T_24H, status: SCHEDULED)
COUNT_TIMED_OUT_T_24H: getJobStat(stat: COUNT_TIMED_OUT, timeFrame: T_24H, status: SCHEDULED)
}

Sample Variables

getJobStat(stat: COUNT_ALL, timeFrame: TOTAL, status: SCHEDULED)

Response Type

Int

Sample Response

{
"data": {
"getJobStat": 179
}
}

Create a Service

Description

Services are currently pipeline jobs which have an activeTimeout and timeout of -1, ie. never ending jobs, schedule = "immediate", and with exposedPort != null

mutation CreateService(
$type: String!
$maxRetries: Int!
$yamlPath: String!
$jobName: String! = ""
$exposedPort: String = "8787"
$parameters: ParameterCreateNestedManyWithoutPipelineJobInput
$gitServer: HyperplaneVCServerCreateNestedOneWithoutPipelineJobsInput
$hyperplaneUserEmail: String!
$branchName: String
) {
createPipelineJob(
data: {
jobType: $type,
jobName: $jobName,
maxRetries: $maxRetries,
pipelineYamlPath: $yamlPath,
parameters: $parameters,
hyperplaneVCServer: $gitServer,
hyperplaneUserEmail: $hyperplaneUserEmail,
branchName: $branchName,
exposedPort: $exposedPort,
timeout: -1,
activeTimeout: -1,
schedule: "immediate"
}
) {
id
pipelineYamlPath
schedule
status
statusReason
output
startTime
completionTime
daskDashboardUrl
timeout
outputNotebooksPath
activeTimeout
maxRetries
exposedPort
jobType
parameters {
key
value
}
}
}

Sample Variables

{
"type": "basic",
"maxRetries": 2,
"jobName": "test",
"yamlPath": "examples/pipeline.yaml",
"hyperplaneUserEmail": "demo@shakudo.io",
"branchName": "demo"
}

Parameters

FieldTypeDefinition
typeString!Name of Shakudo platform Podspec/Image, default or custom. Example: "basic"
timeoutInt!The maximum time in seconds that the pipeline may run, starting from the moment of job submission. Set to -1 for Services.
activeTimeoutIntThe maximum time in seconds that the pipeline may run once it is picked up. Set to -1 for Services.
maxRetriesInt!The maximum number of attempts to run your pipeline job before returning an error, even if timeouts are not reached. Default: 2
yamlPathStringThe relative path to the .yaml file used to run this pipeline job. Example: "example_notebooks/pipelines/python_hello_world_pipeline/pipeline.yaml"
exposedPortStringOnly enabled for Shakudo Services. The port that Services use to expose the pod to other pods within the cluster. Its presence is a current indicator of whether a job is a Service.
scheduleStringSet to immediate for Services
parametersParameterCreateNestedManyWithoutPipelineJobInputKey-value pairs that can be used within the container environment
gitServerHyperplaneVCServerCreateNestedOneWithoutPipelineJobsInputGit server object, retrievable by searching git servers by name (hyperplaneVCServers) and using resulting id in the following manner: { connect: { id: $gitServerId } }
hyperplaneUserEmailString!Shakudo platform user email
branchNameStringThe name of the specific git branch that contains the pipeline YAML file and pipeline scripts. If commitID is not specified, the latest commit is used. If not specified, default branch is used.

Response Type

PipelineJob

Sample Response

{
"data": {
"createPipelineJob": {
"id": "9276a796-229f-4ede-a2cf-a7cf329dab6a",
"pipelineYamlPath": "examples/pipeline.yaml",
"schedule": "immediate",
"status": "pending",
"statusReason": null,
"output": null,
"startTime": "2023-07-06T14:51:35.506Z",
"completionTime": null,
"daskDashboardUrl": null,
"timeout": -1,
"outputNotebooksPath": null,
"activeTimeout": -1,
"maxRetries": 2,
"exposedPort": "8787",
"jobType": "basic",
"parameters": []
}
}
}

Create a Service using PodSpec JSON (getUserServicePodSpec)

Description

Create a Service using a PodSpec JSON object that is customizable.

Retrieve UserServicePodSpec

query GetUserServicePodSpec(
$exposedPort: String
$parameters: ParametersInput
$gitServerName: String
$noGitInit: Boolean
$imageUrl: String
$userEmail: String!
$noHyperplaneCommands: Boolean
$commitId: String
$branchName: String!
$pipelineYamlPath: String!
$jobType: String!
) {
getUserServicePodSpec(
exposedPort: $exposedPort
parameters: $parameters
gitServerName: $gitServerName
noGitInit: $noGitInit
imageUrl: $imageUrl
userEmail: $userEmail
noHyperplaneCommands: $noHyperplaneCommands
commitId: $commitId
branchName: $branchName
pipelineYamlPath: $pipelineYamlPath
jobType: $jobType
)
}

Sample Variables

{
"userEmail": "demo@shakudo.io",
"branchName": "demo",
"pipelineYamlPath": "examples/pipeline.yaml",
"jobType": "basic"
}

Parameters

FieldTypeDescription
exposedPortStringOnly enabled for Shakudo Services. The port that Services use to expose the pod to other pods within the cluster. Its presence is a current indicator of whether a job is a Service.
parametersParametersInputKey-value pairs that can be used within the container environment.
gitServerNameStringThe name of the Git server used for the pipeline job.
noGitInitBooleanSpecifies whether the Git server initialization is skipped for the pipeline job.
imageUrlStringThe URL of the image used for the pipeline job.
userEmailString!Shakudo platform user email for the user who created the session.
noHyperplaneCommandsBooleanSpecifies whether default Shakudo platform commands are used for the pipeline job creation.
commitIdStringThe commit hash for the specific commit used to pull the latest files for the pipeline.
branchNameString!The name of the specific git branch that contains the pipeline YAML file and pipeline scripts.
pipelineYamlPathString!The relative path to the .yaml file used to run this pipeline job.
jobTypeString!Name of the Shakudo platform Podspec/Image used for the pipeline job. eg. "basic"

Create Service using UserServicePodSpec result

mutation CreateService(
$podSpec: JSON!
$jobName: String! = ""
$userEmail: String!
$exposedPort: String! = "8787"
$pipelineYamlPath: String!
) {
createPipelineJob (data: {
jobName: $jobName,
podSpec: $podSpec,
hyperplaneUserEmail: $userEmail,
pipelineYamlPath: $pipelineYamlPath,
exposedPort: $exposedPort,
timeout: -1,
activeTimeout: -1,
schedule: "immediate"
}
) {
id
pipelineYamlPath
schedule
status
statusReason
output
startTime
completionTime
daskDashboardUrl
timeout
outputNotebooksPath
activeTimeout
maxRetries
exposedPort
jobType
parameters {
key
value
}
}
}

Sample Variables

{
"userEmail": "demo@shakudo.io",
"exposedPort": "8787",
"branchName": "main",
"pipelineYamlPath": "examples/pipeline.yaml",
"jobType": "basic",
"jobName": "test-service",
"podSpec": <getUserServicePodSpec field result>
}

Parameters

FieldTypeDescription
podSpecJSON!The JSON object representing the PodSpec configuration for the pipeline job.
jobNameString!The name of the pipeline job.
userEmailString!Shakudo platform user email for the user who created the session.
exposedPortString!Only enabled for Shakudo Services. The port that Services use to expose the pod to other pods within the cluster. Its presence is a current indicator of whether a job is a Service. Default value: "8787".
pipelineYamlPathString!The relative path to the .yaml file used to run this pipeline job.

Response Type

PipelineJob

Sample Response

{
"data": {
"createPipelineJob": {
"id": "9f8f0524-6d67-4996-bd45-8a2434d97c1f",
"pipelineYamlPath": "examples/pipeline.yaml",
"schedule": "immediate",
"status": "pending",
"statusReason": null,
"output": null,
"startTime": "2023-06-30T16:03:42.668Z",
"completionTime": null,
"daskDashboardUrl": null,
"timeout": -1,
"outputNotebooksPath": null,
"activeTimeout": -1,
"maxRetries": 2,
"exposedPort": "8787",
"jobType": "basic",
"parameters": []
}
}
}

Get a List of Services

Description

Get a list of services — services are pipeline jobs which have an activeTimeout and timeout of -1, ie. never ending jobs, schedule = "immediate", and with exposedPort != null

query services($offset: Int, $limit: Int!, $status: String!) {
pipelineJobs(orderBy: [{pinned: desc},{ startTime: desc}], take: $limit, skip: $offset, where: {
AND: [
{activeTimeout: {equals: -1}},
{timeout: {equals: -1}},
{timeout: {equals: "immediate"}},
{status: {equals: $status}}
]
}) {
id
exposedPort
pinned
pipelineYamlPath
schedule
status
statusReason
startTime
completionTime
daskDashboardUrl
timeout
output
outputNotebooksPath
activeTimeout
duration
jobType
schedule
estimatedCost
owner
maxRetries
}
}

Sample Variables

{
"limit": 10,
"status": "in progress"
}

Parameters

FieldTypeDescription
offsetIntThe number of records to skip from the original result.
limitInt! (required)The number of records to retrieve.
statusString! (required)The status of the Kubernetes job that runs the pipeline job.

Response Type

PipelineJob

Sample Response

{
"data": {
"pipelineJobs": [
{
"id": "9276a796-229f-4ede-a2cf-a7cf329dab6a",
"exposedPort": "8787",
"pinned": false,
"pipelineYamlPath": "service.yaml",
"schedule": "immediate",
"status": "in progress",
"statusReason": null,
"startTime": "2023-03-23T02:34:51.850Z",
"completionTime": null,
"daskDashboardUrl": "client.hyperplane.dev/dashboard/",
"timeout": -1,
"output": null,
"outputNotebooksPath": null,
"activeTimeout": -1,
"duration": null,
"jobType": "basic",
"estimatedCost": null,
"owner": "demo",
"maxRetries": 0
},
{
"id": "abeee208-c717-42d9-81f9-9448cdf1473e",
"exposedPort": "8787",
"pinned": false,
"pipelineYamlPath": "service2.yaml",
"schedule": "immediate",
"status": "in progress",
"statusReason": null,
"startTime": "2022-11-18T19:21:23.504Z",
"completionTime": null,
"daskDashboardUrl": "client.hyperplane.dev/dashboard2/",
"timeout": -1,
"output": null,
"outputNotebooksPath": "gs://outputNotebookPath",
"activeTimeout": -1,
"duration": null,
"jobType": "basic",
"estimatedCost": null,
"owner": "demo",
"maxRetries": 0
}
]
}
}

Cancel all Scheduled Jobs

Cancel all Scheduled Jobs

mutation cancelScheduledJobs {
updateManyPipelineJob(
where: { status: { equals: "scheduled" } }
data: { status: { set: "cancelled" } }
) {
count
}
}

Cancel all Scheduled Jobs for a Specific User

Users can also add hyperplaneUserEmail: { equals: $userEmail } to cancel all scheduled jobs created by a particular user.

mutation cancelScheduledJobsForUser($userEmail: String!) {
updateManyPipelineJob(
where: { status: { equals: "scheduled" }, hyperplaneUserEmail: { equals: $userEmail } }
data: { status: { set: "cancelled" } }
) {
count
}
}

Sample Variables

{
"userEmail": "demo@shakudo.io"
}

Parameters

FieldTypeDescription
userEmailString! (required)The email corresponding to the user who created all the scheduled jobs to be cancelled.

Response Type

AffectedRowsOutput

Sample Response

{
"data": {
"updateManyPipelineJob": {
"count": 2
}
}
}

Get Job Parameters

Description

Get the list of parameters for a pipeline job

query jobParameters($id: String!) {
pipelineJobs(where: {id: {equals: $id}}) {
parameters {
key
value
id
pipelineJobId
}
}
}

Parameters

FieldTypeDescription
idString! (required)The ID of the job for which the parameters are being listed.

Sample Variables

{
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8"
}

Response Object Fields

Array of Parameters

Sample Response

{
"data": {
"pipelineJobs": [
{
"parameters": [
{
"key": "key",
"value": "value",
"id": "abeee208-c717-42d9-81f9-9448cdf1473e",
"pipelineJobId": "d1e5cd20-05d3-4517-b009-ec2e8e4f171d"
}
]
}
]
}
}

Delete a Job Parameter

Description

Delete a parameter for a pipeline job

# Retrieve parameterId
query GetPipelineJobParameters($jobId: String!){
pipelineJob(where:{id: $jobId}){
jobName
parameters{
id
key
value
}
}
}

mutation DeletePipelineJobParameter($parameterId: String!) {
deleteParameter(where: {
id: $parameterId
}) {
id
key
value
}
}

Parameters

FieldTypeDescription
jobIdString! (required)The ID of the job from which the parameter is being deleted.
parameterIdString! (required)The ID of the parameter being deleted. Retrieved from GetPipelineJobParameters

Sample Variables

{
"jobId": "65e3a289-1371-4009-9fb3-c03bfbcbebd8",
"parameterId": "9f8f0524-6d67-4996-bd45-8a2434d97c1f"
}

Response Type

Parameter

Sample Response

{
"data": {
"deleteParameter": {
"id": "9f8f0524-6d67-4996-bd45-8a2434d97c1f",
"key": "foo",
"value": "bar"
}
}
}

Update a Job Parameter

Description

Updates the key and/or value of a parameter.

mutation ($parameterId: String!, $keyValue: String, $valueValue: String) {
updateParameter(where: {id: $parameterId}, data: {
key: {set: $keyValue}
value: {set: $valueValue}
}) {
id
key
value
}
}

Parameters

FieldTypeDescription
parameterIdString! (required)ID of the parameter being updated.
keyValueStringNew value for the "key" field of the parameter.
valueValueStringNew value for the "value" field of the parameter.

Sample Variables

{
"parameterId": "65e3a289-1371-4009-9fb3-c03bfbcbebd8",
"keyValue": "newKey",
"valueValue": "newValue"
}

Response Type

Parameter

Sample Response

{
"data": {
"updateParameter": {
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8"
"keyValue": "newKey",
"valueValue": "newValue"
}
}
}

Types

HyperHubSession

Metadata for Sessions

billingProject: BillingProject
billingProjectId: String
collaborative: Boolean
completionTime: DateTime
currentPodEvents: String
department: String
duration: Int
estimatedCost: Float
gpuRequest: String
group: String
hyperplaneUser: HyperplaneUser!
hyperplaneUserEmail: String!
hyperplanepodspecName: String
id: String
imageHash: String
imageType: String
jLabUrl: String
notebookURI: String
owner: String
podEventsLog: String
podSpec: String
podSpecTemplate: HyperplanePodSpec
premptableNode: Boolean
resourceCPUlimit: String
resourceCPUrequest: String
resourceRAMlimit: String
resourceRAMrequest: String
runId: String
sshCommand: String
startTime: DateTime
status: String
statusReason: String
timeout: Int
useHyperplanepodspec: Boolean
userPvc: UserPvc
userPvcName: String
workerPodName: String
FieldTypeDefinition
billingProjectBillingProjectBilling project that user would like Session costs to contribute. Can either provide identifiers to connect to an existing billing project or can provide values to create a new billing project.
billingProjectIdStringBilling Project ID.
collaborativeBooleanToggle collaborative mode
completionTimeDateTimeCompletion time of the pipeline job
currentPodEventsStringDisplays log of states of pod (current events in pod)
departmentStringDisabled, not used
durationIntDuration of the pipeline job
estimatedCostFloatDisabled, plan on using it for tracking estimated cost of the job
gpuRequestStringNumber of gpus requested
groupStringNot used, leave as an empty string
hyperplaneUserHyperplaneUser!Shakudo platform user account details. Can either provide identifiers to connect to an existing account or can provide values to create a new user account.
hyperplaneUserEmailString!Shakudo platform user account email
hyperplanepodspecNameStringDisabled
idStringHyperHubSession object identifier
imageHashStringURL of custom image, same as imageUrl
imageTypeStringName of Shakudo platform Podspec/Image
jLabUrlStringURL for JupyterLab version of the Session environment
notebookURIStringBase url to access jupyter notebook and vscode notebooks
ownerStringUsername of the user account that owns the session, currently the user that created the session
podEventsLogStringSession pod event status log details
podSpecJson?Shakudo platform PodSpec environment config object as JSON
podSpecTemplateHyperplanePodSpecNot used, similar use to jobType
premptableNodeBooleanDisabled
resourceCPUlimitStringLimit to the number of CPUs to be allocated
resourceCPUrequestStringNumber of CPUs requested to be allocated
resourceRAMlimitStringMemory allocation limit
resourceRAMrequestStringMemory allocation amount request
runIdString
sshCommandString
startTimeDateTimeSession environment creation time
statusStringThe status of the Kubernetes job that runs the pipeline job
statusReasonStringKubernetes job status details
timeoutIntThe maximum time in seconds that the pipeline may run, starting from the moment of job submission. Default: -1, i.e., never timeout; 86400 on the dashboard
useHyperplanepodspecBoolean
userPvcUserPvcShakudo session persistent volume (drive) details. Can either provide identifiers to connect to an existing drive or can provide values to create a new drive. Default: not present, which corresponds with default drive claim-{user-email}.
userPvcNameStringPersistent volume name as found in Kubernetes. Typically includes the drive name found on the dashboard. Default: an empty string, which corresponds with the default drive claim-{user-email}.
workerPodNameString

Example:

{
"billingProject": null,
"collaborative": false,
"completionTime": "2023-05-17T21:26:02.310Z",
"currentPodEvents": null,
"department": null,
"duration": 901,
"estimatedCost": null,
"gpuRequest": null,
"group": "",
"hyperplaneUser": {
"id": "3661bd41-6ca9-4b20-a74b-c46ce6ff6951",
"email": "demo@shakudo.io"
},
"hyperplaneUserEmail": "demo@shakudo.io",
"hyperplanepodspecName": null,
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8",
"imageHash": "gcr.io/imageHash",
"imageType": "test-custom-image",
"jLabUrl": "",
"notebookURI": "",
"owner": "demo",
"podEventsLog": "Stopping container hyperhub-user",
"podSpec": null,
"podSpecTemplate": null,
"premptableNode": false,
"resourceCPUlimit": null,
"resourceCPUrequest": null,
"resourceRAMlimit": null,
"resourceRAMrequest": null,
"runId": null,
"sshCommand": null,
"startTime": "2023-05-17T21:11:00.948Z",
"status": "cancelled",
"statusReason": "Ready--true",
"timeout": 900,
"useHyperplanepodspec": false,
"userPvc": null,
"userPvcName": "",
"workerPodName": null
}

PipelineJob

Shakudo platform job config docs

type PipelineJob {
TritonClient: TritonClient
activeTimeout: Int!
billingProject: BillingProject
billingProjectId: String
branchName: String
branchNameOrCommit: BranchSelection
childJobs(cursor: PipelineJobWhereUniqueInput, distinct: [PipelineJobScalarFieldEnum!], orderBy: [PipelineJobOrderByInput!], skip: Int, take: Int, where: PipelineJobWhereInput): [PipelineJob!]!
cloudRunner: String
commitId: String
completionTime: DateTime
customCommand: String
customTrigger: String
dashboardPrefix: String
daskDashboardUrl: String
debuggable: Boolean!
department: String
displayedOwner: String!
duration: Int
estimatedCost: Float
exposedPort: String
grafanaLink: String!
group: String
hyperplaneUser: HyperplaneUser
hyperplaneUserEmail: String
hyperplaneUserId: String
hyperplaneVCServer: HyperplaneVCServer
hyperplaneVCServerId: String
hyperplanepodspecName: String
icon: String
id: String!
imageHash: String
jobCommand: String
jobName: String
jobType: String!
mappedUrl: String
maxHpaRange: Int!
maxRetries: Int!
maxRetriesPerStep: Int!
minReplicas: Int!
noGitInit: Boolean
noHyperplaneCommands: Boolean
noVSRewrite: Boolean
output: String
outputNotebooksPath: String
owner: String
parameters(cursor: ParameterWhereUniqueInput, distinct: [ParameterScalarFieldEnum!], orderBy: [ParameterOrderByInput!], skip: Int, take: Int, where: ParameterWhereInput): [Parameter!]!
parentJob: PipelineJob
parentJobId: String
pinned: Boolean!
pipelineYamlPath: String
podSpecTemplate: HyperplanePodSpec
podSpecTemplateId: String
preemptible: Boolean!
premptableNode: Boolean!
priorityClass: String!
runId: String
schedule: String!
sendNotification: Boolean
slackChannelName: String
sshCommand: String
startTime: DateTime!
status: String!
statusReason: String
steps(cursor: PipelineStepWhereUniqueInput, distinct: [PipelineStepScalarFieldEnum!], orderBy: [PipelineStepOrderByInput!], skip: Int, take: Int, where: PipelineStepWhereInput): [PipelineStep!]!
timeout: Int!
timeoutPerStep: Int
timezone: String!
useHyperplanepodspec: Boolean
workerPodName: String
}
FieldTypeDefinition
TritonClientTritonClientIf TritonClient is non-null, then this PipelineJob is a Triton Job. TritonClient stores Triton client instance object metadata.
activeTimeoutInt!The maximum time in seconds that the pipeline may run once it is picked up. Default: 86400, use -1 to never timeout.
billingProjectBillingProjectBilling project that user would like Job costs to contribute. Can either provide identifiers to connect to an existing billing project or can provide values to create a new billing project.
billingProjectIdStringBilling Project ID.
branchNameStringName of git branch.
branchNameOrCommitBranchSelectionEnum that states whether the image is based on branch or commit.
childJobs[PipelineJob!]!Jobs that spawned based on this job.
cloudRunnerStringCurrently disabled, but will be used to determine which cloud the job will run on. Will be added as part of the multicloud feature.
commitIdStringCommit hash for the commit used to pull the latest files for the pipeline.
completionTimeDateTimeCompletion time of the pipeline job.
customCommandStringNot used
customTriggerStringCurrently disabled on cluster, but will be used on KEDA jobs.
dashboardPrefixStringWhich URL subpath you want a Service to run in with respect to your Shakudo service domain. e.g., http://shakudoservice.io/modelV1.
daskDashboardUrlStringURL for dask dashboard
debuggableBoolean!Whether the debuggable service is enabled.
departmentStringNot used
displayedOwnerString!Username of the user account that owns the job, currently the user that created the job. Username is based on email.
durationIntDuration of the pipeline job.
estimatedCostFloatNot used
exposedPortStringOnly enabled for Shakudo Services. The port that Services use to expose the pod to other pods within the cluster. Its presence is a current indicator of whether a job is a Service.
grafanaLinkString!Link to Grafana logs.
groupStringDisabled, not used. Leave as empty string
hyperplaneUserHyperplaneUserShakudo platform user account details. Can either provide identifiers to connect to an existing account or can provide values to create a new user account.
hyperplaneUserEmailStringShakudo platform user email.
hyperplaneUserIdStringShakudo platform user ID.
hyperplaneVCServerHyperplaneVCServerShakudo Platform Git Server object.
hyperplaneVCServerIdStringGit server object ID.
hyperplanepodspecNameString
iconString
idString!
imageHashStringimageUrl
jobCommandString
jobNameStringPlain name of job viewable from the dashboard, is not necessarily unique.
jobTypeString!Name of Shakudo platform Podspec/Image.
mappedUrlString
maxHpaRangeInt!Maximum number of replicas for HPA (horizontal pod autoscaling).
maxRetriesInt!Maximum number of job retries.
maxRetriesPerStepInt!Maximum number of retries per job step.
minReplicasInt!Minimum number of K8s ReplicaSets.
noGitInitBooleanFalse if git server is to be set up using Shakudo platform workflow. Default: false.
noHyperplaneCommandsBooleanFalse if using default Shakudo platform commands on job creation. Required to use Shakudo platform jobs through the pipeline yaml, but not required if the image has its own setup. Default: false.
noVSRewriteBooleanOnly supported for Services. If enabled, the external prefix/subpath on the Shakudo domain directly corresponds to the same subpath within the Service.
outputString
outputNotebooksPathString
ownerStringTypically mirrors displayedOwner, refer primarily to displayedOwner.
parameters[Parameter!]!List of key-value parameters that are injected into the Job environment and can be used as environment variables.
parentJobPipelineJobThe info of that parent job if the current job spawned from another job.
parentJobIdStringParent job ID.
pinnedBoolean!Whether the job is pinned on the dashboard.
pipelineYamlPathStringRelative path to .yaml file for running pipeline
podSpecTemplateHyperplanePodSpecNot used, similar use to jobType.
podSpecTemplateIdStringID for the corresponding podSpecTemplate.
preemptibleBoolean!Determines whether the job can be preempted, i.e., timed out. This means that a Preemptible VM will be used.
premptableNodeBoolean!Not used
priorityClassString!K8s pod priority classification.
runIdString
scheduleString!Either "immediate" for an immediate job or a cron schedule expression for a scheduled job at the specified interval.
sendNotificationBoolean
slackChannelNameString
sshCommandString
startTimeDateTime!Job start time.
statusString!The status of the Kubernetes job that runs

| statusReason | String | Kubernetes job status detail | | steps | (cursor: PipelineStepWhereUniqueInput, distinct: [PipelineStepScalarFieldEnum!], orderBy: [PipelineStepOrderByInput!], skip: Int, take: Int, where: PipelineStepWhereInput): [PipelineStep!]! | pipeline step objects that correspond with individual script steps | | timeoutPerStep | Int | | | timezone | String | eg. UTC | | useHyperplanepodspec | Boolean | Not used | | workerPodName | String | Not used |

Example:

{
"TritonClient": null,
"activeTimeout": 82400,
"billingProject": null,
"billingProjectId": null,
"branchName": null,
"branchNameOrCommit": null,
"childJobs": [],
"cloudRunner": "",
"commitId": null,
"completionTime": null,
"customCommand": null,
"customTrigger": null,
"dashboardPrefix": null,
"daskDashboardUrl": null,
"debuggable": false,
"department": null,
"displayedOwner": "",
"duration": null,
"estimatedCost": null,
"exposedPort": null,
"grafanaLink": "https://grafana.sample.hyperplane.dev/explore",
"group": null,
"hyperplaneUser": null,
"hyperplaneUserEmail": null,
"hyperplaneUserId": null,
"hyperplaneVCServer": null,
"hyperplaneVCServerId": null,
"hyperplanepodspecName": null,
"icon": null,
"id": "b50e8ea9-1627-4a5d-b7c7-ebad6c801d0a",
"imageHash": "",
"jobCommand": null,
"jobName": null,
"jobType": "basic",
"mappedUrl": null,
"maxHpaRange": 1,
"maxRetries": 2,
"maxRetriesPerStep": 0,
"minReplicas": 1,
"noGitInit": false,
"noHyperplaneCommands": false,
"noVSRewrite": false,
"output": null,
"outputNotebooksPath": null,
"owner": null,
"parameters": [],
"parentJob": null,
"parentJobId": null,
"pinned": false,
"pipelineYamlPath": "example_pipeline.yaml",
"podSpecTemplate": null,
"podSpecTemplateId": null,
"preemptible": true,
"premptableNode": true,
"priorityClass": "shakudo-priority-class",
"runId": null,
"schedule": "immediate",
"sendNotification": null,
"slackChannelName": null,
"sshCommand": null,
"startTime": "2023-06-29T16:38:10.829Z",
"status": "pending",
"statusReason": null,
"steps": [],
"timeout": 82400,
"timeoutPerStep": null,
"timezone": "UTC",
"useHyperplanepodspec": false,
"workerPodName": null
}

Parameter

Key-value pairs that are injected into Jobs and Session environments

type Parameter {
PipelineJob: PipelineJob
id: String!
key: String!
pipelineJobId: String
value: String
}
FieldTypeDefinition
PipelineJobPipelineJobPipeline job that has this parameter
idString!The ID of the parameter
keyString!The key of the parameter
pipelineJobIdStringThe ID of the pipeline job that has this parameter
valueStringThe value of the parameter
{
"key": "key",
"value": "value",
"id": "b50e8ea9-1627-4a5d-b7c7-ebad6c801d0a",
"pipelineJobId": "833bd3d1-bb63-4289-99d8-25c2856f2fba"
}

HyperplaneVCServer

Git servers tied to remote git repositories

type HyperplaneVCServer {
defaultBranch: String!
id: String!
name: String!
pipelineJobs(cursor: PipelineJobWhereUniqueInput, distinct: [PipelineJobScalarFieldEnum!], orderBy: [PipelineJobOrderByInput!], skip: Int, take: Int, where: PipelineJobWhereInput): [PipelineJob!]!
serviceUrl: String
status: HyperplaneVCServerStatus!
url: String!
}
FieldTypeDefinition
defaultBranchString!The default git branch of the git server
idString!The ID of the git server (HyperplaneVCServer) object
nameString!The name of the git server
pipelineJobs[PipelineJob!]!The pipeline jobs that are connected to this git server. Mirrors pipelineJobs query
serviceUrlStringThe service URL (DNS record) for in-cluster connection access
statusHyperplaneVCServerStatus!The status of the git server resource
urlString!The remote repository SSH URL

HyperplanePodSpec

Environment configs for defining Shakudo resources; surrounds image, hardware, storage, kubernetes settings, etc.

type HyperplanePodSpec {
description: String!
displayName: String!
extraEnvars: String
extraTolerations: String
extraVolumeMounts: String
extraVolumes: String
gpuResourceType: String
hyperhubSessions(cursor: HyperHubSessionWhereUniqueInput, distinct: [HyperHubSessionScalarFieldEnum!], orderBy: [HyperHubSessionOrderByInput!], skip: Int, take: Int, where: HyperHubSessionWhereInput): [HyperHubSession!]!
hyperplaneImage: HyperplaneImage
hyperplaneImageId: String
hyperplaneUser: HyperplaneUser
hyperplaneUserEmail: String
hyperplaneUserId: String
icon: String!
id: String!
imagePullPolicy: String
imageUrl: String
nodeSelector: String
nodeSelectorKey: String
nodeSelectorValue: String
pipelineJobs(cursor: PipelineJobWhereUniqueInput, distinct: [PipelineJobScalarFieldEnum!], orderBy: [PipelineJobOrderByInput!], skip: Int, take: Int, where: PipelineJobWhereInput): [PipelineJob!]!
podSpec: String
podspecName: String!
pv: String
pvc: String
resourceCPUlimit: String
resourceCPUrequest: String
resourceGPUrequest: String
resourceRAMlimit: String
resourceRAMrequest: String
show: Boolean!
status: String!
statusReason: String
workingDir: String
}
FieldTypeDefinition
descriptionString!PodSpec description
displayNameString!General purpose display name for PodSpec that appears as a title on dashboard
extraEnvarsStringList of key-value parameters that are injected into any Shakudo resource environment
extraTolerationsStringAdditional pod toleration rules
extraVolumeMountsStringAdditional storage mounting rules. These are relative to the provided Volumes
extraVolumesStringAdditional persistent storage spaces
gpuResourceTypeStringType of GPU resource
hyperhubSessions[HyperHubSession!]!Sessions that currently use this PodSpec. Mirrors hyperhubSessions query
hyperplaneImageHyperplaneImageHyperplane image associated with the PodSpec
hyperplaneUserHyperplaneUserShakudo platform user account details
iconString!Not used
idString!ID of the PodSpec
imagePullPolicyString
imageUrlStringURL of image
nodeSelectorString
nodeSelectorKeyString
nodeSelectorValueString
pipelineJobs[PipelineJob!]!The pipeline jobs that are connected to this git server. Mirrors pipelineJobs query
podSpecString
podspecNameString!
pvStringPersistent volume associated with the PodSpec
pvcStringPersistent volume claim associated with the PodSpec
resourceCPUlimitStringCPU limit for resource allocation
resourceCPUrequestStringCPU request for resource allocation
resourceGPUrequestStringGPU request for resource allocation
resourceRAMlimitStringRAM limit for resource allocation
resourceRAMrequestStringRAM request for resource allocation
showBoolean!
statusString!Status of the PodSpec
statusReasonStringReason for the PodSpec status
workingDirStringWorking directory for the PodSpec

Operations

hyperHubSessions

Signature

hyperHubSessions(
cursor: HyperHubSessionWhereUniqueInput,
distinct: [HyperHubSessionScalarFieldEnum!],
orderBy: [HyperHubSessionOrderByInput!],
skip: Int,
take: Int,
where: HyperHubSessionWhereInput
): [HyperHubSession!]!

Function Description

Retrieves a list of Shakudo platform session metadata, allowing for pagination (cursor and offset-based) and filtering.

Input Object Fields

FieldTypeDefinition
cursorHyperHubSessionWhereUniqueInputStarting session value to paginate from using cursor-based pagination, i.e., the current result starts from this session record.
distinct[HyperHubSessionScalarFieldEnum!]List of fields where their values will remain distinct per record.
orderBy[HyperHubSessionOrderByInput!]List of fields that will be used to order the results, ordering precedence determined by the location in the list.
skipIntThe number of records to skip from the original result.
takeIntThe maximum number of records to show in the result.
whereHyperHubSessionWhereInputConditional values to filter for a specific HyperHubSession object.

Request Example

query HyperhubSessions($limit: Int!, $email: String, $status: String) {
hyperHubSessions(orderBy:{startTime: desc}, take: $limit, where: {
hyperplaneUserEmail: {equals: $email},
status: {equals: $status},
}) {
id
hyperplaneUserEmail
status
imageType
jLabUrl
notebookURI
estimatedCost
department
resourceCPUlimit
resourceRAMlimit
resourceCPUrequest
resourceRAMrequest
gpuRequest
startTime
completionTime
}
countHyperHubSessions
}

variables

{
"limit": 10,
"email": "demo@shakudo.io",
"status": "in progress"
}

Response Object Fields

HyperHubSession

Response Example

{
"data": {
"hyperHubSessions": [
{
"id": "78ba5679-1fd0-475a-88b0-d1877413747f",
"hyperplaneUserEmail": "demo@shakudo.io",
"status": "in progress",
"imageType": "basic",
"jLabUrl": "client/hyperplane.dev/jlabUrl/",
"notebookURI": "ssh demo-pvc-entry@demo.dev",
"estimatedCost": null,
"department": null,
"resourceCPUlimit": null,
"resourceRAMlimit": null,
"resourceCPUrequest": null,
"resourceRAMrequest": null,
"gpuRequest": null,
"startTime": "2023-06-28T15:32:40.090Z",
"completionTime": null
}
],
"countHyperHubSessions": 3006
}
}

createHyperHubSession

Signature

createHyperHubSession(
data: HyperHubSessionCreateInput!
): HyperHubSession!

Function Description

Creates a Shakudo Session environment, a data development environment comes with pre-configured environments, typically accessible in the form of a jupyter notebook.

Input Object Fields

FieldTypeDescription
dataHyperHubSessionCreateInputHyperHubSession object that contains field values used to create a Session. Check HyperHubSessionCreateInput for specific fields.

Request Example

mutation CreateHyperHubSession($input: HyperHubSessionCreateInput!) {
createHyperHubSession(data: $input) {
id
hyperplaneUserEmail
status
imageType
jLabUrl
estimatedCost
department
resourceCPUlimit
resourceRAMlimit
resourceCPUrequest
resourceRAMrequest
gpuRequest
startTime
completionTime
timeout
group
billingProjectId
}
}

Sample Variables

{
"input": {
"collaborative": false,
"imageType": "basic",
"imageUrl": "",
"timeout": 900,
"userPvcName": "",
"group": "",
"hyperplaneUserId": "2a9980d9-f43c-4369-b71e-70d12d369e47",
"billingProjectId": {
"connect": {
"id": "284f0a8e-52d9-4a57-be42-f461fc4315c7"
}
},
"hyperplaneUserEmail": "demo@shakudo.io"
}
}

Response Object Fields

GraphQL Docs

Response Example

{
"data": {
"createHyperHubSession": {
"id": "f48e3b18-bced-4a8c-85b9-b3c2fdd1a06a",
"hyperplaneUserEmail": "demo@shakudo.io",
"status": "pending",
"imageType": "basic",
"jLabUrl": null,
"estimatedCost": null,
"department": null,
"resourceCPUlimit": null,
"resourceRAMlimit": null,
"resourceCPUrequest": null,
"resourceRAMrequest": null,
"gpuRequest": null,
"startTime": "2023-06-27T19:27:43.987Z",
"completionTime": null,
"timeout": 900,
"group": "",
"billingProjectId": "f6a3911d-e048-49f0-96d8-1abd930b66db"
}
}
}

updateHyperHubSession

Signature

updateHyperHubSession(
data: HyperHubSessionUpdateInput!
where: HyperHubSessionWhereUniqueInput!
): HyperHubSession

Function Description

Updates the fields for a specific Session based on the provided data and conditions provided.

Input Object Fields

FieldTypeDefinition
dataHyperHubSessionUpdateInput!HyperHubSession partial object that contains field values used to update, specified in the format [field]: {[action]: [value]}
whereHyperHubSessionWhereUniqueInput!Conditional values to filter for a specific HyperHubSession object

Request Example: Cancelling a Session

mutation UpdateHyperHubSession($id: String!) {
updateHyperHubSession(where: {id: $id}, data: {
status: {set: "cancelled"}
}) {
id
status
}
}

variables

{ 
"id": "7b728979-71b7-426c-9847-6fe3e29a6438"
}

Response Object Fields

HyperHubSession

Response Example

{
"data": {
"updateHyperHubSession": {
"id": "7b728979-71b7-426c-9847-6fe3e29a6438",
"status": "cancelled"
}
}
}

getJobStat

Signature

getJobStat(
stat: StatType!,
status: StatusType,
timeFrame: TimeFrame!
): Int

Function Description

Retrieves job count statistics based on the conditions provided.

Input Object Fields

FieldTypeDescription
statStatType!Statistic type options. Possible values: COUNT_ALL, COUNT_CANCELLED, COUNT_DONE, COUNT_FAILED, COUNT_IN_PROGRESS, COUNT_PENDING, COUNT_SCHEDULED, COUNT_TIMED_OUT, COUNT_TRIGGERED.
statusStatusTypeStatus type options. Possible values: ALL, SCHEDULED, TRIGGERED.
timeFrameTimeFrame!Timeframe options. Possible values: TOTAL, T_1H, T_10M, T_24H.

Request Example

query {
getJobStat(stat: COUNT_ALL, timeFrame: TOTAL)
}

Response Object Fields

Int

Response Example

{
"data": {
"getJobStat": 105179
}
}

createPipelineJob

Signature

createPipelineJob(
data: PipelineJobCreateInput!
): PipelineJob!

Function Description

Creates a Shakudo platform job, which allows users to run task scripts using custom configurations, either immediately as an “Immediate job”, at scheduled intervals as a “Scheduled Job”, or indefinitely as a “Service”.

Immediate jobs: schedule = “immediate”

Scheduled jobs: schedule ≠ “immediate”, schedule is set to cron schedule expression, eg. 0 0 * * * for a job running every minute

Service: timeout and activeTimeout set to -1 and exposedPort != null, particularly set to a valid port

Input Object Fields

data: PipelineJob object that contains field values used to create a PipelineJob. Check PipelineJobCreateInput for specific fields.

Example fields:

FieldTypeDefinition
typeString!Name of Shakudo platform Podspec/Image, default or custom. Example: "basic"
timeoutInt!The maximum time in seconds that the pipeline may run, starting from the moment of job submission. Default: -1 (never timeout). Example: 86400
activeTimeoutIntThe maximum time in seconds that the pipeline may run once it is picked up. Default: -1 (never timeout). Example: 86400
maxRetriesInt!The maximum number of attempts to run your pipeline job before returning an error, even if timeouts are not reached. Default: 2
yamlPathStringThe relative path to the .yaml file used to run this pipeline job. Example: "example_notebooks/pipelines/python_hello_world_pipeline/pipeline.yaml"
exposedPortStringOnly enabled for Shakudo Services. The port that Services use to expose the pod to other pods within the cluster. Its presence is a current indicator of whether a job is a Service.
scheduleStringEither "immediate" for an immediate job or a cron schedule expression for a scheduled job at the specified interval.
parametersParameterCreateNestedManyWithoutPipelineJobInputKey-value pairs that can be used within the container environment
gitServerHyperplaneVCServerCreateNestedOneWithoutPipelineJobsInputGit server object, retrievable by searching git servers by name (hyperplaneVCServers) and using resulting id in the following manner: { connect: { id: $gitServerId } }
hyperplaneUserEmailString!Shakudo platform user email
branchNameStringThe name of the specific git branch that contains the pipeline YAML file and pipeline scripts. If commitID is not specified, the latest commit is used. If not specified, default branch is used.
podSpecJSONShakudo platform PodSpec config object as a JSON object

Request Example

Variables

Response Object Fields

PipelineJob

Response Example

updatePipelineJob

Signature

updatePipelineJob(
data: PipelineJobUpdateInput!
where: PipelineJobWhereUniqueInput!
): PipelineJob

Function Description

Updates the database fields of a specific PipelineJob. Check PipelineJobUpdateInput to see how to do so.

Input Object Fields

FieldTypeDescription
dataPipelineJobUpdateInput!PipelineJob partial object that contains field values used to update, specified in the following format [field]: {[action]: [value]}. Check the PipelineJobUpdateInput type for specific fields and their descriptions.
wherePipelineJobWhereUniqueInput!Conditional values to filter for a specific PipelineJob object. Check the PipelineJobWhereUniqueInput type for specific fields and their descriptions.

Request Example

mutation UpdatePipelineJob($jobId: String!, $parameterId: String!) {
updatePipelineJob(where: {id: $jobId},
data: {
parameters: {disconnect: {id: $parameterId}},
}) {
id
}
}

Variables

{
"jobId": "65e3a289-1371-4009-9fb3-c03bfbcbebd8",
"parameterId": "9f8f0524-6d67-4996-bd45-8a2434d97c1f"
}

Response Object Fields

PipelineJob

Response Example

{
"data": {
"updatePipelineJob": {
"id": "9f8f0524-6d67-4996-bd45-8a2434d97c1f"
}
}
}

updateParameter

Signature

updateParameter(
data: ParameterUpdateInput!
where: ParameterWhereUniqueInput!
): Parameter

Function Description

Updates the database fields of a specific Parameter. Parameters are objects that represent environment variables within Shakudo resources like Jobs and Sessions.

Input Object Fields

FieldTypeDescription
dataPipelineJobUpdateInput!Parameter partial object that contains field values used to update, specified in the following format [field]: {[action]: [value]} , where [field] is the name of the field to update, [action] is the update action (e.g., set, increment, decrement, etc.), and [value] is the new value for the field. Check the ParameterUpdateInput type for specific fields and their descriptions.
wherePipelineJobWhereUniqueInput!Conditional values to filter for a specific PipelineJob object. Check the PipelineJobWhereUniqueInput type for specific fields and their descriptions.

Request Example

mutation ($parameterId: String!, $keyValue: String, $valueValue: String) {
updateParameter(where: {id: $parameterId}, data: {
key: {set: $keyValue}
value: {set: $valueValue}
}) {
id
key
value
}
}

Sample Variables

{
"parameterId": "65e3a289-1371-4009-9fb3-c03bfbcbebd8",
"keyValue": "newKey",
"valueValue": "newValue"
}

Response Type

Parameter

Sample Response

{
"data": {
"updateParameter": {
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8"
"keyValue": "newKey",
"valueValue": "newValue"
}
}
}

createHyperplaneVCServer

Signature

createHyperplaneVCServer(data: HyperplaneVCServerCreateInput!): HyperplaneVCServer!

Function Description

Creates a git server connected to a specific git repository to make it accessible on the Shakudo platform.

Input Object Fields

FieldTypeDescription
dataHyperplaneVCServerCreateInput!HyperplaneVCServer object that contains field values used to create a git server. Check the HyperplaneVCServerCreateInput type for specific fields and their descriptions.

Request Example

mutation($data: HyperplaneVCServerCreateInput!) {
createHyperplaneVCServer(data: $data) {
id
defaultBranch
name
url
}
}

Variables

{
"data": {
"defaultBranch": "main",
"name": "examples-graphql-test",
"url": "git@github.com:org/sample.git"
}
}

Response Object Fields

HyperplaneVCServer

Response Example

{
"data": {
"createHyperplaneVCServer": {
"id": "3aff9f7c-c208-44e2-b389-495a11708349",
"defaultBranch": "main",
"name": "examples-graphql-test",
"pipelineJobs": [],
"status": "CREATING",
"url": "git@github.com:org/sample.git"
}
}
}

hyperplaneVCServers

Signature

hyperplaneVCServers(
cursor: HyperplaneVCServerWhereUniqueInput,
distinct: [HyperplaneVCServerScalarFieldEnum!],
orderBy: [HyperplaneVCServerOrderByInput!],
skip: Int,
take: Int,
where: HyperplaneVCServerWhereInput
): [HyperplaneVCServer!]!

Function Description

Retrieves a list of git server instances based on conditions provided, allowing for pagination (cursor and offset-based) and filtering.

Input Object Fields

FieldTypeDescription
cursorHyperplaneVCServerWhereUniqueInputStarting git server value to paginate from using cursor-based pagination. The current result starts from this git server record.
distinct[HyperplaneVCServerScalarFieldEnum!]List of fields where their values will remain distinct per record.
orderBy[HyperplaneVCServerOrderByInput!]List of fields that will be used to order the results. The ordering precedence is determined by the location in the list.
skipIntThe number of records to skip from the original result.
takeIntThe maximum number of records to show in the result.
whereHyperplaneVCServerWhereInputConditional values to filter for a specific HyperplaneVCServer object.

Request Example


query ($name: String!) {
hyperplaneVCServers(where: { name: {equals: $name } }){
id
defaultBranch
name
pipelineJobs {
id
}
status
url
serviceUrl
}
}

Variables

{
"name": "examples-graphql-test"
}

Response Object Fields

Array of HyperplaneVCServer

Response Example

{
"data": {
"hyperplaneVCServers": [
{
"id": "65e3a289-1371-4009-9fb3-c03bfbcbebd8",
"defaultBranch": "main",
"name": "examples-graphql-test",
"pipelineJobs": [],
"status": "CREATED",
"url": "git@github.com:org/sample.git",
"serviceUrl": "sample-service-url.namespace.svc.cluster.local"
}
]
}
}

getHyperhubSessionDefaultPodSpec

Signature

getHyperhubSessionPodSpec(
imageUrl: String = ""
userPvcName: String = ""
userEmail: String = ""
imageType: String = ""
): JSON

Function Description

Retrieves full PodSpec as JSON string for Sessions, which can be used and customized with granularity in createHyperHubSession by itself, instead of relying on creating a PodSpec object using createPodSpec, which has more limited options.

Input Object Fields

FieldTypeDescription
imageUrlStringURL of custom image, same as imageHash
userPvcNameStringPersistent volume name as found in Kubernetes. Typically includes the drive name found on the dashboard. Default: empty string, which corresponds with default drive claim-{user-email}.
userEmailStringShakudo platform user account email
imageTypeStringName of Shakudo platform Podspec/Image

Note: userEmail is required in Request example to identify the respective user, but is not actually required to use query.

Request Example

query GetHyperhubSessionPodSpec($imageType: String, $userPvcName: String = "", $userEmail: String!, $imageUrl: String) {
getHyperhubSessionPodSpec(
imageType: $imageType,
userPvcName: $userPvcName,
userEmail: $userEmail,
imageUrl: $imageUrl
)
}

Variables

{
"imageType": "basic",
"userEmail": "demo@shakudo.io"
}

Response Object Fields

JSON

getPipelineJobPodSpec

Signature

getPipelineJobPodSpec(
parameters: ParametersInput
gitServerName: String = ""
noGitInit: Boolean = false
imageUrl: String = ""
userEmail: String = ""
noHyperplaneCommands: Boolean = false
commitId: String = ""
branchName: String = ""
pipelineYamlPath: String = ""
debuggable: Boolean = false
jobType: String = ""
): JSON

Function Description

Retrieves full PodSpec as JSON string for PipelineJobs, which can be used and customized with granularity in createPipelineJob by itself, instead of relying on creating a PodSpec object using createPodSpec, which has more limited options.

Input Object Fields

FieldTypeDescription
parametersParametersInputList of key-value parameters that are injected into the Job environment and can be used as environment variables
gitServerNameString ("" if not provided)Git Server name, corresponds with HyperplaneVCServer.name, which is the display name assigned on the dashboard
noGitInitBoolean (false if not provided)False if git server is to be set up using default Shakudo platform workflow. Default: false
imageUrlString ("" if not provided)If the image is custom, then the image URL can be provided
userEmailString! (required)Shakudo platform user account email
noHyperplaneCommandsBooleanFalse if using default Shakudo platform commands on job creation. Required to use Shakudo platform jobs through the pipeline YAML, but not required if the image has its own setup. Default: false
commitIdString ("" if not provided)The commit ID with the versions of the pipeline YAML file and pipeline scripts wanted. Ensure that both are present if the commit ID is used. If left empty, assume that the latest commit on the branch is used
branchNameStringThe name of the specific git branch that contains the pipeline YAML file and pipeline scripts. If commitID is not specified, the latest commit is used. If not specified, default branch is used.
pipelineYamlPathString ("" if not provided)The relative path to the .yaml file used to run this pipeline job
debuggableBoolean (false if not provided)Whether to enable SSH-based debugging for the job, check the following tutorial for more details
jobTypeString ("" if not provided)Name of Shakudo platform Podspec/Image, default or custom

Request Example

query GetPipelineJobPodSpec(
$parameters: ParametersInput
$gitServerName: String = ""
$noGitInit: Boolean = false
$imageUrl: String = ""
$userEmail: String!
$noHyperplaneCommands: Boolean = false
$commitId: String = ""
$branchName: String!
$pipelineYamlPath: String!
$debuggable: Boolean = false
$jobType: String!
) {
getPipelineJobPodSpec(
parameters: $parameters
gitServerName: $gitServerName
noGitInit: $noGitInit
imageUrl: $imageUrl
userEmail: $userEmail
noHyperplaneCommands: $noHyperplaneCommands
commitId: $commitId
branchName: $branchName
pipelineYamlPath: $pipelineYamlPath
debuggable: $debuggable
jobType: $jobType
)
}

Variables

{
"userEmail": "demo@shakudo.io",
"branchName": "main",
"pipelineYamlPath": "example/pipeline.yaml",
"jobType": "basic"
}

Response Object Fields

JSON

getUserServicePodSpec

Signature

getUserServicePodSpec(
exposedPort: String = "8787"
parameters: ParametersInput
gitServerName: String = ""
noGitInit: Boolean = false
imageUrl: String = ""
userEmail: String = ""
noHyperplaneCommands: Boolean = false
commitId: String = ""
branchName: String = ""
pipelineYamlPath: String = ""
jobType: String = ""
): JSON

Function Description

Retrieves full PodSpec as JSON string for Services, which can be used and customized with granularity in createPipelineJob by itself, instead of relying on the parameters found in createPodSpec.

Input Object Fields

FieldTypeDescription
exposedPortStringThe exposed port for the job. Default value is 8787.
parametersParametersInputList of key-value parameters that are injected into the job environment and can be used as environment variables.
gitServerNameStringThe name of the Git server. It corresponds with the display name assigned on the HyperplaneVCServer dashboard. Default value is an empty string.
noGitInitBooleanSpecifies whether to set up the Git server using the default Shakudo platform workflow. Default value is false.
imageUrlStringThe URL of a custom image. If the image is custom, this field can be provided. Default: "" (empty string)
userEmailStringThe email of the Shakudo platform user account. This field is required.
noHyperplaneCommandsBooleanSpecifies whether to use default Shakudo platform commands on job creation. It is required to use Shakudo platform jobs through the pipeline YAML, but not required if the image has its own setup. Default value is false.
commitIdStringThe commit ID with the versions of the pipeline YAML file and pipeline scripts wanted. Ensure that both are present if commit ID is used. If left empty, assume that the latest commit on the branch is used. Default value is an empty string.
branchNameStringThe name of the specific Git branch that contains the pipeline YAML file and pipeline scripts. If commitId is not specified, the latest commit is used. This field is required.
pipelineYamlPathStringThe relative path to the .yaml file used to run this pipeline job. This field is required.
jobTypeStringThe name of the Shakudo platform Podspec/Image. If the empty string is provided, the Podspec used will be basic.

Request Example

query GetUserServicePodSpec(
$exposedPort: String! = "8787"
$parameters: ParametersInput
$gitServerName: String
$noGitInit: Boolean
$imageUrl: String
$userEmail: String!
$noHyperplaneCommands: Boolean
$commitId: String
$branchName: String!
$pipelineYamlPath: String!
$jobType: String!
) {
getUserServicePodSpec(
exposedPort: $exposedPort
parameters: $parameters
gitServerName: $gitServerName
noGitInit: $noGitInit
imageUrl: $imageUrl
userEmail: $userEmail
noHyperplaneCommands: $noHyperplaneCommands
commitId: $commitId
branchName: $branchName
pipelineYamlPath: $pipelineYamlPath
jobType: $jobType
)
}

Variables

{
"userEmail": "demo@shakudo.io",
"branchName": "main",
"pipelineYamlPath": "example/pipeline.yaml",
"jobType": "basic"
}

Response Object Fields

JSON