REST Resource: projects.locations.instances

Resource: Instance

The definition of a notebook instance.

JSON representation 
{
  "name": string,
  "proxyUri": string,
  "instanceOwners": [
    string
  ],
  "creator": string,
  "state": enum (State),
  "upgradeHistory": [
    {
      object (UpgradeHistoryEntry)
    }
  ],
  "id": string,
  "healthState": enum (HealthState),
  "healthInfo": {
    string: string,
    ...
  },
  "createTime": string,
  "updateTime": string,
  "disableProxyAccess": boolean,
  "labels": {
    string: string,
    ...
  },
  "thirdPartyProxyUrl": string,
  "satisfiesPzs": boolean,
  "satisfiesPzi": boolean,

  // Union field infrastructure can be only one of the following:
  "gceSetup": {
    object (GceSetup)
  }
  // End of list of possible types for union field infrastructure.
}
Fields
name

string

Output only. The name of this notebook instance. Format: projects/{projectId}/locations/{location}/instances/{instanceId}
proxyUri

string

Output only. The proxy endpoint that is used to access the Jupyter notebook.
instanceOwners[]

string

Optional. Input only. The owner of this instance after creation. Format: alias@example.com

Currently supports one owner only. If not specified, all of the service account users of your VM instance's service account can use the instance.
creator

string

Output only. Email address of entity that sent original instances.create request.
state

enum (State)

Output only. The state of this instance.
upgradeHistory[]

object (UpgradeHistoryEntry)

Output only. The upgrade history of this instance.
id

string

Output only. Unique ID of the resource.
healthState

enum (HealthState)

Output only. Instance healthState.
healthInfo

map (key: string, value: string)

Output only. Additional information about instance health. Example:

healthInfo": {
  "docker_proxy_agent_status": "1",
  "docker_status": "1",
  "jupyterlab_api_status": "-1",
  "jupyterlab_status": "-1",
  "updated": "2020-10-18 09:40:03.573409"
}

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
createTime

string (Timestamp format)

Output only. Instance creation time.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. Instance update time.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
disableProxyAccess

boolean

Optional. If true, the notebook instance will not register with the proxy.
labels

map (key: string, value: string)

Optional. Labels to apply to this instance. These can be later modified by the instances.patch method.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
thirdPartyProxyUrl

string

Output only. The workforce pools proxy endpoint that is used to access the Jupyter notebook.
satisfiesPzs

boolean

Output only. Reserved for future use for Zone Separation.
satisfiesPzi

boolean

Output only. Reserved for future use for Zone Isolation.
Union field infrastructure. Setup for the Notebook instance. infrastructure can be only one of the following:
gceSetup

object (GceSetup)

Optional. Compute Engine setup for the notebook. Uses notebook-defined fields.

GceSetup

The definition of how to configure a VM instance outside of Resources and Identity.

JSON representation 
{
  "machineType": string,
  "minCpuPlatform": string,
  "acceleratorConfigs": [
    {
      object (AcceleratorConfig)
    }
  ],
  "serviceAccounts": [
    {
      object (ServiceAccount)
    }
  ],
  "bootDisk": {
    object (BootDisk)
  },
  "dataDisks": [
    {
      object (DataDisk)
    }
  ],
  "shieldedInstanceConfig": {
    object (ShieldedInstanceConfig)
  },
  "networkInterfaces": [
    {
      object (NetworkInterface)
    }
  ],
  "disablePublicIp": boolean,
  "tags": [
    string
  ],
  "metadata": {
    string: string,
    ...
  },
  "enableIpForwarding": boolean,
  "gpuDriverConfig": {
    object (GPUDriverConfig)
  },

  // Union field image can be only one of the following:
  "vmImage": {
    object (VmImage)
  },
  "containerImage": {
    object (ContainerImage)
  }
  // End of list of possible types for union field image.
}
Fields
machineType

string

Optional. The machine type of the VM instance. https://cloud.google.com/compute/docs/machine-resource
minCpuPlatform

string

Optional. The minimum CPU platform to use for this instance. The list of valid values can be found in https://cloud.google.com/compute/docs/instances/specify-min-cpu-platform#availablezones
acceleratorConfigs[]

object (AcceleratorConfig)

Optional. The hardware accelerators used on this instance. If you use accelerators, make sure that your configuration has enough vCPUs and memory to support the machineType you have selected. Currently supports only one accelerator configuration.
serviceAccounts[]

