create

{              
  "metadata": {               
    "labels": {                // [map]
                               // Labels associated with the resource.
      string: string                  
    },
    "name": string,            // Human readable name for the resource.
    "parent_id": string,       // [required]
                               // Identifier of the parent resource to which the resource belongs.
    "resource_version": int64  // Version of the resource for safe concurrent modifications and consistent reads.
                               // Positive and monotonically increases on each resource spec change (but *not* on each change of the
                               // resource's container(s) or status).
                               // Service allows zero value or current.
  },
  "spec": {                         
    "boot_disk": {         // Specified boot disk attached to the instance.
      "attach_mode": enum( // [required]
        "UNSPECIFIED",    
        "READ_ONLY",      
        "READ_WRITE"      
      ),
      "device_id": string, // Specifies the user-defined identifier, allowing to use '/dev/disk/by-id/virtio-{device_id}' as a device path in mount command.
      "existing_disk": { // Cannot be set together with: managed_disk
                         // Attach an existing disk.
                         // 
                         // Lifecycle:
                         // - The disk is preserved when the instance is deleted (it will be detached).
                         // 
                         // Switching to a managed disk:
                         // - To delete the disk together with the instance, switch to ManagedDisk in the instance spec.
                         // - For the switch, `ManagedDisk.name` MUST match the current disk `name`
                         //   (see DiskService.Get for the disk referenced by `ExistingDisk.id`).
                         // - When converting an ExistingDisk to a ManagedDisk, you must provide `ManagedDisk.name` and `ManagedDisk.spec`
                         //   exactly as they are currently defined in the disk resource.
                         //   Obtain the current values via `DiskService.Get` and copy them verbatim.
                         //   If `ManagedDisk.spec` differs from the current disk spec, the instance update will fail.
        "id": string     // [required]
      },
      "managed_disk": { // Cannot be set together with: existing_disk
                        // Attach a managed disk.
                        // 
                        // Lifecycle:
                        // - The disk is deleted when the instance is deleted.
                        // 
                        // Semantics:
                        // - Specifying a ManagedDisk expresses an intent to have that managed disk attached.
                        // - If this intent cannot be satisfied, the entire operation fails.
                        // - You can check the intent status in `instance.status.disk_attachments`.
                        // 
                        // Updates and matching:
                        // - Managed disks can be updated only via instance spec updates. Updates via DiskService are not allowed.
                        // - During updates, disks are matched by `name`.
                        // 
                        // Renaming and data loss:
                        // - Changing the disk `name` triggers disk replacement (create a new disk and delete the old one),
                        //   which causes data loss.
                        // - To rename a managed disk safely:
                        //   1) switch it to ExistingDisk in the instance spec, and
                        //   2) update/rename it via DiskService.
                        // 
                        // Conflicts:
                        // - Instance create/update fails if there is already a disk with the same `name`.
                        //   as requested by any ManagedDisk.
                        // 
                        // Finding the disk ID:
                        // - The disk ID is available in `instance.status.disk_attachments` after it is created.
                        //   Use `DiskAttachmentStatus.name` to find the desired disk which matches `name`.
                        // 
                        // Switching to an existing (non-managed) disk:
                        // - To preserve the disk after instance deletion, switch it to ExistingDisk in the instance spec,
                        //   use the disk ID from `instance.status.disk_attachments`.
                        // 
                        // Deletion protection:
                        // - Switching ExistingDisk to ManagedDisk fails if `Disk.spec.deletion_protection` is enabled.
                        // - Deleting an instance that has a ManagedDisk fails if `Disk.spec.deletion_protection` is enabled.
        "labels": {        // [map]
                           // Labels associated with disk resource.
          string: string          
        },
        "name": string, // [required]
                        // Name of a dependent disk.
                        // Use it to convert an ExistingDisk to a dependent disk.
                        // Changing the name will replace the disk and cause data loss.
        "spec": {                    // [required]
                                     // Specification of a dependent disk to be created.
          "block_size_bytes": int64, // [immutable]
                                     // Block size in bytes.
                                     // The block size must be a power of two between 4096 bytes (4 KiB) and 131072 bytes (128 KiB).
                                     // The default value is 4096 bytes (4 KiB).
          "disk_encryption": { // [immutable]
                               // Defines how data on the disk is encrypted. By default, no encryption is applied.
            "type": enum(                   
              "DISK_ENCRYPTION_UNSPECIFIED", // No encryption is applied unless explicitly specified.
              "DISK_ENCRYPTION_MANAGED"      // Enables encryption using the platform's default root key from KMS.
                                             // Available for disks with NETWORK_SSD_NON_REPLICATED and NETWORK_SSD_IO_M3 types only.
            )
          },
          "forbid_deletion": bool,   // Prevents deletion whilst set.
          "size_bytes": int64,       // Cannot be set together with: size_kibibytes, size_mebibytes, size_gibibytes
          "size_gibibytes": int64,   // Cannot be set together with: size_bytes, size_kibibytes, size_mebibytes
          "size_kibibytes": int64,   // Cannot be set together with: size_bytes, size_mebibytes, size_gibibytes
          "size_mebibytes": int64,   // Cannot be set together with: size_bytes, size_kibibytes, size_gibibytes
          "source_image_family": {  // [immutable]
                                    // Cannot be set together with: source_image_id
            "image_family": string, // [required]
            "parent_id": string    
          },
          "source_image_id": string, // [immutable]
                                     // Cannot be set together with: source_image_family
          "type": enum(                   // [required] [immutable]
                                          // The type of disk defines the performance and reliability characteristics of the block device.
                                          // For details, see https://docs.nebius.com/compute/storage/types#disks-types.
            "UNSPECIFIED",               
            "NETWORK_SSD",               
            "NETWORK_HDD",               
            "NETWORK_SSD_NON_REPLICATED",
            "NETWORK_SSD_IO_M3"          
          )
        }
      }
    },
    "cloud_init_user_data": string,  // [sensitive]
                                     // Data in cloud-init format for customizing instance initialization.
                                     // For details, see https://docs.nebius.com/compute/virtual-machines/manage#user-data.
    "filesystems": [{          // List of Shared Filesystems attached to the instance.
      "attach_mode": enum( // [required]
        "UNSPECIFIED",    
        "READ_ONLY",      
        "READ_WRITE"      
      ),
      "existing_filesystem": {
        "id": string           // [required]
      },
      "mount_tag": string      // [required]
                               // Specifies the user-defined identifier, allowing to use it as a device in mount command.
    }],
    "gpu_cluster": { // [immutable]
                     // If you want to interconnect several instances in a GPU cluster via NVIDIA InfiniBand,
                     // set the ID of an existing GPU cluster.
                     // You can only add the VM to the cluster when creating the VM.
                     // For details, see https://docs.nebius.com/compute/clusters/gpu.
      "id": string   // If you want to interconnect several instances in a GPU cluster via NVIDIA InfiniBand,
                     // set the ID of an existing GPU cluster.
                     // You can only add the VM to the cluster when creating the VM.
                     // For details, see https://docs.nebius.com/compute/clusters/gpu.
    },
    "hostname": string,              // Instance's hostname. Used to generate default DNS record in format `<hostname>.<network_id>.compute.internal.`
                                     // or `<instance_id>.<network_id>.compute.internal.` if hostname is not specified.
    "local_disks": {         // Local disks are meaningfully different from regular (remote) disks:
                             // they are provided by the underlying host and are tied to a particular VM run.
                             // Local disk data is not preserved across Stop-Start initiated via Compute API.
                             // Local disks are not provided by default. To get them, explicitly request them via this field.
                             // Availability depends on the selected platform, preset and region.
                             // Changing this field will result in disks change and content loss, but only after stop and start the instance.
      "passthrough_group": { // Requests passthrough local disks from the host.
                             // Topology of the provided disks is preserved during stop and start
                             // for every instance of a specific platform and preset in the region.
        "requested": bool    // Passthrough local disks from the underlying host.
                             // 
                             // Devices are expected to appear in the guest as NVMe devices (nvme0, nvme1, ...),
                             // but the exact number depends on the preset.
                             // Enabled only when this field is explicitly set.
      }
    },
    "network_interfaces": [{ // [required]
                             // List of network interfaces attached to the instance.
      "aliases": [{              // Assign ranges of IP addresses as aliases.
        "allocation_id": string  // [required]
                                 // ID of allocation.
      }],
      "ip_address": {            // [required] [immutable] [meaningful_empty_value]
                                 // Private IPv4 address associated with the interface.
        "allocation_id": string  // Allocation identifier if it was created before.
      },
      "name": string,        // [required] [immutable]
                             // Interface name
                             // Value of this field configures the name of the network interface inside VM's OS.
                             // Longer values will persist in the specification but will be truncated to 15 symbols before being passed to VM configuration.
      "public_ip_address": {     // [meaningful_empty_value]
                                 // Public IPv4 address associated with the interface.
        "allocation_id": string, // Allocation identifier if it was created before.
        "static": bool           // If false - Allocation will be created/deleted during NetworkInterface.Allocate/NetworkInterface.Deallocate
                                 // If true  - Allocation will be created/deleted during NetworkInterface.Create/NetworkInterface.Delete
                                 // False by default.
      },
      "security_groups": [{ // Security groups associated with the network interface.
                            // If an empty list is provided, the default security group for the network will be used.
                            // Effective security groups can be seen in the status.
        "id": string        // Security group identifier.
      }],
      "subnet_id": string    // [required] [immutable]
                             // Subnet ID.
    }],
    "nvl_instance_group_id": string, // NVLink Instance Group ID associated with the VM.
    "preemptible": {         // [immutable]
                             // Include these parameters to create a Preemptible VM and omit them to create a Regular VM
                             // For details, see https://docs.nebius.com/compute/virtual-machines/preemptible.
      "on_preemption": enum( // [required] [immutable]
                             // Specifies what happens when the VM is preempted. The only supported value is STOP:
                             // Compute stops the VM without deleting or restarting it.
        "UNSPECIFIED",      
        "STOP"              
      ),
      "priority": int32      // [deprecated: supported until 2026-05-11] [immutable]
                             // It is deprecated and doesn't affect preemption behavior anymore.
    },
    "recovery_policy": enum( // [immutable]
                             // Recovery policy defines how the instance will be treated in case of a failure.
                             // Common source of failure is a host failure, but it can be any other failure.
                             // Instance undergoing a guest shutdown (poweroff, etc.) will be subject to recovery policy, meaning that it could
                             // be restarted and billed accordingly. Stop instance via API or UI to stop it to avoid recovering.
                             // - If set to RECOVER, instance will be restarted, if possible. It could be restarted on the same host or on another host.
                             // - If set to FAIL, instance will be stopped and not restarted.
      "RECOVER",            
      "FAIL"                
    ),
    "reservation_policy": {       
      "policy": enum(
        "AUTO",       // 1) Will try to launch instance in any reservation_ids if provided.
                      // 2) Will try to launch instance in any of the available capacity block.
                      // 3) Will try to launch instance in PAYG if 1 & 2 are not satisfied.
        "FORBID",     // The instance is launched only using on-demand (PAYG) capacity.
                      // No attempt is made to find or use a Capacity Block.
                      // It's an error to provide reservation_ids with policy = FORBID.
        "STRICT"      // 1) Will try to launch the instance in Capacity Blocks from reservation_ids if provided.
                      // 2) If reservation_ids are not provided will try to launch instance in suitable & available Capacity Block.
                      // 3) Fail otherwise.
      ),
      "reservation_ids": [string]  // Capacity block groups, order matters.
    },
    "resources": {        // [required]
                          // Specification of compute resources allocated to the instance.
                          // For details, see https://docs.nebius.com/compute/virtual-machines/types.
      "platform": string, // [required] [immutable]
      "preset": string   
    },
    "secondary_disks": [{  // List of additional data disks attached to the instance beyond the boot disk.
      "attach_mode": enum( // [required]
        "UNSPECIFIED",    
        "READ_ONLY",      
        "READ_WRITE"      
      ),
      "device_id": string, // Specifies the user-defined identifier, allowing to use '/dev/disk/by-id/virtio-{device_id}' as a device path in mount command.
      "existing_disk": { // Cannot be set together with: managed_disk
                         // Attach an existing disk.
                         // 
                         // Lifecycle:
                         // - The disk is preserved when the instance is deleted (it will be detached).
                         // 
                         // Switching to a managed disk:
                         // - To delete the disk together with the instance, switch to ManagedDisk in the instance spec.
                         // - For the switch, `ManagedDisk.name` MUST match the current disk `name`
                         //   (see DiskService.Get for the disk referenced by `ExistingDisk.id`).
                         // - When converting an ExistingDisk to a ManagedDisk, you must provide `ManagedDisk.name` and `ManagedDisk.spec`
                         //   exactly as they are currently defined in the disk resource.
                         //   Obtain the current values via `DiskService.Get` and copy them verbatim.
                         //   If `ManagedDisk.spec` differs from the current disk spec, the instance update will fail.
        "id": string     // [required]
      },
      "managed_disk": { // Cannot be set together with: existing_disk
                        // Attach a managed disk.
                        // 
                        // Lifecycle:
                        // - The disk is deleted when the instance is deleted.
                        // 
                        // Semantics:
                        // - Specifying a ManagedDisk expresses an intent to have that managed disk attached.
                        // - If this intent cannot be satisfied, the entire operation fails.
                        // - You can check the intent status in `instance.status.disk_attachments`.
                        // 
                        // Updates and matching:
                        // - Managed disks can be updated only via instance spec updates. Updates via DiskService are not allowed.
                        // - During updates, disks are matched by `name`.
                        // 
                        // Renaming and data loss:
                        // - Changing the disk `name` triggers disk replacement (create a new disk and delete the old one),
                        //   which causes data loss.
                        // - To rename a managed disk safely:
                        //   1) switch it to ExistingDisk in the instance spec, and
                        //   2) update/rename it via DiskService.
                        // 
                        // Conflicts:
                        // - Instance create/update fails if there is already a disk with the same `name`.
                        //   as requested by any ManagedDisk.
                        // 
                        // Finding the disk ID:
                        // - The disk ID is available in `instance.status.disk_attachments` after it is created.
                        //   Use `DiskAttachmentStatus.name` to find the desired disk which matches `name`.
                        // 
                        // Switching to an existing (non-managed) disk:
                        // - To preserve the disk after instance deletion, switch it to ExistingDisk in the instance spec,
                        //   use the disk ID from `instance.status.disk_attachments`.
                        // 
                        // Deletion protection:
                        // - Switching ExistingDisk to ManagedDisk fails if `Disk.spec.deletion_protection` is enabled.
                        // - Deleting an instance that has a ManagedDisk fails if `Disk.spec.deletion_protection` is enabled.
        "labels": {        // [map]
                           // Labels associated with disk resource.
          string: string          
        },
        "name": string, // [required]
                        // Name of a dependent disk.
                        // Use it to convert an ExistingDisk to a dependent disk.
                        // Changing the name will replace the disk and cause data loss.
        "spec": {                    // [required]
                                     // Specification of a dependent disk to be created.
          "block_size_bytes": int64, // [immutable]
                                     // Block size in bytes.
                                     // The block size must be a power of two between 4096 bytes (4 KiB) and 131072 bytes (128 KiB).
                                     // The default value is 4096 bytes (4 KiB).
          "disk_encryption": { // [immutable]
                               // Defines how data on the disk is encrypted. By default, no encryption is applied.
            "type": enum(                   
              "DISK_ENCRYPTION_UNSPECIFIED", // No encryption is applied unless explicitly specified.
              "DISK_ENCRYPTION_MANAGED"      // Enables encryption using the platform's default root key from KMS.
                                             // Available for disks with NETWORK_SSD_NON_REPLICATED and NETWORK_SSD_IO_M3 types only.
            )
          },
          "forbid_deletion": bool,   // Prevents deletion whilst set.
          "size_bytes": int64,       // Cannot be set together with: size_kibibytes, size_mebibytes, size_gibibytes
          "size_gibibytes": int64,   // Cannot be set together with: size_bytes, size_kibibytes, size_mebibytes
          "size_kibibytes": int64,   // Cannot be set together with: size_bytes, size_mebibytes, size_gibibytes
          "size_mebibytes": int64,   // Cannot be set together with: size_bytes, size_kibibytes, size_gibibytes
          "source_image_family": {  // [immutable]
                                    // Cannot be set together with: source_image_id
            "image_family": string, // [required]
            "parent_id": string    
          },
          "source_image_id": string, // [immutable]
                                     // Cannot be set together with: source_image_family
          "type": enum(                   // [required] [immutable]
                                          // The type of disk defines the performance and reliability characteristics of the block device.
                                          // For details, see https://docs.nebius.com/compute/storage/types#disks-types.
            "UNSPECIFIED",               
            "NETWORK_SSD",               
            "NETWORK_HDD",               
            "NETWORK_SSD_NON_REPLICATED",
            "NETWORK_SSD_IO_M3"          
          )
        }
      }
    }],
    "service_account_id": string,    // [immutable]
                                     // Unique identifier of the service account associated with this instance.
                                     // For details, see https://docs.nebius.dev/en/iam/about-iam/concepts/service-accounts.
    "stopped": bool                  // Indicates whether the instance should be stopped.
  }
}