Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
  • Blog
  • Pricing
  • Documentation
Yandex project
© 2025 Yandex.Cloud LLC
Yandex Compute Cloud
  • Yandex Container Solution
  • Access management
  • Terraform reference
    • Authentication with the API
      • Overview
        • Overview
        • Get
        • List
        • Create
        • Update
        • Delete
        • UpdateMetadata
        • GetSerialPortOutput
        • Stop
        • Start
        • Restart
        • AttachDisk
        • DetachDisk
        • AttachFilesystem
        • DetachFilesystem
        • AttachNetworkInterface
        • DetachNetworkInterface
        • AddOneToOneNat
        • RemoveOneToOneNat
        • UpdateNetworkInterface
        • ListOperations
        • Move
        • Relocate
        • SimulateMaintenanceEvent
        • ListAccessBindings
        • SetAccessBindings
        • UpdateAccessBindings
  • Monitoring metrics
  • Audit Trails events
  • Release notes

In this article:

  • HTTP request
  • Body parameters
  • ResourcesSpec
  • MetadataOptions
  • AttachedDiskSpec
  • DiskSpec
  • DiskPlacementPolicy
  • AttachedLocalDiskSpec
  • AttachedFilesystemSpec
  • NetworkInterfaceSpec
  • PrimaryAddressSpec
  • OneToOneNatSpec
  • DnsRecordSpec
  • SchedulingPolicy
  • NetworkSettings
  • PlacementPolicy
  • HostAffinityRule
  • GpuSettings
  • SerialPortSettings
  • Response
  • CreateInstanceMetadata
  • Status
  • Instance
  • Resources
  • MetadataOptions
  • AttachedDisk
  • AttachedLocalDisk
  • AttachedFilesystem
  • NetworkInterface
  • PrimaryAddress
  • OneToOneNat
  • DnsRecord
  • SerialPortSettings
  • GpuSettings
  • SchedulingPolicy
  • NetworkSettings
  • PlacementPolicy
  • HostAffinityRule
  • HardwareGeneration
  • LegacyHardwareFeatures
  1. API reference
  2. REST
  3. Instance
  4. Create

Compute Cloud API, REST: Instance.Create

Written by
Yandex Cloud
Improved by
Updated at February 21, 2025
  • HTTP request
  • Body parameters
  • ResourcesSpec
  • MetadataOptions
  • AttachedDiskSpec
  • DiskSpec
  • DiskPlacementPolicy
  • AttachedLocalDiskSpec
  • AttachedFilesystemSpec
  • NetworkInterfaceSpec
  • PrimaryAddressSpec
  • OneToOneNatSpec
  • DnsRecordSpec
  • SchedulingPolicy
  • NetworkSettings
  • PlacementPolicy
  • HostAffinityRule
  • GpuSettings
  • SerialPortSettings
  • Response
  • CreateInstanceMetadata
  • Status
  • Instance
  • Resources
  • MetadataOptions
  • AttachedDisk
  • AttachedLocalDisk
  • AttachedFilesystem
  • NetworkInterface
  • PrimaryAddress
  • OneToOneNat
  • DnsRecord
  • SerialPortSettings
  • GpuSettings
  • SchedulingPolicy
  • NetworkSettings
  • PlacementPolicy
  • HostAffinityRule
  • HardwareGeneration
  • LegacyHardwareFeatures

Creates an instance in the specified folder.
Method starts an asynchronous operation that can be cancelled while it is in progress.

HTTP requestHTTP request

POST https://compute.api.cloud.yandex.net/compute/v1/instances

Body parametersBody parameters

