instances

Creates, updates, deletes, gets or lists an instances resource.

Overview

Name	instances
Type	Resource
Id	google.notebooks.instances

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
id	string	Output only. Unique ID of the resource.
name	string	Output only. The name of this notebook instance. Format: projects/{project_id}/locations/{location}/instances/{instance_id}
createTime	string (google-datetime)	Output only. Instance creation time.
creator	string	Output only. Email address of entity that sent original CreateInstance request.
disableProxyAccess	boolean	Optional. If true, the notebook instance will not register with the proxy.
enableDeletionProtection	boolean	Optional. If true, deletion protection will be enabled for this Workbench Instance. If false, deletion protection will be disabled for this Workbench Instance.
enableManagedEuc	boolean	Optional. Flag to enable managed end user credentials for the instance.
enableThirdPartyIdentity	boolean	Optional. Flag that specifies that a notebook can be accessed with third party identity provider.
gceSetup	object	Optional. Compute Engine setup for the notebook. Uses notebook-defined fields. (id: GceSetup)
healthInfo	object	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" }
healthState	string	Output only. Instance health_state.
instanceOwners	array	Optional. 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.
labels	object	Optional. Labels to apply to this instance. These can be later modified by the UpdateInstance method.
proxyUri	string	Output only. The proxy endpoint that is used to access the Jupyter notebook.
satisfiesPzi	boolean	Output only. Reserved for future use for Zone Isolation.
satisfiesPzs	boolean	Output only. Reserved for future use for Zone Separation.
state	string	Output only. The state of this instance.
thirdPartyProxyUrl	string	Output only. The workforce pools proxy endpoint that is used to access the Jupyter notebook.
updateTime	string (google-datetime)	Output only. Instance update time.
upgradeHistory	array	Output only. The upgrade history of this instance.

list

Successful response

Name	Datatype	Description
id	string	Output only. Unique ID of the resource.
name	string	Output only. The name of this notebook instance. Format: projects/{project_id}/locations/{location}/instances/{instance_id}
createTime	string (google-datetime)	Output only. Instance creation time.
creator	string	Output only. Email address of entity that sent original CreateInstance request.
disableProxyAccess	boolean	Optional. If true, the notebook instance will not register with the proxy.
enableDeletionProtection	boolean	Optional. If true, deletion protection will be enabled for this Workbench Instance. If false, deletion protection will be disabled for this Workbench Instance.
enableManagedEuc	boolean	Optional. Flag to enable managed end user credentials for the instance.
enableThirdPartyIdentity	boolean	Optional. Flag that specifies that a notebook can be accessed with third party identity provider.
gceSetup	object	Optional. Compute Engine setup for the notebook. Uses notebook-defined fields. (id: GceSetup)
healthInfo	object	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" }
healthState	string	Output only. Instance health_state.
instanceOwners	array	Optional. 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.
labels	object	Optional. Labels to apply to this instance. These can be later modified by the UpdateInstance method.
proxyUri	string	Output only. The proxy endpoint that is used to access the Jupyter notebook.
satisfiesPzi	boolean	Output only. Reserved for future use for Zone Isolation.
satisfiesPzs	boolean	Output only. Reserved for future use for Zone Separation.
state	string	Output only. The state of this instance.
thirdPartyProxyUrl	string	Output only. The workforce pools proxy endpoint that is used to access the Jupyter notebook.
updateTime	string (google-datetime)	Output only. Instance update time.
upgradeHistory	array	Output only. The upgrade history of this instance.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, instancesId		Gets details of a single Instance.
list	select	projectsId, locationsId	pageSize, pageToken, orderBy, filter	Lists instances in a given project and location.
create	insert	projectsId, locationsId	instanceId, requestId	Creates a new Instance in a given project and location.
patch	update	projectsId, locationsId, instancesId	updateMask, requestId	UpdateInstance updates an Instance.
delete	delete	projectsId, locationsId, instancesId	requestId	Deletes a single Instance.
start	exec	projectsId, locationsId, instancesId		Starts a notebook instance.
stop	exec	projectsId, locationsId, instancesId		Stops a notebook instance.
reset	exec	projectsId, locationsId, instancesId		Resets a notebook instance.
check_upgradability	exec	projectsId, locationsId, instancesId		Checks whether a notebook instance is upgradable.
upgrade	exec	projectsId, locationsId, instancesId		Upgrades a notebook instance to the latest version.
resize_disk	exec	projectsId, locationsId, instancesId		Resize a notebook instance disk to a higher capacity.
rollback	exec	projectsId, locationsId, instancesId		Rollbacks a notebook instance to the previous version.
diagnose	exec	projectsId, locationsId, instancesId		Creates a Diagnostic File and runs Diagnostic Tool given an Instance.
restore	exec	projectsId, locationsId, instancesId		RestoreInstance restores an Instance from a BackupSource.
report_info_system	exec	projectsId, locationsId, instancesId		Allows notebook instances to report their latest instance information to the Notebooks API server. The server will merge the reported information to the instance metadata store. Do not use this method directly.
upgrade_system	exec	projectsId, locationsId, instancesId		Allows notebook instances to upgrade themselves. Do not use this method directly.
check_authorization	exec	projectsId, locationsId, instancesId		Initiated by Cloud Console for Oauth consent flow for Workbench Instances. Do not use this method directly. Design doc: go/wbi-euc:auth-dd
generate_access_token	exec	projectsId, locationsId, instancesId		Called by VM to return an EUC for the instance owner. Do not use this method directly. Design doc: go/wbi-euc:dd

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
instancesId	string
locationsId	string
projectsId	string
filter	string
instanceId	string
orderBy	string
pageSize	integer (int32)
pageToken	string
requestId	string
updateMask	string (google-fieldmask)

