instances

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

Overview

Name	instances
Type	Resource
Id	google.file.instances

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	Output only. The resource name of the instance, in the format projects/{project}/locations/{location}/instances/{instance}.
capacityStepSizeGb	string (int64)	Output only. The incremental increase or decrease in capacity, designated in some number of GB.
createTime	string (google-datetime)	Output only. The time when the instance was created.
customPerformanceSupported	boolean	Output only. Indicates whether this instance supports configuring its performance. If true, the user can configure the instance's performance by using the 'performance_config' field.
deletionProtectionEnabled	boolean	Optional. Indicates whether the instance is protected against deletion.
deletionProtectionReason	string	Optional. The reason for enabling deletion protection.
description	string	The description of the instance (2048 characters or less).
directoryServices	object	Optional. Directory Services configuration for Kerberos-based authentication. Should only be set if protocol is "NFS_V4_1". (id: DirectoryServicesConfig)
etag	string	Server-specified ETag for the instance resource to prevent simultaneous updates from overwriting each other.
fileShares	array	File system shares on the instance. For this version, only a single file share is supported.
kmsKeyName	string	KMS key name used for data encryption.
labels	object	Resource labels to represent user provided metadata.
maxCapacityGb	string (int64)	Output only. The maximum capacity of the instance in GB.
minCapacityGb	string (int64)	Output only. The minimum capacity of the instance in GB.
networks	array	VPC networks to which the instance is connected. For this version, only a single network is supported.
performanceConfig	object	Optional. Used to configure performance. (id: PerformanceConfig)
performanceLimits	object	Output only. Used for getting performance limits. (id: PerformanceLimits)
protocol	string	Immutable. The protocol indicates the access protocol for all shares in the instance. This field is immutable and it cannot be changed after the instance has been created. Default value: NFS_V3. (FILE_PROTOCOL_UNSPECIFIED, NFS_V3, NFS_V4_1)
replication	object	Optional. Replication configuration. (id: Replication)
satisfiesPzi	boolean	Output only. Reserved for future use.
satisfiesPzs	boolean	Output only. Reserved for future use.
state	string	Output only. The instance state. (STATE_UNSPECIFIED, CREATING, READY, REPAIRING, DELETING, ERROR, RESTORING, SUSPENDED, SUSPENDING, RESUMING, REVERTING, PROMOTING)
statusMessage	string	Output only. Additional information about the instance state, if available.
suspensionReasons	array	Output only. Field indicates all the reasons the instance is in "SUSPENDED" state.
tags	object	Optional. Input only. Immutable. Tag key-value pairs bound to this resource. Each key must be a namespaced name and each value a short name. Example: "123456789012/environment" : "production", "123456789013/costCenter" : "marketing" See the documentation for more information: - Namespaced name: https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing#retrieving_tag_key - Short name: https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing#retrieving_tag_value
tier	string	The service tier of the instance. (TIER_UNSPECIFIED, STANDARD, PREMIUM, BASIC_HDD, BASIC_SSD, HIGH_SCALE_SSD, ENTERPRISE, ZONAL, REGIONAL)

list