{
  "folderId": "string",
  "name": "string",
  "description": "string",
  "labels": "object",
  "zoneId": "string",
  "platformId": "string",
  "resourcesSpec": {
    "memory": "string",
    "cores": "string",
    "coreFraction": "string",
    "gpus": "string"
  },
  "metadata": "object",
  "metadataOptions": {
    "gceHttpEndpoint": "string",
    "awsV1HttpEndpoint": "string",
    "gceHttpToken": "string",
    "awsV1HttpToken": "string"
  },
  "bootDiskSpec": {
    "mode": "string",
    "deviceName": "string",
    "autoDelete": "boolean",
    // Includes only one of the fields `diskSpec`, `diskId`
    "diskSpec": {
      "name": "string",
      "description": "string",
      "typeId": "string",
      "size": "string",
      // Includes only one of the fields `imageId`, `snapshotId`
      "imageId": "string",
      "snapshotId": "string",
      // end of the list of possible fields
      "diskPlacementPolicy": {
        "placementGroupId": "string",
        "placementGroupPartition": "string"
      },
      "blockSize": "string",
      "kmsKeyId": "string"
    },
    "diskId": "string"
    // end of the list of possible fields
  },
  "secondaryDiskSpecs": [
    {
      "mode": "string",
      "deviceName": "string",
      "autoDelete": "boolean",
      // Includes only one of the fields `diskSpec`, `diskId`
      "diskSpec": {
        "name": "string",
        "description": "string",
        "typeId": "string",
        "size": "string",
        // Includes only one of the fields `imageId`, `snapshotId`
        "imageId": "string",
        "snapshotId": "string",
        // end of the list of possible fields
        "diskPlacementPolicy": {
          "placementGroupId": "string",
          "placementGroupPartition": "string"
        },
        "blockSize": "string",
        "kmsKeyId": "string"
      },
      "diskId": "string"
      // end of the list of possible fields
    }
  ],
  "localDiskSpecs": [
    {
      "size": "string"
    }
  ],
  "filesystemSpecs": [
    {
      "mode": "string",
      "deviceName": "string",
      "filesystemId": "string"
    }
  ],
  "networkInterfaceSpecs": [
    {
      "subnetId": "string",
      "primaryV4AddressSpec": {
        "address": "string",
        "oneToOneNatSpec": {
          "ipVersion": "string",
          "address": "string",
          "dnsRecordSpecs": [
            {
              "fqdn": "string",
              "dnsZoneId": "string",
              "ttl": "string",
              "ptr": "boolean"
            }
          ]
        },
        "dnsRecordSpecs": [
          {
            "fqdn": "string",
            "dnsZoneId": "string",
            "ttl": "string",
            "ptr": "boolean"
          }
        ]
      },
      "primaryV6AddressSpec": {
        "address": "string",
        "oneToOneNatSpec": {
          "ipVersion": "string",
          "address": "string",
          "dnsRecordSpecs": [
            {
              "fqdn": "string",
              "dnsZoneId": "string",
              "ttl": "string",
              "ptr": "boolean"
            }
          ]
        },
        "dnsRecordSpecs": [
          {
            "fqdn": "string",
            "dnsZoneId": "string",
            "ttl": "string",
            "ptr": "boolean"
          }
        ]
      },
      "securityGroupIds": [
        "string"
      ],
      "index": "string"
    }
  ],
  "hostname": "string",
  "schedulingPolicy": {
    "preemptible": "boolean"
  },
  "serviceAccountId": "string",
  "networkSettings": {
    "type": "string"
  },
  "placementPolicy": {
    "placementGroupId": "string",
    "hostAffinityRules": [
      {
        "key": "string",
        "op": "string",
        "values": [
          "string"
        ]
      }
    ],
    "placementGroupPartition": "string"
  },
  "gpuSettings": {
    "gpuClusterId": "string"
  },
  "maintenancePolicy": "string",
  "maintenanceGracePeriod": "string",
  "serialPortSettings": {
    "sshAuthorization": "string"
  },
  "reservedInstancePoolId": "string"
}

Field

Description

folderId

string

Required field. ID of the folder to create an instance in.
To get the folder ID, use a yandex.cloud.resourcemanager.v1.FolderService.List request.

name

string

Name of the instance.

description

string

Description of the instance.

labels

object (map<string, string>)

Resource labels as key:value pairs.

zoneId

string