SELECT examples

get

Gets details of a single Instance.

SELECT
id,
name,
createTime,
creator,
disableProxyAccess,
enableDeletionProtection,
enableManagedEuc,
enableThirdPartyIdentity,
gceSetup,
healthInfo,
healthState,
instanceOwners,
labels,
proxyUri,
satisfiesPzi,
satisfiesPzs,
state,
thirdPartyProxyUrl,
updateTime,
upgradeHistory
FROM google.notebooks.instances
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND instancesId = '{{ instancesId }}' -- required;

list

Lists instances in a given project and location.

SELECT
id,
name,
createTime,
creator,
disableProxyAccess,
enableDeletionProtection,
enableManagedEuc,
enableThirdPartyIdentity,
gceSetup,
healthInfo,
healthState,
instanceOwners,
labels,
proxyUri,
satisfiesPzi,
satisfiesPzs,
state,
thirdPartyProxyUrl,
updateTime,
upgradeHistory
FROM google.notebooks.instances
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND orderBy = '{{ orderBy }}'
AND filter = '{{ filter }}';

INSERT examples

create

Creates a new Instance in a given project and location.

INSERT INTO google.notebooks.instances (
data__gceSetup,
data__instanceOwners,
data__disableProxyAccess,
data__labels,
data__enableThirdPartyIdentity,
data__enableManagedEuc,
data__enableDeletionProtection,
projectsId,
locationsId,
instanceId,
requestId
)
SELECT 
'{{ gceSetup }}',
'{{ instanceOwners }}',
{{ disableProxyAccess }},
'{{ labels }}',
{{ enableThirdPartyIdentity }},
{{ enableManagedEuc }},
{{ enableDeletionProtection }},
'{{ projectsId }}',
'{{ locationsId }}',
'{{ instanceId }}',
'{{ requestId }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: instances
  props:
    - name: projectsId
      value: string
      description: Required parameter for the instances resource.
    - name: locationsId
      value: string
      description: Required parameter for the instances resource.
    - name: gceSetup
      value: object
      description: >
        Optional. Compute Engine setup for the notebook. Uses notebook-defined fields.
        
    - name: instanceOwners
      value: array
      description: >
        Optional. 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.
        
    - name: disableProxyAccess
      value: boolean
      description: >
        Optional. If true, the notebook instance will not register with the proxy.
        
    - name: labels
      value: object
      description: >
        Optional. Labels to apply to this instance. These can be later modified by the UpdateInstance method.
        
    - name: enableThirdPartyIdentity
      value: boolean
      description: >
        Optional. Flag that specifies that a notebook can be accessed with third party identity provider.
        
    - name: enableManagedEuc
      value: boolean
      description: >
        Optional. Flag to enable managed end user credentials for the instance.
        
    - name: enableDeletionProtection
      value: boolean
      description: >
        Optional. If true, deletion protection will be enabled for this Workbench Instance. If false, deletion protection will be disabled for this Workbench Instance.
        
    - name: instanceId
      value: string
    - name: requestId
      value: string