Name	Datatype	Description
name	string	Output only. The resource name of the instance, in the format projects/{project}/locations/{location}/instances/{instance}.
capacityStepSizeGb	string (int64)	Output only. The incremental increase or decrease in capacity, designated in some number of GB.
createTime	string (google-datetime)	Output only. The time when the instance was created.
customPerformanceSupported	boolean	Output only. Indicates whether this instance supports configuring its performance. If true, the user can configure the instance's performance by using the 'performance_config' field.
deletionProtectionEnabled	boolean	Optional. Indicates whether the instance is protected against deletion.
deletionProtectionReason	string	Optional. The reason for enabling deletion protection.
description	string	The description of the instance (2048 characters or less).
directoryServices	object	Optional. Directory Services configuration for Kerberos-based authentication. Should only be set if protocol is "NFS_V4_1". (id: DirectoryServicesConfig)
etag	string	Server-specified ETag for the instance resource to prevent simultaneous updates from overwriting each other.
fileShares	array	File system shares on the instance. For this version, only a single file share is supported.
kmsKeyName	string	KMS key name used for data encryption.
labels	object	Resource labels to represent user provided metadata.
maxCapacityGb	string (int64)	Output only. The maximum capacity of the instance in GB.
minCapacityGb	string (int64)	Output only. The minimum capacity of the instance in GB.
networks	array	VPC networks to which the instance is connected. For this version, only a single network is supported.
performanceConfig	object	Optional. Used to configure performance. (id: PerformanceConfig)
performanceLimits	object	Output only. Used for getting performance limits. (id: PerformanceLimits)
protocol	string	Immutable. The protocol indicates the access protocol for all shares in the instance. This field is immutable and it cannot be changed after the instance has been created. Default value: NFS_V3. (FILE_PROTOCOL_UNSPECIFIED, NFS_V3, NFS_V4_1)
replication	object	Optional. Replication configuration. (id: Replication)
satisfiesPzi	boolean	Output only. Reserved for future use.
satisfiesPzs	boolean	Output only. Reserved for future use.
state	string	Output only. The instance state. (STATE_UNSPECIFIED, CREATING, READY, REPAIRING, DELETING, ERROR, RESTORING, SUSPENDED, SUSPENDING, RESUMING, REVERTING, PROMOTING)
statusMessage	string	Output only. Additional information about the instance state, if available.
suspensionReasons	array	Output only. Field indicates all the reasons the instance is in "SUSPENDED" state.
tags	object	Optional. Input only. Immutable. Tag key-value pairs bound to this resource. Each key must be a namespaced name and each value a short name. Example: "123456789012/environment" : "production", "123456789013/costCenter" : "marketing" See the documentation for more information: - Namespaced name: https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing#retrieving_tag_key - Short name: https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing#retrieving_tag_value
tier	string	The service tier of the instance. (TIER_UNSPECIFIED, STANDARD, PREMIUM, BASIC_HDD, BASIC_SSD, HIGH_SCALE_SSD, ENTERPRISE, ZONAL, REGIONAL)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, instancesId		Gets the details of a specific instance.
list	select	projectsId, locationsId	orderBy, filter, pageSize, pageToken	Lists all instances in a project for either a specified location or for all locations.
create	insert	projectsId, locationsId	instanceId	Creates an instance. When creating from a backup, the capacity of the new instance needs to be equal to or larger than the capacity of the backup (and also equal to or larger than the minimum capacity of the tier).
patch	update	projectsId, locationsId, instancesId	updateMask	Updates the settings of a specific instance.
delete	delete	projectsId, locationsId, instancesId	force	Deletes an instance.
revert	exec	projectsId, locationsId, instancesId		Revert an existing instance's file system to a specified snapshot.
pause_replica	exec	projectsId, locationsId, instancesId		Pause the standby instance (replica). WARNING: This operation makes the standby instance's NFS filesystem writable. Any data written to the standby instance while paused will be lost when the replica is resumed or promoted.
resume_replica	exec	projectsId, locationsId, instancesId		Resume the standby instance (replica). WARNING: Any data written to the standby instance while paused will be lost when the replica is resumed.
promote_replica	exec	projectsId, locationsId, instancesId		Promote the standby instance (replica).
restore	exec	projectsId, locationsId, instancesId		Restores an existing instance's file share from a backup. The capacity of the instance needs to be equal to or larger than the capacity of the backup (and also equal to or larger than the minimum capacity of the tier).

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
force	boolean
instanceId	string
orderBy	string
pageSize	integer (int32)
pageToken	string
updateMask	string (google-fieldmask)

SELECT examples

get

Gets the details of a specific instance.