object (ServiceAccount)

Optional. The service account that serves as an identity for the VM instance. Currently supports only one service account.
bootDisk

object (BootDisk)

Optional. The boot disk for the VM.
dataDisks[]

object (DataDisk)

Optional. Data disks attached to the VM instance. Currently supports only one data disk.
shieldedInstanceConfig

object (ShieldedInstanceConfig)

Optional. Shielded VM configuration. Images using supported Shielded VM features.
networkInterfaces[]

object (NetworkInterface)

Optional. The network interfaces for the VM. Supports only one interface.
disablePublicIp

boolean

Optional. If true, no external IP will be assigned to this VM instance.
tags[]

string

Optional. The Compute Engine network tags to add to runtime (see Add network tags).
metadata

map (key: string, value: string)

Optional. Custom metadata to apply to this instance.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
enableIpForwarding

boolean

Optional. Flag to enable ip forwarding or not, default false/off. https://cloud.google.com/vpc/docs/using-routes#canipforward
gpuDriverConfig

object (GPUDriverConfig)

Optional. Configuration for GPU drivers.
Union field image. Type of the image; can be one of VM image, or container image. image can be only one of the following:
vmImage

object (VmImage)

Optional. Use a Compute Engine VM image to start the notebook instance.
containerImage

object (ContainerImage)

Optional. Use a container image to start the notebook instance.

AcceleratorConfig

An accelerator configuration for a VM instance Definition of a hardware accelerator. Note that there is no check on type and coreCount combinations. TPUs are not supported. See GPUs on Compute Engine to find a valid combination.

JSON representation 
{
  "type": enum (AcceleratorType),
  "coreCount": string
}
Fields
type

enum (AcceleratorType)

Optional. Type of this accelerator.
coreCount

string (int64 format)

Optional. Count of cores of this accelerator.

AcceleratorType

Definition of the types of hardware accelerators that can be used on this instance.

Enums
ACCELERATOR_TYPE_UNSPECIFIED Accelerator type is not specified.
NVIDIA_TESLA_P100 Accelerator type is Nvidia Tesla P100.
NVIDIA_TESLA_V100 Accelerator type is Nvidia Tesla V100.
NVIDIA_TESLA_P4 Accelerator type is Nvidia Tesla P4.
NVIDIA_TESLA_T4 Accelerator type is Nvidia Tesla T4.
NVIDIA_TESLA_A100 Accelerator type is Nvidia Tesla A100 - 40GB.
NVIDIA_A100_80GB Accelerator type is Nvidia Tesla A100 - 80GB.
NVIDIA_L4 Accelerator type is Nvidia Tesla L4.
NVIDIA_H100_80GB Accelerator type is Nvidia Tesla H100 - 80GB.
NVIDIA_H100_MEGA_80GB Accelerator type is Nvidia Tesla H100 - MEGA 80GB.
NVIDIA_TESLA_T4_VWS Accelerator type is NVIDIA Tesla T4 Virtual Workstations.
NVIDIA_TESLA_P100_VWS Accelerator type is NVIDIA Tesla P100 Virtual Workstations.
NVIDIA_TESLA_P4_VWS Accelerator type is NVIDIA Tesla P4 Virtual Workstations.

ServiceAccount

A service account that acts as an identity.

JSON representation 
{
  "email": string,
  "scopes": [
    string
  ]
}
Fields
email

string

Optional. Email address of the service account.
scopes[]

string

Output only. The list of scopes to be made available for this service account. Set by the CLH to https://www.googleapis.com/auth/cloud-platform

VmImage

Definition of a custom Compute Engine virtual machine image for starting a notebook instance with the environment installed directly on the VM.

JSON representation 
{
  "project": string,

  // Union field image can be only one of the following:
  "name": string,
  "family": string
  // End of list of possible types for union field image.
}
Fields
project

string

Required. The name of the Google Cloud project that this VM image belongs to. Format: {projectId}
Union field image. The reference to an external Compute Engine VM image. image can be only one of the following:
name

string

Optional. Use VM image name to find the image.
family

string

Optional. Use this VM image family to find the image; the newest image in this family will be used.

ContainerImage

Definition of a container image for starting a notebook instance with the environment installed in a container.

JSON representation 
{
  "repository": string,
  "tag": string
}
Fields
repository

string

Required. The path to the container image repository. For example: gcr.io/{projectId}/{imageName}
tag

string