Required field. ID of the availability zone where the instance resides.
To get a list of available zones, use the yandex.cloud.compute.v1.ZoneService.List request

platformId

string

Required field. ID of the hardware platform configuration for the instance.
This field affects the available values in resourcesSpec field.

Platforms allows you to create various types of instances: with a large amount of memory,
with a large number of cores, with a burstable performance.
For more information, see Platforms.

resourcesSpec

ResourcesSpec

Required field. Computing resources of the instance, such as the amount of memory and number of cores.
To get a list of available values, see Levels of core performance.

metadata

object (map<string, string>)

The metadata key:value pairs that will be assigned to this instance. This includes custom metadata and predefined keys.
The total size of all keys and values must be less than 512 KB.

Values are free-form strings, and only have meaning as interpreted by the programs which configure the instance.
The values must be 256 KB or less.

For example, you may use the metadata in order to provide your public SSH key to the instance.
For more information, see Metadata.

metadataOptions

MetadataOptions

Options allow user to configure access to instance's metadata

bootDiskSpec

AttachedDiskSpec

Required field. Boot disk to attach to the instance.

secondaryDiskSpecs[]

AttachedDiskSpec

Array of secondary disks to attach to the instance.

localDiskSpecs[]

AttachedLocalDiskSpec

Array of local disks to attach to the instance.

filesystemSpecs[]

AttachedFilesystemSpec

Array of filesystems to attach to the instance.

The filesystems must reside in the same availability zone as the instance.

To use the instance with an attached filesystem, the latter must be mounted.
For details, see documentation.

networkInterfaceSpecs[]

NetworkInterfaceSpec

Required field. Network configuration for the instance. Specifies how the network interface is configured
to interact with other services on the internal network and on the internet.

hostname

string

Host name for the instance.
This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value.
The host name must be unique within the network and region.
If not specified, the host name will be equal to yandex.cloud.compute.v1.Instance.id of the instance
and FQDN will be <id>.auto.internal. Otherwise FQDN will be <hostname>.<region_id>.internal.

schedulingPolicy

SchedulingPolicy

Scheduling policy configuration.

serviceAccountId

string

ID of the service account to use for authentication inside the instance.
To get the service account ID, use a yandex.cloud.iam.v1.ServiceAccountService.List request.

networkSettings

NetworkSettings

Network settings.

placementPolicy

PlacementPolicy

Placement policy configuration.

gpuSettings

GpuSettings

GPU settings.

maintenancePolicy

enum (MaintenancePolicy)

Behaviour on maintenance events

  • MAINTENANCE_POLICY_UNSPECIFIED
  • RESTART: Restart instance to move it to another host during maintenance
  • MIGRATE: Use live migration to move instance to another host during maintenance

maintenanceGracePeriod

string (duration)

Time between notification via metadata service and maintenance

serialPortSettings

SerialPortSettings

Serial port settings

reservedInstancePoolId

string

ID of the reserved instance pool that the instance should belong to.
Instance will be created using resources from the reserved instance pool.
Reserved instance pool resource configuration must match the resource configuration of the instance.

ResourcesSpecResourcesSpec

Field

Description

memory

string (int64)

Required field. The amount of memory available to the instance, specified in bytes.

cores

string (int64)

Required field. The number of cores available to the instance.

coreFraction

string (int64)

Baseline level of CPU performance with the ability to burst performance above that baseline level.
This field sets baseline performance for each core.

For example, if you need only 5% of the CPU performance, you can set core_fraction=5.
For more information, see Levels of core performance.

gpus

string (int64)

The number of GPUs available to the instance.

MetadataOptionsMetadataOptions

Field

Description

gceHttpEndpoint

enum (MetadataOption)

Enabled access to GCE flavored metadata

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

awsV1HttpEndpoint

enum (MetadataOption)

Enabled access to AWS flavored metadata (IMDSv1)

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

gceHttpToken

enum (MetadataOption)

Enabled access to IAM credentials with GCE flavored metadata

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

awsV1HttpToken

enum (MetadataOption)

Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

AttachedDiskSpecAttachedDiskSpec