UPDATE examples

patch

UpdateInstance updates an Instance.

UPDATE google.notebooks.instances
SET 
data__gceSetup = '{{ gceSetup }}',
data__instanceOwners = '{{ instanceOwners }}',
data__disableProxyAccess = {{ disableProxyAccess }},
data__labels = '{{ labels }}',
data__enableThirdPartyIdentity = {{ enableThirdPartyIdentity }},
data__enableManagedEuc = {{ enableManagedEuc }},
data__enableDeletionProtection = {{ enableDeletionProtection }}
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND instancesId = '{{ instancesId }}' --required
AND updateMask = '{{ updateMask}}'
AND requestId = '{{ requestId}}'
RETURNING
name,
done,
error,
metadata,
response;

DELETE examples

delete

Deletes a single Instance.

DELETE FROM google.notebooks.instances
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND instancesId = '{{ instancesId }}' --required
AND requestId = '{{ requestId }}';

Lifecycle Methods

start

Starts a notebook instance.

EXEC google.notebooks.instances.start 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required;

stop

Stops a notebook instance.

EXEC google.notebooks.instances.stop 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required;

reset

Resets a notebook instance.

EXEC google.notebooks.instances.reset 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required;

check_upgradability

Checks whether a notebook instance is upgradable.

EXEC google.notebooks.instances.check_upgradability 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required;

upgrade

Upgrades a notebook instance to the latest version.

EXEC google.notebooks.instances.upgrade 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required;

resize_disk

Resize a notebook instance disk to a higher capacity.

EXEC google.notebooks.instances.resize_disk 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"bootDisk": "{{ bootDisk }}", 
"dataDisk": "{{ dataDisk }}"
}';

rollback

Rollbacks a notebook instance to the previous version.

EXEC google.notebooks.instances.rollback 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"targetSnapshot": "{{ targetSnapshot }}"
}';

diagnose

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

EXEC google.notebooks.instances.diagnose 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"diagnosticConfig": "{{ diagnosticConfig }}", 
"timeoutMinutes": {{ timeoutMinutes }}
}';

restore

RestoreInstance restores an Instance from a BackupSource.

EXEC google.notebooks.instances.restore 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"snapshot": "{{ snapshot }}"
}';

report_info_system

Allows notebook instances to report their latest instance information to the Notebooks API server. The server will merge the reported information to the instance metadata store. Do not use this method directly.

EXEC google.notebooks.instances.report_info_system 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"vmId": "{{ vmId }}", 
"event": "{{ event }}"
}';

upgrade_system

Allows notebook instances to upgrade themselves. Do not use this method directly.

EXEC google.notebooks.instances.upgrade_system 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"vmId": "{{ vmId }}"
}';

check_authorization

Initiated by Cloud Console for Oauth consent flow for Workbench Instances. Do not use this method directly. Design doc: go/wbi-euc:auth-dd

EXEC google.notebooks.instances.check_authorization 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"authorizationDetails": "{{ authorizationDetails }}"
}';

generate_access_token

Called by VM to return an EUC for the instance owner. Do not use this method directly. Design doc: go/wbi-euc:dd

EXEC google.notebooks.instances.generate_access_token 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"vmToken": "{{ vmToken }}"
}';