Optional. The tag of the container image. If not specified, this defaults to the latest tag.

BootDisk

The definition of a boot disk.

JSON representation 
{
  "diskSizeGb": string,
  "diskType": enum (DiskType),
  "diskEncryption": enum (DiskEncryption),
  "kmsKey": string
}
Fields
diskSizeGb

string (int64 format)

Optional. The size of the boot disk in GB attached to this instance, up to a maximum of 64000 GB (64 TB). If not specified, this defaults to the recommended value of 150GB.
diskType

enum (DiskType)

Optional. Indicates the type of the disk.
diskEncryption

enum (DiskEncryption)

Optional. Input only. Disk encryption method used on the boot and data disks, defaults to GMEK.
kmsKey

string

Optional. Input only. The KMS key used to encrypt the disks, only applicable if diskEncryption is CMEK. Format: projects/{projectId}/locations/{location}/keyRings/{key_ring_id}/cryptoKeys/{key_id}

Learn more about using your own encryption keys.

DiskType

Possible disk types.

Enums
DISK_TYPE_UNSPECIFIED Disk type not set.
PD_STANDARD Standard persistent disk type.
PD_SSD SSD persistent disk type.
PD_BALANCED Balanced persistent disk type.
PD_EXTREME Extreme persistent disk type.

DiskEncryption

Definition of the disk encryption options.

Enums
DISK_ENCRYPTION_UNSPECIFIED Disk encryption is not specified.
GMEK Use Google managed encryption keys to encrypt the boot disk.
CMEK Use customer managed encryption keys to encrypt the boot disk.

DataDisk

An instance-attached disk resource.

JSON representation 
{
  "diskSizeGb": string,
  "diskType": enum (DiskType),
  "diskEncryption": enum (DiskEncryption),
  "kmsKey": string
}
Fields
diskSizeGb

string (int64 format)

Optional. The size of the disk in GB attached to this VM instance, up to a maximum of 64000 GB (64 TB). If not specified, this defaults to 100.
diskType

enum (DiskType)

Optional. Input only. Indicates the type of the disk.
diskEncryption

enum (DiskEncryption)

Optional. Input only. Disk encryption method used on the boot and data disks, defaults to GMEK.
kmsKey

string

Optional. Input only. The KMS key used to encrypt the disks, only applicable if diskEncryption is CMEK. Format: projects/{projectId}/locations/{location}/keyRings/{key_ring_id}/cryptoKeys/{key_id}

Learn more about using your own encryption keys.

ShieldedInstanceConfig

A set of Shielded Instance options. See Images using supported Shielded VM features. Not all combinations are valid.

JSON representation 
{
  "enableSecureBoot": boolean,
  "enableVtpm": boolean,
  "enableIntegrityMonitoring": boolean
}
Fields
enableSecureBoot

boolean

Optional. Defines whether the VM instance has Secure Boot enabled.

Secure Boot helps ensure that the system only runs authentic software by verifying the digital signature of all boot components, and halting the boot process if signature verification fails. Disabled by default.
enableVtpm

boolean

Optional. Defines whether the VM instance has the vTPM enabled. Enabled by default.
enableIntegrityMonitoring

boolean

Optional. Defines whether the VM instance has integrity monitoring enabled.

Enables monitoring and attestation of the boot integrity of the VM instance. The attestation is performed against the integrity policy baseline. This baseline is initially derived from the implicitly trusted boot image when the VM instance is created. Enabled by default.

NetworkInterface

The definition of a network interface resource attached to a VM.

JSON representation 
{
  "network": string,
  "subnet": string,
  "nicType": enum (NicType),
  "accessConfigs": [
    {
      object (AccessConfig)
    }
  ]
}
Fields
network

string

Optional. The name of the VPC that this VM instance is in. Format: projects/{projectId}/global/networks/{network_id}
subnet

string

Optional. The name of the subnet that this VM instance is in. Format: projects/{projectId}/regions/{region}/subnetworks/{subnetwork_id}
nicType

enum (NicType)

Optional. The type of vNIC to be used on this interface. This may be gVNIC or VirtioNet.
accessConfigs[]

object (AccessConfig)

Optional. An array of configurations for this interface. Currently, only one access config, ONE_TO_ONE_NAT, is supported. If no accessConfigs specified, the instance will have an external internet access through an ephemeral external IP address.

NicType

The type of vNIC driver. Default should be NIC_TYPE_UNSPECIFIED.