Field

Description

mode

enum (Mode)

The mode in which to attach this disk.

  • MODE_UNSPECIFIED
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.

deviceName

string

Specifies a unique serial number of your choice that is reflected into the /dev/disk/by-id/ tree
of a Linux operating system running within the instance.

This value can be used to reference the device for mounting, resizing, and so on, from within the instance.
If not specified, a random value will be generated.

autoDelete

boolean

Specifies whether the disk will be auto-deleted when the instance is deleted.

diskSpec

DiskSpec

Disk specification.

Includes only one of the fields diskSpec, diskId.

diskId

string

ID of the disk that should be attached.

Includes only one of the fields diskSpec, diskId.

DiskSpecDiskSpec

Field

Description

name

string

Name of the disk.

description

string

Description of the disk.

typeId

string

ID of the disk type.
To get a list of available disk types, use the yandex.cloud.compute.v1.DiskTypeService.List request.

size

string (int64)

Required field. Size of the disk, specified in bytes.

imageId

string

ID of the image to create the disk from.

Includes only one of the fields imageId, snapshotId.

snapshotId

string

ID of the snapshot to restore the disk from.

Includes only one of the fields imageId, snapshotId.

diskPlacementPolicy

DiskPlacementPolicy

Placement policy configuration.

blockSize

string (int64)

Block size of the disk, specified in bytes. The default is 4096.

kmsKeyId

string

ID of KMS key for disk encryption

DiskPlacementPolicyDiskPlacementPolicy

Field

Description

placementGroupId

string

Placement group ID.

placementGroupPartition

string (int64)

AttachedLocalDiskSpecAttachedLocalDiskSpec

Field

Description

size

string (int64)

Required field. Size of the disk, specified in bytes.

AttachedFilesystemSpecAttachedFilesystemSpec

Field

Description

mode

enum (Mode)

Mode of access to the filesystem that should be attached.

  • MODE_UNSPECIFIED
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.

deviceName

string

Name of the device representing the filesystem on the instance.

The name should be used for referencing the filesystem from within the instance
when it's being mounted, resized etc.

If not specified, a random value will be generated.

filesystemId

string

ID of the filesystem that should be attached.

NetworkInterfaceSpecNetworkInterfaceSpec

Field

Description

subnetId

string

Required field. ID of the subnet.

primaryV4AddressSpec

PrimaryAddressSpec

Primary IPv4 address that will be assigned to the instance for this network interface.

primaryV6AddressSpec

PrimaryAddressSpec

Primary IPv6 address that will be assigned to the instance for this network interface. IPv6 not available yet.

securityGroupIds[]

string

ID's of security groups attached to the interface

index

string

The index of the network interface, will be generated by the server, 0,1,2... etc if not specified.

PrimaryAddressSpecPrimaryAddressSpec

Field

Description

address

string

An IPv4 internal network address that is assigned to the instance for this network interface.
If not specified by the user, an unused internal IP is assigned by the system.

oneToOneNatSpec

OneToOneNatSpec

An external IP address configuration.
If not specified, then this instance will have no external internet access.

dnsRecordSpecs[]

DnsRecordSpec

Internal DNS configuration

OneToOneNatSpecOneToOneNatSpec

Field

Description

ipVersion

enum (IpVersion)

External IP address version.

  • IP_VERSION_UNSPECIFIED
  • IPV4: IPv4 address, for example 192.0.2.235.
  • IPV6: IPv6 address. Not available yet.

address

string

set static IP by value

dnsRecordSpecs[]

DnsRecordSpec

External DNS configuration

DnsRecordSpecDnsRecordSpec

Field

Description

fqdn

string

Required field. FQDN (required)

dnsZoneId

string

DNS zone id (optional, if not set, private zone used)

ttl

string (int64)

DNS record ttl, values in 0-86400 (optional)

ptr

boolean

When set to true, also create PTR DNS record (optional)

SchedulingPolicySchedulingPolicy

Field

Description

preemptible

boolean

