Instances

An instance is the virtual machine inside a VPS subscription. All requests need the VPS headers; the x-vps-subscription-id header selects the subscription. Sample responses show field types generated from the schema.

List Instances

Query · instance_listInstances

Lists the instances of a VPS subscription.

Arguments

NameTypeRequiredDescription
inputinstance_ListInstancesRequest_InputNoPaging and filter

input

FieldTypeRequiredDescription
pageSizeIntNoNumber of instances per page
pageTokenStringNoThe nextPageToken from the previous page
lifecycleStateinstance_LifecycleStateNoFilter by lifecycle state. Not used by the UI

The x-vps-subscription-id header selects the subscription whose instances are listed.

Variables

{
  "input": {
    "pageSize": 10
  }
}

Request

query Instance_listInstances($input: instance_ListInstancesRequest_Input) {
  instance_listInstances(input: $input) {
    instances {
      id
      projectId
      name
      lifecycleState
      desiredRuntime
      observedRuntime
      observedAt
      planKey
      imageKey
      vcpu
      memoryMb
      diskGb
      sshKeyIds
      addresses {
        family
        address
        index
        allocationId
      }
      highAvailability {
        enabled
        maxRestart
        maxRelocate
        tierKey
      }
      createdAt
      updatedAt
      cloudConfigId
      cloudConfigVersion
    }
    nextPageToken
  }
}

Response

{
  "data": {
    "instance_listInstances": {
      "instances": [
        {
          "id": "String",
          "projectId": "String",
          "name": "String",
          "lifecycleState": "instance_LifecycleState",
          "desiredRuntime": "RUNTIME_STATE_UNSPECIFIED | RUNTIME_STATE_RUNNING | RUNTIME_STATE_STOPPED",
          "observedRuntime": "RUNTIME_STATE_UNSPECIFIED | RUNTIME_STATE_RUNNING | RUNTIME_STATE_STOPPED",
          "observedAt": "google__protobuf__Timestamp",
          "planKey": "String",
          "imageKey": "String",
          "vcpu": "Int",
          "memoryMb": "Int",
          "diskGb": "Int",
          "sshKeyIds": ["String"],
          "addresses": [
            {
              "family": "ADDRESS_FAMILY_UNSPECIFIED | ADDRESS_FAMILY_IPV4 | ADDRESS_FAMILY_IPV6",
              "address": "String",
              "index": "Int",
              "allocationId": "String"
            }
          ],
          "highAvailability": {
            "enabled": "Boolean",
            "maxRestart": "Int",
            "maxRelocate": "Int",
            "tierKey": "String"
          },
          "createdAt": "google__protobuf__Timestamp",
          "updatedAt": "google__protobuf__Timestamp",
          "cloudConfigId": "String",
          "cloudConfigVersion": "Int"
        }
      ],
      "nextPageToken": "String"
    }
  }
}

Get Instance

Query · instance_getInstance

Gets a single instance by ID.

Arguments

NameTypeRequiredDescription
inputinstance_GetInstanceRequest_InputNoInstance to get

input

FieldTypeRequiredDescription
instanceIdStringNoThe instance ID. The UI skips the query until both the instance ID and subscription ID are known

Variables

{
  "input": {
    "instanceId": "<INSTANCE_ID>"
  }
}

Request

query Instance_getInstance($input: instance_GetInstanceRequest_Input) {
  instance_getInstance(input: $input) {
    instance {
      id
      projectId
      name
      lifecycleState
      desiredRuntime
      observedRuntime
      observedAt
      planKey
      imageKey
      vcpu
      memoryMb
      diskGb
      sshKeyIds
      addresses {
        family
        address
        index
        allocationId
      }
      highAvailability {
        enabled
        maxRestart
        maxRelocate
        tierKey
      }
      createdAt
      updatedAt
      cloudConfigId
      cloudConfigVersion
    }
  }
}

Response

{
  "data": {
    "instance_getInstance": {
      "instance": {
        "id": "String",
        "projectId": "String",
        "name": "String",
        "lifecycleState": "instance_LifecycleState",
        "desiredRuntime": "RUNTIME_STATE_UNSPECIFIED | RUNTIME_STATE_RUNNING | RUNTIME_STATE_STOPPED",
        "observedRuntime": "RUNTIME_STATE_UNSPECIFIED | RUNTIME_STATE_RUNNING | RUNTIME_STATE_STOPPED",
        "observedAt": "google__protobuf__Timestamp",
        "planKey": "String",
        "imageKey": "String",
        "vcpu": "Int",
        "memoryMb": "Int",
        "diskGb": "Int",
        "sshKeyIds": ["String"],
        "addresses": [
          {
            "family": "ADDRESS_FAMILY_UNSPECIFIED | ADDRESS_FAMILY_IPV4 | ADDRESS_FAMILY_IPV6",
            "address": "String",
            "index": "Int",
            "allocationId": "String"
          }
        ],
        "highAvailability": {
          "enabled": "Boolean",
          "maxRestart": "Int",
          "maxRelocate": "Int",
          "tierKey": "String"
        },
        "createdAt": "google__protobuf__Timestamp",
        "updatedAt": "google__protobuf__Timestamp",
        "cloudConfigId": "String",
        "cloudConfigVersion": "Int"
      }
    }
  }
}

Create Instance

Mutation · instance_createInstance

Creates a new VPS instance. It starts a background operation.

Arguments

NameTypeRequiredDescription
inputinstance_CreateInstanceRequest_InputNoInstance details

input

FieldTypeRequiredDescription
nameStringNoInstance name. Required by the form
planKeyStringNoPlan key from instance_listPlans. Required by the form
imageKeyStringNoImage key from instance_listImages. Required by the form
sshKeyIds[String]NoIDs from instance_listSshKeys
cloudConfigStringNocloud-init user data. Sent only when the "cloud config" switch is on and the text parses
idempotencyKeyStringNo<name>-<8 random chars>
retainedAllocationIdStringNoNot used by the UI
highAvailabilityinstance_HighAvailability_InputNoNot used by the UI
cloudConfigRefinstance_CloudConfigRef_InputNoNot used by the UI

highAvailability

FieldTypeRequiredDescription
enabledBooleanNo
maxRestartIntNo
maxRelocateIntNo
tierKeyStringNo

cloudConfigRef

FieldTypeRequiredDescription
cloudConfigIdStringNo
versionIntNo

Variables

{
  "input": {
    "name": "web-01",
    "planKey": "<PLAN_KEY>",
    "imageKey": "<IMAGE_KEY>",
    "sshKeyIds": ["<SSH_KEY_ID>"],
    "idempotencyKey": "web-01-<8 random chars>"
  }
}

Request

mutation Instance_createInstance($input: instance_CreateInstanceRequest_Input) {
  instance_createInstance(input: $input) {
    operation {
      id
      instanceId
      kind
      state
      steps {
        ordinal
        phase
        state
      }
      errorCode
      errorMessage
      createdAt
      startedAt
      completedAt
    }
    rootPassword
  }
}

Response

{
  "data": {
    "instance_createInstance": {
      "operation": {
        "id": "String",
        "instanceId": "String",
        "kind": "instance_OperationKind",
        "state": "instance_OperationState",
        "steps": [
          {
            "ordinal": "Int",
            "phase": "instance_OperationPhase",
            "state": "instance_StepState"
          }
        ],
        "errorCode": "String",
        "errorMessage": "String",
        "createdAt": "google__protobuf__Timestamp",
        "startedAt": "google__protobuf__Timestamp",
        "completedAt": "google__protobuf__Timestamp"
      },
      "rootPassword": "String"
    }
  }
}