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
| Name | Type | Required | Description |
|---|---|---|---|
input | instance_ListInstancesRequest_Input | No | Paging and filter |
input
| Field | Type | Required | Description |
|---|---|---|---|
pageSize | Int | No | Number of instances per page |
pageToken | String | No | The nextPageToken from the previous page |
lifecycleState | instance_LifecycleState | No | Filter 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"
}
}
}
The instance detail page calls this with pageSize: DEFAULT_PAGE_SIZE and shows
instances[0] as "the" instance of the subscription; the subscription card
calls it with pageSize: 10. Because the subscription is sent as a header,
which Apollo's cache key cannot see, lists from different subscriptions share
one cache entry in the frontend. The frontend's TypeScript input type also
declares projectId, but that field is not in
instance_ListInstancesRequest_Input and the UI never sends it.
Get Instance
Query · instance_getInstance
Gets a single instance by ID.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
input | instance_GetInstanceRequest_Input | No | Instance to get |
input
| Field | Type | Required | Description |
|---|---|---|---|
instanceId | String | No | The 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"
}
}
}
}
Used by the rebuild form, the monitor page and the console popup. A lazy
variant (useLazyGetInstanceById, fetchPolicy: "network-only") is exported
by the frontend but not used.
Create Instance
Mutation · instance_createInstance
Creates a new VPS instance. It starts a background operation.
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
input | instance_CreateInstanceRequest_Input | No | Instance details |
input
| Field | Type | Required | Description |
|---|---|---|---|
name | String | No | Instance name. Required by the form |
planKey | String | No | Plan key from instance_listPlans. Required by the form |
imageKey | String | No | Image key from instance_listImages. Required by the form |
sshKeyIds | [String] | No | IDs from instance_listSshKeys |
cloudConfig | String | No | cloud-init user data. Sent only when the "cloud config" switch is on and the text parses |
idempotencyKey | String | No | <name>-<8 random chars> |
retainedAllocationId | String | No | Not used by the UI |
highAvailability | instance_HighAvailability_Input | No | Not used by the UI |
cloudConfigRef | instance_CloudConfigRef_Input | No | Not used by the UI |
highAvailability
| Field | Type | Required | Description |
|---|---|---|---|
enabled | Boolean | No | |
maxRestart | Int | No | |
maxRelocate | Int | No | |
tierKey | String | No |
cloudConfigRef
| Field | Type | Required | Description |
|---|---|---|---|
cloudConfigId | String | No | |
version | Int | No |
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"
}
}
}
The create form loads images and plans with availableOnly: true and SSH keys
with pageSize: 100. rootPassword is returned only once, when the platform
generates a root password; the UI keeps it in a dialog until the user clicks
Done. On success the cached instance_listInstances is evicted.
The frontend's TypeScript types declare an access input field
(VpsAccessMode: ACCESS_MODE_SSH_KEYS, ACCESS_MODE_ROOT_PASSWORD,
ACCESS_MODE_CONSOLE_AUTOLOGIN, ACCESS_MODE_UNSPECIFIED) and define a picker
for it. The testing gateway has no access field on
instance_CreateInstanceRequest_Input or instance_RebuildInstanceRequest_Input,
and no access-mode enum. The UI does not currently send access, and the picker
is not rendered. Do not send it: the gateway would reject the unknown input
field.