True for short-lived compute instances. For more information, see Preemptible VMs.

NetworkSettingsNetworkSettings

Field

Description

type

enum (Type)

Network Type

  • TYPE_UNSPECIFIED
  • STANDARD: Standard network.
  • SOFTWARE_ACCELERATED: Software accelerated network.
  • HARDWARE_ACCELERATED: Hardware accelerated network (not available yet, reserved for future use).

PlacementPolicyPlacementPolicy

Field

Description

placementGroupId

string

Placement group ID.

hostAffinityRules[]

HostAffinityRule

List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

placementGroupPartition

string (int64)

Placement group partition

HostAffinityRuleHostAffinityRule

Affinity definition

Field

Description

key

string

Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'

op

enum (Operator)

Include or exclude action

  • OPERATOR_UNSPECIFIED
  • IN
  • NOT_IN

values[]

string

Affinity value or host ID or host group ID

GpuSettingsGpuSettings

Field

Description

gpuClusterId

string

Attach instance to specified GPU cluster.

SerialPortSettingsSerialPortSettings

Field

Description

sshAuthorization

enum (SSHAuthorization)

Authentication and authorization in serial console when using SSH protocol

  • SSH_AUTHORIZATION_UNSPECIFIED
  • INSTANCE_METADATA: Authentication and authorization using SSH keys in instance metadata
  • OS_LOGIN: Authentication and authorization using Oslogin service

ResponseResponse

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": "boolean",
  "metadata": {
    "instanceId": "string"
  },
  // Includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": {
    "id": "string",
    "folderId": "string",
    "createdAt": "string",
    "name": "string",
    "description": "string",
    "labels": "object",
    "zoneId": "string",
    "platformId": "string",
    "resources": {
      "memory": "string",
      "cores": "string",
      "coreFraction": "string",
      "gpus": "string"
    },
    "status": "string",
    "metadata": "object",
    "metadataOptions": {
      "gceHttpEndpoint": "string",
      "awsV1HttpEndpoint": "string",
      "gceHttpToken": "string",
      "awsV1HttpToken": "string"
    },
    "bootDisk": {
      "mode": "string",
      "deviceName": "string",
      "autoDelete": "boolean",
      "diskId": "string"
    },
    "secondaryDisks": [
      {
        "mode": "string",
        "deviceName": "string",
        "autoDelete": "boolean",
        "diskId": "string"
      }
    ],
    "localDisks": [
      {
        "size": "string",
        "deviceName": "string"
      }
    ],
    "filesystems": [
      {
        "mode": "string",
        "deviceName": "string",
        "filesystemId": "string"
      }
    ],
    "networkInterfaces": [
      {
        "index": "string",
        "macAddress": "string",
        "subnetId": "string",
        "primaryV4Address": {
          "address": "string",
          "oneToOneNat": {
            "address": "string",
            "ipVersion": "string",
            "dnsRecords": [
              {
                "fqdn": "string",
                "dnsZoneId": "string",
                "ttl": "string",
                "ptr": "boolean"
              }
            ]
          },
          "dnsRecords": [
            {
              "fqdn": "string",
              "dnsZoneId": "string",
              "ttl": "string",
              "ptr": "boolean"
            }
          ]
        },
        "primaryV6Address": {
          "address": "string",
          "oneToOneNat": {
            "address": "string",
            "ipVersion": "string",
            "dnsRecords": [
              {
                "fqdn": "string",
                "dnsZoneId": "string",
                "ttl": "string",
                "ptr": "boolean"
              }
            ]
          },
          "dnsRecords": [
            {
              "fqdn": "string",
              "dnsZoneId": "string",
              "ttl": "string",
              "ptr": "boolean"
            }
          ]
        },
        "securityGroupIds": [
          "string"
        ]
      }
    ],
    "serialPortSettings": {
      "sshAuthorization": "string"
    },
    "gpuSettings": {
      "gpuClusterId": "string"
    },
    "fqdn": "string",
    "schedulingPolicy": {
      "preemptible": "boolean"
    },
    "serviceAccountId": "string",
    "networkSettings": {
      "type": "string"
    },
    "placementPolicy": {
      "placementGroupId": "string",
      "hostAffinityRules": [
        {
          "key": "string",
          "op": "string",
          "values": [
            "string"
          ]
        }
      ],
      "placementGroupPartition": "string"
    },
    "hostGroupId": "string",
    "hostId": "string",
    "maintenancePolicy": "string",
    "maintenanceGracePeriod": "string",
    "hardwareGeneration": {
      // Includes only one of the fields `legacyFeatures`, `generation2Features`
      "legacyFeatures": {
        "pciTopology": "string"
      },
      "generation2Features": "object"
      // end of the list of possible fields
    },
    "reservedInstancePoolId": "string"
  }
  // end of the list of possible fields
}

