> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance

> Instance is the Schema for the instances API.

<Note>
  API resource reference for **Instance**, part of the [Compute service](/api/compute/overview). To create or change one, see [Changing resources](/datumctl/resources/changing); to inspect, see [Reading resources](/datumctl/resources/reading).
</Note>

<Warning>
  This resource is part of the `v1alpha` API and is subject to change. Fields and behavior may change in future releases.
</Warning>

## Identity

|         |                         |
| ------- | ----------------------- |
| Group   | `compute.datumapis.com` |
| Version | `v1alpha`               |
| Kind    | `Instance`              |
| Scope   | Project                 |

## Overview

An `Instance` represents a single compute workload running in a Datum Cloud Project. Each instance runs one of two runtime types: a **sandbox** (a managed, isolated environment for running one or more containers) or a **virtual machine** (a classical VM booting a full OS from a user-provided image). Every instance attaches to one or more networks through its network interfaces and may mount volumes backed by disks, config maps, or secrets.

Use an `Instance` when you need to run application code — as containers or as a full VM — with a defined instance type, network connectivity, and optional persistent storage inside a Project.

## Spec fields

| Field                                           | Type               | Required         | Description                                                                                              |
| ----------------------------------------------- | ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------- |
| `spec.runtime`                                  | Object             | Yes              | The runtime type of the instance, such as a container sandbox or a VM.                                   |
| `spec.runtime.resources`                        | Object             | Yes              | Resources each instance must be allocated across its containers or VM.                                   |
| `spec.runtime.resources.instanceType`           | string             | Yes              | Full or partial URL of the instance type resource to use (for example, `datumcloud/d1-standard-2`).      |
| `spec.runtime.resources.requests`               | map\[string]Object | No               | Adjustments to the resources defined by the instance type (for customizable instance families).          |
| `spec.runtime.sandbox`                          | Object             | No               | A managed isolated environment capable of running containers.                                            |
| `spec.runtime.sandbox.containers`               | \[]Object          | Yes (if sandbox) | The containers to run within the sandbox; each requires a `name` and `image`.                            |
| `spec.runtime.sandbox.imagePullSecrets`         | \[]Object          | No               | Secrets in the same Project used for pulling images.                                                     |
| `spec.runtime.virtualMachine`                   | Object             | No               | A classical VM environment booting a full OS from a user-provided image.                                 |
| `spec.runtime.virtualMachine.volumeAttachments` | \[]Object          | Yes (if VM)      | Volumes to attach to the VM.                                                                             |
| `spec.runtime.virtualMachine.ports`             | \[]Object          | No               | Named ports for the virtual machine.                                                                     |
| `spec.networkInterfaces`                        | \[]Object          | Yes              | Network interface configuration for the instance.                                                        |
| `spec.networkInterfaces[].network`              | Object             | Yes              | The network to attach the interface to; `network.name` is required.                                      |
| `spec.networkInterfaces[].networkPolicy`        | Object             | No               | An interface-specific, platform-managed network policy targeting this interface.                         |
| `spec.volumes`                                  | \[]Object          | No               | Volumes available to attach to the instance's containers or VM.                                          |
| `spec.volumes[].name`                           | string             | Yes (per volume) | Name used to reference the volume in container/VM volume attachments.                                    |
| `spec.volumes[].disk`                           | Object             | No               | A persistent disk backed volume.                                                                         |
| `spec.volumes[].configMap`                      | Object             | No               | A config map that populates this volume.                                                                 |
| `spec.volumes[].secret`                         | Object             | No               | A secret that populates this volume.                                                                     |
| `spec.location`                                 | Object             | No               | The location the instance has been scheduled to (`name` and `namespace`).                                |
| `spec.controller`                               | Object             | No               | Settings driven by the controller managing the instance, including `templateHash` and `schedulingGates`. |

## Status fields (read-only)

| Field                      | Type      | Description                                                                                  |
| -------------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `status.conditions`        | \[]Object | Observations of the instance's current state; known types are `Available` and `Progressing`. |
| `status.controller`        | Object    | Controller status, including the `observedTemplateHash` last applied to this instance.       |
| `status.networkInterfaces` | \[]Object | Network interface information, including address assignments.                                |

## Usage

```yaml theme={null}
apiVersion: compute.datumapis.com/v1alpha
kind: Instance
metadata:
  name: web-server
spec:
  runtime:
    resources:
      instanceType: datumcloud/d1-standard-2
    sandbox:
      containers:
        - name: web
          image: nginx:1.27
  networkInterfaces:
    - network:
        name: default
```

```bash theme={null}
datumctl apply -f instance.yaml --project my-project
datumctl get instances --project my-project
datumctl describe instance web-server --project my-project
```

<Tip>
  Run `datumctl explain instances --recursive` to see the full, live field tree for this resource.
</Tip>