Skip to main content
POST
/
v1
/
regions
/
{region}
/
projects
/
{project}
/
compute
/
instances
Create compute instance
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '/v1/regions/us-texas-1/zones/us1-a/instance-types/g1-xlarge',
    id: 'instance-d4e5f6',
    displayName: '<string>',
    description: '<string>',
    labels: {},
    instanceMetadata: [{key: '<string>', value: '<string>'}],
    hostname: '<string>',
    disks: [
      {
        sizeGb: 123,
        interface: 'SCSI',
        source: '/v1/regions/us-texas-1/compute/images/ubuntu-24.04-20260202-3',
        boot: true,
        type: 'PERSISTENT',
        mode: 'READ_ONLY'
      }
    ],
    nics: [
      {
        network: '/v1/regions/us-texas-1/projects/project-x9y8z7/compute/networks/network-g7h8i9',
        subnet: '<string>',
        ipv4Address: '<string>',
        ipv6Address: '<string>',
        vlan: 123
      }
    ],
    gpus: [{type: '<string>', count: 123}]
  })
};

fetch('https://api.k0rdent.ai/v1/regions/{region}/projects/{project}/compute/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "selfLink": "/v1/regions/us-texas-1/projects/project-x9y8z7/compute/instances/instance-d4e5f6",
  "uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "instance-d4e5f6",
  "displayName": "<string>",
  "description": "<string>",
  "labels": {},
  "type": "/v1/regions/us-texas-1/zones/us1-a/instance-types/g1-xlarge",
  "instanceMetadata": [
    {
      "key": "ssh-keys",
      "value": "admin:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJeaD1heScpzmiypsUSb0T3lkmg2d/onGkPviaZ2Rtgc admin@hostname\nguest:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBYgtXDI3X7eELjQ+D+qbJGqgfa+OqvY7jo/EuLv1ECd guest@hostname\n"
    }
  ],
  "hostname": "<string>",
  "lifecycle": {
    "status": "PROVISIONING",
    "statusMessage": "<string>"
  },
  "disks": [
    {
      "sizeGb": 123,
      "interface": "SCSI",
      "source": "/v1/regions/us-texas-1/compute/images/ubuntu-24.04-20260202-3",
      "boot": true,
      "type": "PERSISTENT",
      "mode": "READ_ONLY"
    }
  ],
  "nics": [
    {
      "network": "/v1/regions/us-texas-1/projects/project-x9y8z7/compute/networks/network-g7h8i9",
      "subnet": "<string>",
      "ipv4Address": "<string>",
      "ipv6Address": "<string>",
      "vlan": 123
    }
  ],
  "gpus": [
    {
      "type": "<string>",
      "count": 123
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization
string
header
required

Bearer token authentication using OAuth2/OIDC tokens

Path Parameters

region
string
required

Region identifier

project
string
required

Project identifier

Body

application/json

Request to create a compute instance.

type
string<uri>
required

URI of the instance type resource to use for this instance. Immutable after creation.

Example:

"/v1/regions/us-texas-1/zones/us1-a/instance-types/g1-xlarge"

id
string

Name of the resource. Must be 1-63 characters long and match the pattern a-z? — the first character must be a lowercase letter, and all following characters must be lowercase letters, digits, or hyphens, with the last character being a letter or digit. If not specified, the server will generate a name. Immutable after creation.

Required string length: 1 - 63
Pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$
Example:

"instance-d4e5f6"

displayName
string

Optional human-friendly display name for the instance.

description
string

An optional description of this resource.

labels
object

Labels to apply to this resource.

instanceMetadata
object[]

Instance metadata assigned to this instance, exposed via metadata service.

hostname
string

Specifies the hostname of the instance. The specified hostname must be RFC1035 compliant. If not specified, the default hostname will be generated. Immutable after creation.

disks
object[]
nics
object[]
gpus
object[]

GPU accelerators to attach to this instance.

Response

Instance creation initiated

Compute instance (VM or baremetal).

Server-defined URL for this resource.

Example:

"/v1/regions/us-texas-1/projects/project-x9y8z7/compute/instances/instance-d4e5f6"

uid
string<uuid>

Server-generated UUID.

id
string

Name of the resource. Provided by the client when the resource is created, or generated by the server if not specified. Must be 1-63 characters long and match the pattern a-z? — the first character must be a lowercase letter, and all following characters must be lowercase letters, digits, or hyphens, with the last character being a letter or digit. Cannot be changed after the resource is created.

Required string length: 1 - 63
Pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$
Example:

"instance-d4e5f6"

displayName
string

Optional human-friendly display name for the instance.

description
string

An optional description of this resource.

labels
object

Labels to apply to this resource.

type
string<uri>

URI of the instance type resource to use for this instance. Immutable after creation.

(TODO): support for custom types similar to GCP or user-defined types via project-based machineType like /v1/regions/us-texas-1/projects/project-x9y8z7/compute/instance-types/user-type-1.

Example:

"/v1/regions/us-texas-1/zones/us1-a/instance-types/g1-xlarge"

instanceMetadata
object[]

Instance metadata assigned to this instance, exposed via metadata service. Including, but not limited to, SSH keys and cloud-init metadata.

hostname
string

Specifies the hostname of the instance. The specified hostname must be RFC1035 compliant. If not specified, the default hostname will be generated.

(TBD): hostname template similar to [INSTANCE_NAME].[ZONE].c.[PROJECT_ID].internal; may change based on CSP configuration.

lifecycle
object
disks
object[]
nics
object[]
gpus
object[]

(TBD): this is a specialized version of GCP instance.guestAccelerators. Using list & count at the same time leaves this API open for extension, e.g.:

  • if physical hosts have different GPUs attached (is it likely?)
  • if we need advanced topology support (NUMA-awareness)
createdAt
string<date-time>
updatedAt
string<date-time>