An Operation resource. For more information, see Operation.

Field

Description

id

string

ID of the operation.

description

string

Description of the operation. 0-256 characters long.

createdAt

string (date-time)

Creation timestamp.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

createdBy

string

ID of the user or service account who initiated the operation.

modifiedAt

string (date-time)

The time when the Operation resource was last modified.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

done

boolean

If the value is false, it means the operation is still in progress.
If true, the operation is completed, and either error or response is available.

metadata

CreateInstanceMetadata

Service-specific metadata associated with the operation.
It typically contains the ID of the target resource that the operation is performed on.
Any method that returns a long-running operation should document the metadata type, if any.

error

Status

The error result of the operation in case of failure or cancellation.

Includes only one of the fields error, response.

The operation result.
If done == false and there was no failure detected, neither error nor response is set.
If done == false and there was a failure detected, error is set.
If done == true, exactly one of error or response is set.

response

Instance

The normal response of the operation in case of success.
If the original method returns no data on success, such as Delete,
the response is google.protobuf.Empty.
If the original method is the standard Create/Update,
the response should be the target resource of the operation.
Any method that returns a long-running operation should document the response type, if any.

Includes only one of the fields error, response.

The operation result.
If done == false and there was no failure detected, neither error nor response is set.
If done == false and there was a failure detected, error is set.
If done == true, exactly one of error or response is set.

CreateInstanceMetadataCreateInstanceMetadata

Field

Description

instanceId

string

ID of the instance that is being created.

StatusStatus

The error result of the operation in case of failure or cancellation.

Field

Description

code

integer (int32)

Error code. An enum value of google.rpc.Code.

message

string

An error message.

details[]

object

A list of messages that carry the error details.

InstanceInstance

An Instance resource. For more information, see Instances.

Field

Description

id

string

ID of the instance.

folderId

string

ID of the folder that the instance belongs to.

createdAt

string (date-time)

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

name

string

Name of the instance. 1-63 characters long.

description

string

Description of the instance. 0-256 characters long.

labels

object (map<string, string>)

Resource labels as key:value pairs. Maximum of 64 per resource.

zoneId

string

ID of the availability zone where the instance resides.

platformId

string

ID of the hardware platform configuration for the instance.

resources

Resources

Computing resources of the instance such as the amount of memory and number of cores.

status

enum (Status)

Status of the instance.

  • STATUS_UNSPECIFIED
  • PROVISIONING: Instance is waiting for resources to be allocated.
  • RUNNING: Instance is running normally.
  • STOPPING: Instance is being stopped.
  • STOPPED: Instance stopped.
  • STARTING: Instance is being started.
  • RESTARTING: Instance is being restarted.
  • UPDATING: Instance is being updated.
  • ERROR: Instance encountered a problem and cannot operate.
  • CRASHED: Instance crashed and will be restarted automatically.
  • DELETING: Instance is being deleted.

metadata

object (map<string, string>)

The metadata key:value pairs assigned to this instance. This includes custom metadata and predefined keys.

For example, you may use the metadata in order to provide your public SSH key to the instance.
For more information, see Metadata.

metadataOptions

MetadataOptions

Options allow user to configure access to instance's metadata

bootDisk

AttachedDisk