SELECT
name,
capacityStepSizeGb,
createTime,
customPerformanceSupported,
deletionProtectionEnabled,
deletionProtectionReason,
description,
directoryServices,
etag,
fileShares,
kmsKeyName,
labels,
maxCapacityGb,
minCapacityGb,
networks,
performanceConfig,
performanceLimits,
protocol,
replication,
satisfiesPzi,
satisfiesPzs,
state,
statusMessage,
suspensionReasons,
tags,
tier
FROM google.file.instances
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND instancesId = '{{ instancesId }}' -- required
;

list

Lists all instances in a project for either a specified location or for all locations.

SELECT
name,
capacityStepSizeGb,
createTime,
customPerformanceSupported,
deletionProtectionEnabled,
deletionProtectionReason,
description,
directoryServices,
etag,
fileShares,
kmsKeyName,
labels,
maxCapacityGb,
minCapacityGb,
networks,
performanceConfig,
performanceLimits,
protocol,
replication,
satisfiesPzi,
satisfiesPzs,
state,
statusMessage,
suspensionReasons,
tags,
tier
FROM google.file.instances
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND orderBy = '{{ orderBy }}'
AND filter = '{{ filter }}'
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
;

INSERT examples

create

Creates an instance. When creating from a backup, the capacity of the new instance needs to be equal to or larger than the capacity of the backup (and also equal to or larger than the minimum capacity of the tier).

INSERT INTO google.file.instances (
data__labels,
data__performanceConfig,
data__tags,
data__tier,
data__fileShares,
data__replication,
data__etag,
data__deletionProtectionEnabled,
data__protocol,
data__directoryServices,
data__description,
data__deletionProtectionReason,
data__kmsKeyName,
data__networks,
projectsId,
locationsId,
instanceId
)
SELECT 
'{{ labels }}',
'{{ performanceConfig }}',
'{{ tags }}',
'{{ tier }}',
'{{ fileShares }}',
'{{ replication }}',
'{{ etag }}',
{{ deletionProtectionEnabled }},
'{{ protocol }}',
'{{ directoryServices }}',
'{{ description }}',
'{{ deletionProtectionReason }}',
'{{ kmsKeyName }}',
'{{ networks }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ instanceId }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: instances
props:
  - name: projectsId
    value: "{{ projectsId }}"
    description: Required parameter for the instances resource.
  - name: locationsId
    value: "{{ locationsId }}"
    description: Required parameter for the instances resource.
  - name: labels
    value: "{{ labels }}"
    description: |
      Resource labels to represent user provided metadata.
  - name: performanceConfig
    description: |
      Optional. Used to configure performance.
    value:
      fixedIops:
        maxIops: "{{ maxIops }}"
      iopsPerTb:
        maxIopsPerTb: "{{ maxIopsPerTb }}"
  - name: tags
    value: "{{ tags }}"
    description: |
      Optional. Input only. Immutable. Tag key-value pairs bound to this resource. Each key must be a namespaced name and each value a short name. Example: "123456789012/environment" : "production", "123456789013/costCenter" : "marketing" See the documentation for more information: - Namespaced name: https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing#retrieving_tag_key - Short name: https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing#retrieving_tag_value
  - name: tier
    value: "{{ tier }}"
    description: |
      The service tier of the instance.
    valid_values: ['TIER_UNSPECIFIED', 'STANDARD', 'PREMIUM', 'BASIC_HDD', 'BASIC_SSD', 'HIGH_SCALE_SSD', 'ENTERPRISE', 'ZONAL', 'REGIONAL']
  - name: fileShares
    description: |
      File system shares on the instance. For this version, only a single file share is supported.
    value:
      - capacityGb: "{{ capacityGb }}"
        sourceBackup: "{{ sourceBackup }}"
        nfsExportOptions: "{{ nfsExportOptions }}"
        name: "{{ name }}"
        sourceBackupdrBackup: "{{ sourceBackupdrBackup }}"
  - name: replication
    description: |
      Optional. Replication configuration.
    value:
      role: "{{ role }}"
      replicas:
        - stateReasons: "{{ stateReasons }}"
          lastActiveSyncTime: "{{ lastActiveSyncTime }}"
          state: "{{ state }}"
          peerInstance: "{{ peerInstance }}"
          stateUpdateTime: "{{ stateUpdateTime }}"
  - name: etag
    value: "{{ etag }}"
    description: |
      Server-specified ETag for the instance resource to prevent simultaneous updates from overwriting each other.
  - name: deletionProtectionEnabled
    value: {{ deletionProtectionEnabled }}
    description: |
      Optional. Indicates whether the instance is protected against deletion.
  - name: protocol
    value: "{{ protocol }}"
    description: |
      Immutable. The protocol indicates the access protocol for all shares in the instance. This field is immutable and it cannot be changed after the instance has been created. Default value: `NFS_V3`.
    valid_values: ['FILE_PROTOCOL_UNSPECIFIED', 'NFS_V3', 'NFS_V4_1']
  - name: directoryServices
    description: |
      Optional. Directory Services configuration for Kerberos-based authentication. Should only be set if protocol is "NFS_V4_1".
    value:
      ldap:
        servers:
          - "{{ servers }}"
        usersOu: "{{ usersOu }}"
        domain: "{{ domain }}"
        groupsOu: "{{ groupsOu }}"
  - name: description
    value: "{{ description }}"
    description: |
      The description of the instance (2048 characters or less).
  - name: deletionProtectionReason
    value: "{{ deletionProtectionReason }}"
    description: |
      Optional. The reason for enabling deletion protection.
  - name: kmsKeyName
    value: "{{ kmsKeyName }}"
    description: |
      KMS key name used for data encryption.
  - name: networks
    description: |
      VPC networks to which the instance is connected. For this version, only a single network is supported.
    value:
      - reservedIpRange: "{{ reservedIpRange }}"
        network: "{{ network }}"
        modes: "{{ modes }}"
        ipAddresses: "{{ ipAddresses }}"
        pscConfig:
          endpointProject: "{{ endpointProject }}"
        connectMode: "{{ connectMode }}"
  - name: instanceId
    value: "{{ instanceId }}"

