> ## Documentation Index > Fetch the complete documentation index at: https://team.k0labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Create compute instance > **Visibility:** `internal` · `public` ( OpenAPI Custom Extension: x-visibility ) "Virtual machine lifecycle", "Baremetal server lifecycle" Create a new VM or baremetal instance. ## OpenAPI ````yaml api-docs/k0rdent-api.json post /v1/regions/{region}/projects/{project}/compute/instances openapi: 3.1.0 info: title: K0rdent AI API version: 0.2.0-draft description: > OpenAPI specification for the K0rdent AI GPU-as-a-Service platform. **Custom Extensions:** - `x-visibility`: Endpoint visibility — `internal` (Atlas only), `public` (Arc only), `[internal, public]` (common) - `x-status`: Implementation status — `mvp`, `tbd`, `blocked`, `stretch` - `x-source`: Source document reference or `TBD` for fields pending confirmation **Error Model:** Standard `{ error: { code, message, details[] } }` envelope. **Pagination:** All list endpoints support two modes: - **Cursor** (`pageToken` + `pageSize`): Use for frequently updated resources. Prevents skipped or duplicated items across pages. `nextPageToken` is returned; `total` is not. - **Offset** (`offset` + `pageSize`): Use for stable resources. Returns `total` for page-count UIs. `nextPageToken` is not returned. `pageToken` and `offset` are mutually exclusive. Default `pageSize` is 50, maximum is 500. servers: - url: https://api.k0rdent.ai description: K0rdent AI API Gateway security: - bearerAuth: [] tags: - name: clusters description: Kubernetes cluster management - name: kubeconfigs description: Kubeconfig issuance and management - name: instances description: VM and baremetal instance lifecycle - name: networks description: Network configuration and topology - name: addresses description: IP address management - name: servers description: Bare metal server lifecycle management - name: organizations description: Organization (tenant) management - name: projects description: Project resource grouping - name: authentication description: Authentication and session management - name: users description: User management - name: groups description: User group management - name: roles description: RBAC role definitions - name: policies description: IAM policy bindings - name: providers description: Identity provider configuration - name: token description: > Generate access token via multiple grant types (authorization_code, api_key, client_credentials). - name: check description: > Evaluate permissions for a principal against actions and resources. Supports single and bulk checks (up to 100). - name: introspect description: > Token introspection per RFC 7662. Validate token activity and retrieve full decoded claims. - name: revoke description: > Token revocation per RFC 7009. Explicitly invalidate access tokens before natural expiration. - name: sessions description: > Manage user browser sessions. Supports listing active sessions, creating a new session (login), and ending the current session (logout). - name: apikeys description: > Manage API keys for programmatic access. API keys are bound to a user and inherit a dynamic subset of the user's privileges, evaluated at token-mint time. Keys are scoped to a level in the resource hierarchy (organization, or project). - name: serviceaccounts description: | Manage service accounts for machine-to-machine and infrastructure access. Service accounts are independent principals with their own identity, role bindings, and credentials. They survive user off-boarding and are managed exclusively by tenant administrators. paths: /v1/regions/{region}/projects/{project}/compute/instances: parameters: - $ref: '#/components/parameters/RegionPathParam' - $ref: '#/components/parameters/ProjectPathParam' post: tags: - instances summary: Create compute instance description: > **Visibility:** `internal` · `public` ( OpenAPI Custom Extension: x-visibility ) "Virtual machine lifecycle", "Baremetal server lifecycle" Create a new VM or baremetal instance. operationId: createInstance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceCreateRequest' responses: '201': description: Instance creation initiated content: application/json: schema: $ref: '#/components/schemas/Instance' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: RegionPathParam: name: region in: path required: true schema: type: string description: Region identifier ProjectPathParam: name: project in: path required: true schema: type: string description: Project identifier schemas: InstanceCreateRequest: type: object description: Request to create a compute instance. required: - type properties: id: type: string description: >- Name of the resource. Must be 1-63 characters long and match the pattern [a-z]([\-a-z0-9]*[a-z0-9])? — 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. pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ minLength: 1 maxLength: 63 example: instance-d4e5f6 displayName: type: string description: Optional human-friendly display name for the instance. description: type: string description: An optional description of this resource. labels: type: object description: Labels to apply to this resource. additionalProperties: type: string type: type: string format: uri example: /v1/regions/us-texas-1/zones/us1-a/instance-types/g1-xlarge description: |- URI of the instance type resource to use for this instance. Immutable after creation. instanceMetadata: type: array description: >- Instance metadata assigned to this instance, exposed via metadata service. items: type: object properties: key: type: string description: |- Key for the metadata entry. Keys must conform to the following regexp: [a-zA-Z0-9-_]+, and be less than 128 bytes in length. value: type: string description: |- The value for this metadata entry. Values are free-form strings that are interpreted by the image running in the instance. hostname: type: string description: >- 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: type: array items: type: object properties: sizeGb: type: integer description: Disk size (GB). interface: type: string enum: - SCSI - NVME description: Sets the disk attachment interface to SCSI or NVME. source: type: string format: uri description: |- URI of a predefined instance image or an existing compatible Volume or Snapshot. Immutable after creation. example: /v1/regions/us-texas-1/compute/images/ubuntu-24.04-20260202-3 boot: type: boolean description: |- Specifies that this disk is a boot disk. The virtual machine uses the first partition as its root filesystem. type: type: string enum: - PERSISTENT - TEMPORARY description: The disk type. mode: type: string enum: - READ_ONLY - READ_WRITE description: The disk attachment mode. Defaults to READ_WRITE. nics: type: array items: type: object properties: network: type: string format: uri description: |- The URI of the network resource for this NIC. If neither a network nor a subnetwork is specified when creating an instance, the default network is used. If the project doesn't have a default network, you must specify a network or subnet. If only a subnetwork is specified, the network is inferred automatically. example: >- /v1/regions/us-texas-1/projects/project-x9y8z7/compute/networks/network-g7h8i9 subnet: type: string format: uri description: The URI of the subnetwork resource for this NIC. ipv4Address: type: string description: |- Primary internal IPv4 address to assign to the instance on this network interface. If not specified, the system automatically assigns an available internal IP. ipv6Address: type: string description: |- Primary internal IPv6 address to assign to the instance on this network interface. If not specified, the system automatically assigns an available internal IP. vlan: type: integer description: Optional VLAN tag for this NIC. gpus: type: array description: GPU accelerators to attach to this instance. items: type: object properties: type: type: string format: uri description: The URI of the GPU type for this instance. count: type: integer description: Number of attached GPUs. Instance: type: object description: | Compute instance (VM or baremetal). properties: selfLink: type: string format: uri description: Server-defined URL for this resource. readOnly: true example: >- /v1/regions/us-texas-1/projects/project-x9y8z7/compute/instances/instance-d4e5f6 uid: type: string description: Server-generated UUID. format: uuid readOnly: true id: type: string description: >- 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]([\-a-z0-9]*[a-z0-9])? — 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. pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ minLength: 1 maxLength: 63 example: instance-d4e5f6 displayName: type: string description: Optional human-friendly display name for the instance. description: type: string description: An optional description of this resource. labels: type: object description: Labels to apply to this resource. additionalProperties: type: string type: type: string format: uri example: /v1/regions/us-texas-1/zones/us1-a/instance-types/g1-xlarge description: >- URI of the instance type resource to use for this instance. Immutable after creation. (TODO): support for custom types similar to [GCP](https://docs.cloud.google.com/compute/docs/instances/creating-instance-with-custom-machine-type) or user-defined types via project-based `machineType` like `/v1/regions/us-texas-1/projects/project-x9y8z7/compute/instance-types/user-type-1`. instanceMetadata: type: array description: >- Instance metadata assigned to this instance, exposed via metadata service. Including, but not limited to, SSH keys and cloud-init metadata. items: type: object properties: key: type: string description: |- Key for the metadata entry. Keys must conform to the following regexp: [a-zA-Z0-9-_]+, and be less than 128 bytes in length. example: ssh-keys value: type: string description: |- The value for this metadata entry. Values are free-form strings that are interpreted by the image running in the instance. example: > admin:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJeaD1heScpzmiypsUSb0T3lkmg2d/onGkPviaZ2Rtgc admin@hostname guest:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBYgtXDI3X7eELjQ+D+qbJGqgfa+OqvY7jo/EuLv1ECd guest@hostname hostname: type: string description: >- 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: type: object properties: status: type: string enum: - PROVISIONING - STAGING - RUNNING - STOPPING - SUSPENDING - SUSPENDED - REPAIRING - TERMINATED readOnly: true description: The lifecycle status of the Instance. statusMessage: type: string readOnly: true description: Optional, human-readable explanation of `status`. disks: type: array items: type: object properties: sizeGb: type: integer description: Disk size (GB). interface: type: string enum: - SCSI - NVME description: Sets the disk attachment interface to SCSI or NVME. source: type: string format: uri description: >- URI of a predefined instance image or an existing compatible Volume or Snapshot. Immutable after creation. (TODO): clarify scope requirements, e.g. allow "region1 + zone1a", but prohibit "region2 + zone1a" or "zone1a + zone1b" example: /v1/regions/us-texas-1/compute/images/ubuntu-24.04-20260202-3 boot: type: boolean description: |- Specifies that this disk is a boot disk. The virtual machine uses the first partition as its root filesystem. type: type: string enum: - PERSISTENT - TEMPORARY description: |- (TODO) Explain - same as: - GCP: SCRATCH/PERSISTENT - AWS: EBS vs Instance Store - Azure: Managed Disk vs Local/Temp mode: type: string enum: - READ_ONLY - READ_WRITE description: The disk attachment mode. Defaults to READ_WRITE. nics: type: array items: type: object properties: network: type: string format: uri description: |- The URI of the network resource for this NIC. If neither a network nor a subnetwork is specified when creating an instance, the default network is used. If the project doesn't have a default network, you must specify a network or subnet. If only a subnetwork is specified, the network is inferred automatically. (TBD): global vs regional/zonal networks example: >- /v1/regions/us-texas-1/projects/project-x9y8z7/compute/networks/network-g7h8i9 subnet: type: string format: uri description: The URI of the subnetwork resource for this NIC. ipv4Address: type: string description: |- Primary internal IPv4 address to assign to the instance on this network interface. If not specified, the system automatically assigns an available internal IP. ipv6Address: type: string description: |- Primary internal IPv6 address to assign to the instance on this network interface. If not specified, the system automatically assigns an available internal IP. vlan: type: integer description: Optional VLAN tag for this NIC. gpus: type: array description: >- (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) items: type: object properties: type: type: string format: uri description: |- The URI of the GPU type for this instance. (TBD): reference to `gpu-types` endpoint count: type: integer description: Number of attached GPUs createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object description: Standard error response properties: error: type: object properties: code: type: integer description: HTTP status code message: type: string description: Error message details: type: array items: type: object description: Additional error details responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token authentication using OAuth2/OIDC tokens ````