Boot disk that is attached to the instance.

secondaryDisks[]

AttachedDisk

Array of secondary disks that are attached to the instance.

localDisks[]

AttachedLocalDisk

Array of local disks that are attached to the instance.

filesystems[]

AttachedFilesystem

Array of filesystems that are attached to the instance.

networkInterfaces[]

NetworkInterface

Array of network interfaces that are attached to the instance.

serialPortSettings

SerialPortSettings

Serial port settings

gpuSettings

GpuSettings

GPU settings

fqdn

string

A domain name of the instance. FQDN is defined by the server
in the format <hostname>.<region_id>.internal when the instance is created.
If the hostname were not specified when the instance was created, FQDN would be <id>.auto.internal.

schedulingPolicy

SchedulingPolicy

Scheduling policy configuration.

serviceAccountId

string

ID of the service account to use for authentication inside the instance.
To get the service account ID, use a yandex.cloud.iam.v1.ServiceAccountService.List request.

networkSettings

NetworkSettings

Network Settings

placementPolicy

PlacementPolicy

Placement policy configuration.

hostGroupId

string

ID of the dedicated host group that the instance belongs to.

hostId

string

ID of the dedicated host that the instance belongs to.

maintenancePolicy

enum (MaintenancePolicy)

Behaviour on maintenance events

  • MAINTENANCE_POLICY_UNSPECIFIED
  • RESTART: Restart instance to move it to another host during maintenance
  • MIGRATE: Use live migration to move instance to another host during maintenance

maintenanceGracePeriod

string (duration)

Time between notification via metadata service and maintenance

hardwareGeneration

HardwareGeneration

This feature set is inherited from the image/disk used as a boot one at the creation of the instance.

reservedInstancePoolId

string

ID of the reserved instance pool that the instance belongs to.

ResourcesResources

Field

Description

memory

string (int64)

The amount of memory available to the instance, specified in bytes.

cores

string (int64)

The number of cores available to the instance.

coreFraction

string (int64)

Baseline level of CPU performance with the ability to burst performance above that baseline level.
This field sets baseline performance for each core.

gpus

string (int64)

The number of GPUs available to the instance.

MetadataOptionsMetadataOptions

Field

Description

gceHttpEndpoint

enum (MetadataOption)

Enabled access to GCE flavored metadata

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

awsV1HttpEndpoint

enum (MetadataOption)

Enabled access to AWS flavored metadata (IMDSv1)

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

gceHttpToken

enum (MetadataOption)

Enabled access to IAM credentials with GCE flavored metadata

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

awsV1HttpToken

enum (MetadataOption)

Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)

  • METADATA_OPTION_UNSPECIFIED
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

AttachedDiskAttachedDisk

Field

Description

mode

enum (Mode)

Access mode to the Disk resource.

  • MODE_UNSPECIFIED
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.

deviceName

string

Serial number that is reflected into the /dev/disk/by-id/ tree
of a Linux operating system running within the instance.

This value can be used to reference the device for mounting, resizing, and so on, from within the instance.

autoDelete

boolean

Specifies whether the disk will be auto-deleted when the instance is deleted.

diskId

string

ID of the disk that is attached to the instance.

AttachedLocalDiskAttachedLocalDisk

Field

Description

size

string (int64)

Size of the disk, specified in bytes.

deviceName

string

Serial number that is reflected into the /dev/disk/by-id/ tree
of a Linux operating system running within the instance.

This value can be used to reference the device for mounting, resizing, and so on, from within the instance.

AttachedFilesystemAttachedFilesystem

Field

Description

mode

enum (Mode)

Access mode to the filesystem.

  • MODE_UNSPECIFIED
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.

deviceName

string

Name of the device representing the filesystem on the instance.

The name should be used for referencing the filesystem from within the instance
when it's being mounted, resized etc.

filesystemId

string

ID of the filesystem that is attached to the instance.

NetworkInterfaceNetworkInterface

Field

Description

index

string

The index of the network interface, will be generated by the server, 0,1,2... etc if not specified.