UPDATE examples

patch

Updates the settings of a specific instance.

UPDATE google.file.instances
SET 
data__labels = '{{ labels }}',
data__performanceConfig = '{{ performanceConfig }}',
data__tags = '{{ tags }}',
data__tier = '{{ tier }}',
data__fileShares = '{{ fileShares }}',
data__replication = '{{ replication }}',
data__etag = '{{ etag }}',
data__deletionProtectionEnabled = {{ deletionProtectionEnabled }},
data__protocol = '{{ protocol }}',
data__directoryServices = '{{ directoryServices }}',
data__description = '{{ description }}',
data__deletionProtectionReason = '{{ deletionProtectionReason }}',
data__kmsKeyName = '{{ kmsKeyName }}',
data__networks = '{{ networks }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND instancesId = '{{ instancesId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
done,
error,
metadata,
response;

DELETE examples

delete

Deletes an instance.

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

Lifecycle Methods

revert

Revert an existing instance's file system to a specified snapshot.

EXEC google.file.instances.revert 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"targetSnapshotId": "{{ targetSnapshotId }}"
}'
;

pause_replica

Pause the standby instance (replica). WARNING: This operation makes the standby instance's NFS filesystem writable. Any data written to the standby instance while paused will be lost when the replica is resumed or promoted.

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

resume_replica

Resume the standby instance (replica). WARNING: Any data written to the standby instance while paused will be lost when the replica is resumed.

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

promote_replica

Promote the standby instance (replica).

EXEC google.file.instances.promote_replica 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@instancesId='{{ instancesId }}' --required 
@@json=
'{
"peerInstance": "{{ peerInstance }}"
}'
;

restore

Restores an existing instance's file share from a backup. The capacity of the instance needs to be equal to or larger than the capacity of the backup (and also equal to or larger than the minimum capacity of the tier).

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