Skip to main content

List

Retrieves the list of Instance resources in the specified folder.

import { cloudApi, serviceClients, Session } from "@yandex-cloud/nodejs-sdk";

const ListInstancesRequest =
  cloudApi.compute.instance_service.ListInstancesRequest;

(async () => {
  const authToken = process.env["YC_OAUTH_TOKEN"];
  const session = new Session({ oauthToken: authToken });
  const client = session.client(serviceClients.InstanceServiceClient);

  const result = await client.list(
    ListInstancesRequest.fromPartial({
      folderId: "folderId",
      // pageSize: 0,
      // pageToken: "pageToken",
      // filter: "filter",
      // orderBy: "orderBy"
    })
  );
  console.log(result);
})();

ListInstancesRequest​

folderId : string​

ID of the Folder to list instances in. To get the folder ID, use a yandex.cloud.resourcemanager.v1.FolderService.List request.

pageSize : int64​

The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a ListInstancesResponse.next_page_token that can be used to get the next page of results in subsequent list requests.

pageToken : string​

Page token. To get the next page of results, set page_token to the ListInstancesResponse.next_page_token returned by a previous list request.

filter : string​

A filter expression that filters resources listed in the response. The expression consists of one or more conditions united by AND operator: <condition1> [AND <condition2> [<...> AND <conditionN>]].

Each condition has the form <field> <operator> <value>, where:

  1. <field> is the field name. Currently you can use filtering only on the limited number of fields.
  2. <operator> is a logical operator, one of =, !=, IN, NOT IN.
  3. <value> represents a value. String values should be written in double (") or single (') quotes. C-style escape sequences are supported (\" turns to ", \' to ', \\ to backslash).
orderBy : string​

By which column the listing should be ordered and in which direction, format is "createdAt desc". "id asc" if omitted. The default sorting order is ascending

ListInstancesResponse​

instances : Instance​

List of Instance resources.

nextPageToken : string​

This token allows you to get the next page of results for list requests. If the number of results is larger than ListInstancesRequest.page_size, use the next_page_token as the value for the ListInstancesRequest.page_token query parameter in the next list request. Each subsequent list request will have its own next_page_token to continue paging through the results.

Instance​

An Instance resource. For more information, see Instances.

Status​
  • 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.

id : string​

ID of the instance.

folderId : string​

ID of the folder that the instance belongs to.

createdAt : google.protobuf.Timestamp​
name : string​

Name of the instance. 1-63 characters long.

description : string​

Description of the instance. 0-256 characters long.

labels : 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 : Status​

Status of the instance.

metadata : 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 : MaintenancePolicy​

Behaviour on maintenance events

maintenanceGracePeriod : google.protobuf.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.

Resources​

memory : int64​

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

cores : int64​

The number of cores available to the instance.

coreFraction : 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 : int64​

The number of GPUs available to the instance.

MetadataOptions​

gceHttpEndpoint : MetadataOption​

Enabled access to GCE flavored metadata

awsV1HttpEndpoint : MetadataOption​

Enabled access to AWS flavored metadata (IMDSv1)

gceHttpToken : MetadataOption​

Enabled access to IAM credentials with GCE flavored metadata

awsV1HttpToken : MetadataOption​

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

AttachedDisk​

Mode​
  • MODE_UNSPECIFIED

  • READ_ONLY

    Read-only access.

  • READ_WRITE

    Read/Write access.

mode : Mode​

Access mode to the Disk resource.

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 : bool​

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.

AttachedLocalDisk​

size : 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.

AttachedFilesystem​

Mode​
  • MODE_UNSPECIFIED

  • READ_ONLY

    Read-only access.

  • READ_WRITE

    Read/Write access.

mode : Mode​

Access mode to the filesystem.

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.

NetworkInterface​

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

SerialPortSettings​

SSHAuthorization​
  • SSH_AUTHORIZATION_UNSPECIFIED

  • INSTANCE_METADATA

    Authentication and authorization using SSH keys in instance metadata

  • OS_LOGIN

    Authentication and authorization using Oslogin service

sshAuthorization : SSHAuthorization​

Authentication and authorization in serial console when using SSH protocol

GpuSettings​

gpuClusterId : string​

Attach instance to specified GPU cluster.

SchedulingPolicy​

preemptible : bool​

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

NetworkSettings​

Type​
  • TYPE_UNSPECIFIED

  • STANDARD

    Standard network.

  • SOFTWARE_ACCELERATED

    Software accelerated network.

  • HARDWARE_ACCELERATED

    Hardware accelerated network (not available yet, reserved for future use).

type : Type​

Network Type

PlacementPolicy​

HostAffinityRule​

Affinity definition

Operator​
  • OPERATOR_UNSPECIFIED

  • IN

  • NOT_IN

key : string​

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

op : Operator​

Include or exclude action

values : string​

Affinity value or host ID or host group ID

placementGroupId : string​

Placement group ID.

hostAffinityRules : HostAffinityRule​

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

placementGroupPartition : int64​

Placement group partition

HardwareGeneration​

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.

One of features​

  • legacyFeatures : LegacyHardwareFeatures​
  • generation2Features : Generation2HardwareFeatures​

PrimaryAddress​

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

HostAffinityRule​

Affinity definition

Operator​
  • OPERATOR_UNSPECIFIED

  • IN

  • NOT_IN

key : string​

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

op : Operator​

Include or exclude action

values : string​

Affinity value or host ID or host group ID

LegacyHardwareFeatures​

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

pciTopology : PCITopology​

Generation2HardwareFeatures​

A second hardware generation, which by default assumes PCI_TOPOLOGY_V2 and UEFI boot (with UEFI related features).

OneToOneNat​

address : string​

An external IP address associated with this instance.

ipVersion : IpVersion​

IP version for the external IP address.

dnsRecords : DnsRecord​

External DNS configuration

DnsRecord​

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 : int64​

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

ptr : bool​

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