macAddress

string

MAC address that is assigned to the network interface.

subnetId

string

ID of the subnet.

primaryV4Address

PrimaryAddress

Primary IPv4 address that is assigned to the instance for this network interface.

primaryV6Address

PrimaryAddress

Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.

securityGroupIds[]

string

ID's of security groups attached to the interface

PrimaryAddressPrimaryAddress

Field

Description

address

string

An IPv4 internal network address that is assigned to the instance for this network interface.

oneToOneNat

OneToOneNat

One-to-one NAT configuration. If missing, NAT has not been set up.

dnsRecords[]

DnsRecord

Internal DNS configuration

OneToOneNatOneToOneNat

Field

Description

address

string

An external IP address associated with this instance.

ipVersion

enum (IpVersion)

IP version for the external IP address.

  • IP_VERSION_UNSPECIFIED
  • IPV4: IPv4 address, for example 192.0.2.235.
  • IPV6: IPv6 address. Not available yet.

dnsRecords[]

DnsRecord

External DNS configuration

DnsRecordDnsRecord

Field

Description

fqdn

string

Name of the A/AAAA record as specified when creating the instance.
Note that if `fqdn' has no trailing '.', it is specified relative to the zone (@see dns_zone_id).

dnsZoneId

string

DNS zone id for the record (optional, if not set, some private zone is used).

ttl

string (int64)

DNS record ttl (optional, if not set, a reasonable default is used.)

ptr

boolean

When true, indicates there is a corresponding auto-created PTR DNS record.

SerialPortSettingsSerialPortSettings

Field

Description

sshAuthorization

enum (SSHAuthorization)

Authentication and authorization in serial console when using SSH protocol

  • SSH_AUTHORIZATION_UNSPECIFIED
  • INSTANCE_METADATA: Authentication and authorization using SSH keys in instance metadata
  • OS_LOGIN: Authentication and authorization using Oslogin service

GpuSettingsGpuSettings

Field

Description

gpuClusterId

string

Attach instance to specified GPU cluster.

SchedulingPolicySchedulingPolicy

Field

Description

preemptible

boolean

True for short-lived compute instances. For more information, see Preemptible VMs.

NetworkSettingsNetworkSettings

Field

Description

type

enum (Type)

Network Type

  • TYPE_UNSPECIFIED
  • STANDARD: Standard network.
  • SOFTWARE_ACCELERATED: Software accelerated network.
  • HARDWARE_ACCELERATED: Hardware accelerated network (not available yet, reserved for future use).

PlacementPolicyPlacementPolicy

Field

Description

placementGroupId

string

Placement group ID.

hostAffinityRules[]

HostAffinityRule

List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

placementGroupPartition

string (int64)

Placement group partition

HostAffinityRuleHostAffinityRule

Affinity definition

Field

Description

key

string

Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'

op

enum (Operator)

Include or exclude action

  • OPERATOR_UNSPECIFIED
  • IN
  • NOT_IN

values[]

string

Affinity value or host ID or host group ID

HardwareGenerationHardwareGeneration

A set of features, specific to a particular Compute hardware generation.
They are not necessary supported by every host OS or distro, thus they are fixed to an image
and are applied to all instances created with it as their boot disk image.
These features significantly determine how the instance is created, thus cannot be changed after the fact.

Field

Description

legacyFeatures

LegacyHardwareFeatures

Includes only one of the fields legacyFeatures, generation2Features.

generation2Features

object

Includes only one of the fields legacyFeatures, generation2Features.

LegacyHardwareFeaturesLegacyHardwareFeatures

A first hardware generation, by default compatible with all legacy images.
Allows switching to PCI_TOPOLOGY_V2 and back.

Field

Description

pciTopology

enum (PCITopology)

  • PCI_TOPOLOGY_UNSPECIFIED
  • PCI_TOPOLOGY_V1
  • PCI_TOPOLOGY_V2

Was the article helpful?

Previous
List
Next
Update
Yandex project
© 2025 Yandex.Cloud LLC