Enums
NIC_TYPE_UNSPECIFIED No type specified.
VIRTIO_NET VIRTIO
GVNIC GVNIC

AccessConfig

An access configuration attached to an instance's network interface.

JSON representation 
{
  "externalIp": string
}
Fields
externalIp

string

An external IP address associated with this instance. Specify an unused static external IP address available to the project or leave this field undefined to use an IP from a shared ephemeral IP address pool. If you specify a static external IP address, it must live in the same region as the zone of the instance.

GPUDriverConfig

A GPU driver configuration

JSON representation 
{
  "enableGpuDriver": boolean,
  "customGpuDriverPath": string
}
Fields
enableGpuDriver

boolean

Optional. Whether the end user authorizes Google Cloud to install GPU driver on this VM instance. If this field is empty or set to false, the GPU driver won't be installed. Only applicable to instances with GPUs.
customGpuDriverPath

string

Optional. Specify a custom Cloud Storage path where the GPU driver is stored. If not specified, we'll automatically choose from official GPU drivers.

State

The definition of the states of this instance.

Enums
STATE_UNSPECIFIED State is not specified.
STARTING The control logic is starting the instance.
PROVISIONING The control logic is installing required frameworks and registering the instance with notebook proxy
ACTIVE The instance is running.
STOPPING The control logic is stopping the instance.
STOPPED The instance is stopped.
DELETED The instance is deleted.
UPGRADING The instance is upgrading.
INITIALIZING The instance is being created.
SUSPENDING The instance is suspending.
SUSPENDED The instance is suspended.

UpgradeHistoryEntry

The entry of VM image upgrade history.

JSON representation 
{
  "snapshot": string,
  "vmImage": string,
  "containerImage": string,
  "framework": string,
  "version": string,
  "state": enum (State),
  "createTime": string,
  "action": enum (Action),
  "targetVersion": string
}
Fields
snapshot

string

Optional. The snapshot of the boot disk of this notebook instance before upgrade.
vmImage

string

Optional. The VM image before this instance upgrade.
containerImage

string

Optional. The container image before this instance upgrade.
framework

string

Optional. The framework of this notebook instance.
version

string

Optional. The version of the notebook instance before this upgrade.
state

enum (State)

Output only. The state of this instance upgrade history entry.
createTime

string (Timestamp format)

Immutable. The time that this instance upgrade history entry is created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
action

enum (Action)

Optional. Action. Rolloback or Upgrade.
targetVersion

string

Optional. Target VM Version, like m63.

State

The definition of the states of this upgrade history entry.

Enums
STATE_UNSPECIFIED State is not specified.
STARTED The instance upgrade is started.
SUCCEEDED The instance upgrade is succeeded.
FAILED The instance upgrade is failed.

Action

The definition of operations of this upgrade history entry.

Enums
ACTION_UNSPECIFIED Operation is not specified.
UPGRADE Upgrade.
ROLLBACK Rollback.

HealthState

The instance health state.

Enums
HEALTH_STATE_UNSPECIFIED The instance substate is unknown.
HEALTHY The instance is known to be in an healthy state (for example, critical daemons are running) Applies to ACTIVE state.
UNHEALTHY The instance is known to be in an unhealthy state (for example, critical daemons are not running) Applies to ACTIVE state.
AGENT_NOT_INSTALLED The instance has not installed health monitoring agent. Applies to ACTIVE state.
AGENT_NOT_RUNNING The instance health monitoring agent is not running. Applies to ACTIVE state.

Methods

checkUpgradability

 Checks whether a notebook instance is upgradable.

create

 Creates a new Instance in a given project and location.

delete

 Deletes a single Instance.

diagnose

 Creates a Diagnostic File and runs Diagnostic Tool given an Instance.

get

 Gets details of a single Instance.

getIamPolicy

 Gets the access control policy for a resource.

list

 Lists instances in a given project and location.

patch

 UpdateInstance updates an Instance.

reset

 Resets a notebook instance.

resizeDisk

 Resize a notebook instance disk to a higher capacity.

restore

 RestoreInstance restores an Instance from a BackupSource.

rollback

 Rollbacks a notebook instance to the previous version.

setIamPolicy

 Sets the access control policy on the specified resource.

start

 Starts a notebook instance.

stop

 Stops a notebook instance.

testIamPermissions

 Returns permissions that a caller has on the specified resource.

upgrade

 Upgrades a notebook instance to the latest version.