This page shows you how to create a Filestore instance by using either the Google Cloud console or the gcloud CLI.
Instructions for creating an instance
Google Cloud console
Before you begin
The quota for a zonal (10 TiB to 100 TiB) or regional (10 TiB to 100 TiB) instance starts at
0
. To use these tiers, you must first create and receive approval for a quota increase request before you can create an instance.If you need to create an instance using a legacy service tier, such as enterprise or high scale SSD, you must run your operations directly through the Filestore API or by using
gcloud
. Thesecreate
operations are not supported through the Google Cloud console.For more information, see Service tiers.
Google Cloud instructions
In the Google Cloud console, go to the Filestore instances page.
Click Create Instance
Enter all required fields and optional fields as needed based on the instructions in the following sections of this page.
Click Create.
gcloud
Before you begin
To use the gcloud CLI, you must either install the gcloud CLI or use the Cloud Shell that's built into the Google Cloud console:
Go to the Google Cloud console
gcloud
command for creating a Filestore instance
You can create a Filestore instance by running the filestore
instances create
command.
Quota for instances varies by project, region, and tier. For more information,
see Quotas or Request a quota increase.
gcloud filestore instances create INSTANCE_ID \
[--project=PROJECT_ID] \
[--location=LOCATION] \
[--description=DESCRIPTION] \
--tier=TIER \
--file-share=name="FILE_SHARE_NAME",capacity=FILE_SHARE_SIZE \
--network=name="VPC-NETWORK",[connect-mode=CONNECT_MODE],[reserved-ip-range="RESERVED_IP_ADDRESS"] \
[--labels=KEY=VALUE,[KEY=VALUE,…]] \
[--kms-key=KMS_KEY] \
[--deletion-protection] \
[--deletion-protection-reason="PROTECTION_REASON"]
Replace the following:
- INSTANCE_ID with the instance ID of the Filestore instance that you want to create. See Name your instance.
PROJECT_ID with the project ID of the Google Cloud project that contains the Filestore instance. You can skip this flag if the Filestore instance is in the
gcloud
default project. You can set the default project by running theconfig set project
command:gcloud config set project PROJECT_ID
LOCATION with the location where you want the Filestore instance to reside. See Select a location. You can skip this flag if the Filestore instance is in the
gcloud
default location. You can set the default location by running theconfig set filestore/zone
command:gcloud config set filestore/zone zone
For the regional or enterprise tier, use the
config set filestore/region
command:gcloud config set filestore/region region
DESCRIPTION A description of the Filestore instance.
TIER with the service tier you want to use.
FILE_SHARE_NAME with the name you specify for the NFS file share that is served from the instance. See Name the file share.
FILE_SHARE_SIZE with the size you want for the file share. See Allocate capacity.
VPC-NETWORK with the name of the VPC network you want the instance to use. See Select the VPC network. If you want to specify a Shared VPC from a service project, you must specify the fully qualified network name, which is in the format
projects/HOST_PROJECT_ID/global/networks/SHARED_VPC_NAME
and you must specifyconnect-mode=PRIVATE_SERVICE_ACCESS
. For example:--network=name=projects/host/global/networks/shared-vpc-1,connect-mode=PRIVATE_SERVICE_ACCESS
You can't specify a legacy network for the VPC-NETWORK value. If necessary, create a new VPC network to use by following the instructions at Creating a new auto mode VPC network.
CONNECT_MODE with
DIRECT_PEERING
orPRIVATE_SERVICE_ACCESS
. If you are specifying a Shared VPC as the network, you must also specifyPRIVATE_SERVICE_ACCESS
as the connect mode.RESERVED_IP_ADDRESS with the IP address range for the Filestore instance. If you are specifying
connect-mode=PRIVATE_SERVICE_ACCESS
, and want to use a reserved IP address range, you must specify the name of an allocated address range instead of a CIDR range. See Configure a reserved IP address. We recommend that you skip this flag to allow Filestore to automatically find a free IP address range and assign it to the instance.KEY with a label that you want to add. Adding labels is not required when creating a Filestore instance. You can also add, delete, or update labels after you create an instance. For details, see Managing labels.
VALUE with the value for a label.
KMS_KEY is the fully qualified name of the Cloud KMS encryption key that you want to use when you want to manage your own data encryption. The format looks like:
projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY
PROTECTION_REASON if you choose to use the
--deletion-protection
flag, you have the option of adding a note regarding the setting. To add the note, use the optional--deletion-protection-reason
flag and include a description of the justification for the setting you chose. For example, "All genomics data must adhere to current organization policies." For more information, see Deletion protection.
Example
The following command creates an instance with the following characteristics:
- ID is
render1
. - Project is
myproject
. - Zone is
us-central1-c
. - Tier is
BASIC_HDD
. - File share name is
my_vol
. - File share size is 2 TiB.
- VPC network is
default
. - Reserved IP address range is
10.0.7.0/29
. - Grants read and write access with root squashed to the client with IP
address
10.0.2.0
. - Deletion protection is enabled.
- A justification for the deletion protection setting is provided.
gcloud filestore instances create render1 \
--project=myproject \
--zone=us-central1-c \
--tier=BASIC_HDD \
--network=name="default",reserved-ip-range="10.0.7.0/29" \
--flags-file=nfs-export-options.json \
--deletion-protection \
--deletion-protection-reason="All genomics data must adhere to current
organization policies."
nfs-export-options.json
file contents:
{
"--file-share":
{
"capacity": "2048",
"name": "my_vol",
"nfs-export-options": [
{
"access-mode": "READ_WRITE",
"ip-ranges": [
"10.0.0.0/29",
"10.2.0.0/29"
],
"squash-mode": "ROOT_SQUASH",
"anon_uid": 1003,
"anon_gid": 1003
},
{
"access-mode": "READ_ONLY",
"ip-ranges": [
"192.168.0.0/26"
],
"squash-mode": "NO_ROOT_SQUASH"
}
]
}
}
REST API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the Filestore API:curl --request POST \ 'https://file.googleapis.com/v1/projects/PROJECT/locations/LOCATION/instances?instanceId=NAME' \ --header "Authorization: Bearer $(gcloud auth print-access-token)" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{"tier":"TIER","networks":[{"network":"NETWORK"}],"fileShares":[{"capacityGb":CAPACITY,"name":"SHARE_NAME"}], "deletionProtectionEnabled": true, "deletionProtectionReason": "PROTECTION_REASON"}' \ --compressed
Where:
PROJECT
is the name of the project where your instance will reside. For example,my-genomics-project
.LOCATION
is the location where the instance will reside. For example,us-east1
orus-central1-a
.NAME
is the name of the instance you want to create. For example,my-genomics-instance
.TIER
is the name of the service tier you want to use. For example,REGIONAL
.NETWORK
is the name of the network you want to use. For example,default
.CAPACITY
is the size, in GiB, you want to allocate for the instance. For example,1024
.SHARE_NAME
is the name of the file share. For example,vol1
.PROTECTION_REASON
if you choose to use thedeletionProtectionEnabled
flag, you have the option of adding a note regarding the setting. To add the note, use the optionaldeletionProtectionReason
flag and include a description of the justification for the setting you chose. For example, "All genomics data must adhere to current organization policies." For more information, see Deletion protection.
Understand instances and shares
A Filestore instance represents physical storage capacity.
A share represents an allocated portion of that storage with an individual, unique access point.
All service tiers offer storage options with a 1:1 share–to–instance ratio. Alternatively, Filestore multishares for GKE, available for enterprise-tier instances only, offers access to multiple shares on a single instance.
Instance names, or instance IDs, are used by administrators to manage instances. File share names are used by clients to connect to the shares exported from those instances.
Name your instance
The name of your Filestore instance, or instance ID, is used to
identify the instance and is used in gcloud
commands. Instance IDs must comply
with the <label>
element of
RFC 1035.
Specifically, they must:
- Be between 1-63 characters long.
- Begin with a lowercase letter.
- Consist of dashes, lowercase letters, or digits.
- End with lowercase letters or digits.
The instance ID must be unique in the Google Cloud project and zone where it's located. Once an instance is created, its instance ID cannot be changed.
Select a service tier
Select the service tier that best suits your needs. Once an instance is created, its service tier cannot be changed. The following table summarizes capabilities available by service tier:
Capability | Basic HDD & Basic SSD |
Zonal | Regional | Enterprise |
---|---|---|---|---|
Capacity | 1 TiB to 63.9 TiB | 1 TiB to 100 TiB | 1 TiB to 100 TiB | 1 TiB to 10 TiB |
Scalability |
|
|
|
Scales up or down in increments of 256 GiB |
Performance |
|
Scales linearly with capacity, within the limits of the chosen capacity range |
Scales linearly with capacity, within the limits of the chosen capacity range |
Scales linearly with capacity |
Protocol | NFSv3 | NFSv3, NFSv4.1 | NFSv3, NFSv4.1 | NFSv3, NFSv4.1 |
Create
operations for zonal, regional,
and enterprise instances can take anywhere between 15 minutes and
one hour to complete, depending on instance size.
Filestore quota is consumed when instance creation starts but you are not billed for the instance during this time.
Performance
The following table provides a more detailed comparison of performance across service tiers:
Specification | Basic HDD | Basic SSD | Zonal | Regional | Enterprise |
---|---|---|---|---|---|
Read IOPS |
|
60,000 |
|
|
1 TiB to 10 TiB capacity: 12,000-120,000 |
Write IOPS |
|
25,000 |
|
|
1 TiB to 10 TiB capacity: 4,000-40,000 |
Read Throughput (MB/s) |
|
1,200 |
|
|
1 TiB to 10 TiB capacity: 120-1,200 |
Write Throughput (MB/s) |
|
350 |
|
|
1 TiB to 10 TiB capacity: 100-1,000 |
For more information about performance, see Performance.
For a more detailed description of capabilities available by service tier, see Service tiers.
Allocate capacity
Allocate capacity to the amount you need when you create the instance. As you approach your capacity limit, you can scale up the capacity as needed without affecting runtime. To learn about how you can monitor the capacity of your instances, see Monitoring instances.
In the gcloud CLI, you can specify the capacity in whole numbers
using either GiB
or TiB
. The default unit is GiB
.
The following table shows the instance sizes available for each tier:
Tier | Minimum size | Maximum size | Incremental step size |
---|---|---|---|
Basic HDD | 1 TiB | 63.9 TiB | 1 GiB |
Basic SSD | 2.5 TiB | 63.9 TiB | 1 GiB |
Zonal | 1 TiB | 9.75 TiB | 256 GiB |
Zonal | 10 TiB | 100 TiB | 2.5 TiB |
Regional | 1 TiB | 9.75 TiB | 256 GiB |
Regional | 10 TiB | 100 TiB | 2.5 TiB |
Enterprise | 1 TiB | 10 TiB | 256 GiB |
The size of instances can be any whole gibibyte value or its tebibyte equivalent that's between the minimum and maximum instance size and is divisible by its incremental step size. For example, valid sizes for zonal-tier instances with a higher capacity range include 10 TiB, 12.5 TiB, and 15 TiB.
Once created, basic-tier instances can only scale up in size. All other service tiers can scale up or down in capacity. For more information, see Edit instances and Scale capacity.
Total capacity quota
Every project is allocated a separate capacity quota, defined by region and service tier. Quota limits vary by service tier.
Once you have reached your quota limit, you won't be able to create more Filestore instances or increase the capacity of your existing instances. To see your available quota, go to the Quotas page in the Google Cloud console:
For information on requesting more quota, see Requesting quota increases.
Name the file share
A file share is the directory on a Filestore instance where all shared files are stored. It is also the thing that you mount or map to on the client VM.
The name of the file share must comply with the following:
- Be between 1-32 characters long for zonal, regional, and enterprise tiers, and 1-16 characters long for basic tiers.
- Begin with a letter.
- Consist of uppercase or lowercase letters, numbers, and underscores.
- End with a letter or number.
Select the VPC network
The network that you select to use with Filestore can be either a standard VPC network or a Shared VPC network. In both cases, the network that you choose must have enough available IP resources to dedicate to the Filestore instance, otherwise the instance fails to create.
Clients must be on the same network as the Filestore instance to access the files stored on that instance. Once an instance is created, this network selection cannot be changed.
Shared VPC network
Before you can create an instance on a Shared VPC network in a service project, the network administrator must first enable private services access for the Shared VPC network. If you are creating the instance in the host project, private services access is not required.
Shared VPC networks are displayed in the Google Cloud console in the format:
projects/HOST_PROJECT_ID/global/networks/SHARED_VPC_NAME
For detailed procedures, see Creating an instance on a Shared VPC network.
NFS file locking
If the applications you plan to use with this Filestore instance require NFS file locking, and you are choosing either of the following, you may need to open up the ports used by Filestore in the network you choose:
- A VPC network other than the default network.
- The default VPC network with changed firewall rules.
For more information, see Configuring firewall rules.
Select a location
Location refers to the Region and Zone where the Filestore instance is located. For the best performance and to avoid cross-regional networking charges, ensure that the Filestore instance is located in the same region as the Compute Engine VMs that need to access them.
For more information about regions and zones, see Geography and regions.
Configure IP-based access control
By default, a Filestore instance grants root level read and write access to all clients, including Compute Engine VMs and GKE clusters, that share the same Google Cloud project and VPC network. If you want to restrict access, you can do so by creating rules that grant specific access levels to clients based on their IP address. Once the rules are added, all IP addresses and ranges that are not specified in a rule are revoked access. Zonal, regional, and enterprise instances support configuration settings for overlapping IP address ranges. For more information, see Overlapping permissions.
The following table describes the privileges of each access level. These access levels are only used in the Google Cloud console. In the gcloud CLI and the API, you must specify the rule configurations directly.
Access level | Rule configuration | Description |
---|---|---|
admin |
|
The client can view and modify all files, folders, and metadata as a root user. It can also grant ownership to files or folders by setting its uid and gid , and in doing so, grant access to clients that don't have root level access to the file share. |
admin-viewer |
|
The client can view all files, folders, and metadata as a root user but cannot modify them. |
editor |
|
The client can view and modify the files, folders, and metadata according to its assigned uid and gid . |
viewer |
|
The client can view the files, folders, and metadata according to its assigned uid and gid . |
root-squash
maps all requests from uid 0
and gid 0
to anon_uid
and
anon_gid
, respectively. This configuration removes root level access from
clients that attempt to access the file share as a root user.
When creating IP-based access rules:
- You must specify an internal IP address or range and the access level granted.
- At least one rule must grant
admin
access at the time of instance creation. This rule can be removed once the instance is created. - Zonal, regional, and enterprise instances support configuration settings for overlapping IP address ranges. Basic-tier instances are not supported. For more information, see Overlapping permissions.
In the Google Cloud console, you can create up to 4 different rules (admin
,
admin-viewer
, editor
, viewer
) involving up to 64 different IP addresses or
ranges.
In the gcloud CLI, you can configure up to 64 different IP addresses
or CIDR blocks per Filestore instance across a maximum of 10
different rules. A rule is defined as the combination of the access-mode
,
squash-mode
, and anon_uid
/anon_gid
configurations. The anon_uid
and
anon_gid
fields have default values of 65534
and can only be configured
through the API and the gcloud CLI.
Example
Here's an example of three different IP-based access rules:
access-mode=READ_ONLY
,squash-mode=ROOT_SQUASH
,anon_uid=10000
.access-mode=READ_WRITE
,squash-mode=ROOT_SQUASH
,anon_gid=150
.access-mode=READ_WRITE
,squash-mode=NO_ROOT_SQUASH
.
To create IP-based access control rules using the gcloud CLI, use the
--flags-file
flag with the
instances create
or
instances update
commands
and point it to a JSON configuration file. For example, if the JSON
configuration file is named nfs-export-options.json
, the flag would be:
--flags-file=nfs-export-options.json
Example JSON configuration file:
{
"--file-share":
{
"capacity": "2048",
"name": "my_vol",
"nfs-export-options": [
{
"access-mode": "READ_WRITE",
"ip-ranges": [
"10.0.0.0/29",
"10.2.0.0/29"
],
"squash-mode": "ROOT_SQUASH",
"anon_uid": 1003,
"anon_gid": 1003
},
{
"access-mode": "READ_ONLY",
"ip-ranges": [
"192.168.0.0/26"
],
"squash-mode": "NO_ROOT_SQUASH"
}
]
}
}
- ip-ranges is the IP address or range to grant access to. You can specify multiple IP addresses or ranges by separating them with a comma. Only zonal, regional, and enterprise instances support configuration settings for overlapping IP address ranges. For more information, see Overlapping permissions.
- access-mode is the access level to grant to the clients whose
IP address falls within ip-range. It can have the values of
READ_WRITE
orREAD_ONLY
. The default value isREAD_WRITE
. - squash-mode can have the values
ROOT_SQUASH
orNO_ROOT_SQUASH
.ROOT_SQUASH
removes root level access to the clients whose IP address falls within ip-range, whileNO_ROOT_SQUASH
enables root access. The default value isNO_ROOT_SQUASH
. - anon_uid is the user ID value that you want to map to
anon_uid
. The default value is65534
. - anon_gid is the group ID value that you want to map to
anon_gid
. The default value is65534
.
Clients on non-RFC 1918 ranges
If you plan to connect non-RFC 1918 clients to your Filestore instance, you must explicitly grant them access to the Filestore instance using IP-based access control.
Optional fields
The following sections describe optional fields.
Add an instance description
An instance description lets you write descriptions, notes, or instructions for yourself and other users. For example, you can include information about:
- The types of files stored in the instance.
- Who has access to the instance.
- Instructions for how to get access to the instance.
- What the instance is used for.
Instance descriptions are limited to 2048 characters in length. There are no restrictions on the characters that are allowed. Once a Filestore instance is created, you can update its instance description anytime as needed. For information on updating instance descriptions, see Editing instances.
Add labels
Labels are key-value pairs that you can use to group related instances and store metadata about an instance. You can add, delete, or modify labels anytime. For more information, see Managing labels.
Configure a reserved IP address range
Each Filestore instance must have an IP address range associated with it. Both RFC 1918 and non-RFC 1918 IP address ranges (GA) are supported.
Once specified, an instance's IP address range is immutable.
Users are encouraged to let Filestore automatically determine a free IP address range and assign it to the instance. When selecting your own range, consider the following Filestore IP resource requirements:
Must use CIDR notation.
Must be a valid VPC subnet range.
Basic instances require a block size of 29. For example,
10.123.123.0/29
.Zonal, regional, and enterprise instances require a block size of 26. For example,
172.16.123.0/26
.The IP address range must not overlap with the following:
Existing subnets in the VPC network that the Filestore instance uses.
Existing subnets in a VPC network that's peered with the one that the Filestore instance uses. For details, see Overlapping subnets at time of peering.
IP address ranges assigned to any other existing Filestore instances in that network.
The
172.17.0.0/16
address range is reserved for internal Filestore components. As a result, the following limitations apply:Clients in this range can't be connected to Filestore instances.
Filestore instances can't be created within this IP range. For more information, see Known issues.
There must be at least one VPC Network Peering or private services access connections per VPC.
You can see the IP address ranges for the subnets of your network by going to the VPC networks page in the Google Cloud console:
You can get the reserved IP address range for any Filestore instance on the Filestore instances page in the Google Cloud console:
Go to the Filestore instances page
If you want to use private services access and specify a reserved IP address range, you must specify the name of an allocated address range for the connection. If you don't specify a range name, Filestore automatically uses any of the allocated ranges associated with the private services access connection.
Use a customer-managed encryption key
By default, Google Cloud automatically encrypts data when it is at rest using encryption keys managed by Google. If you need more control over the keys that protect your data, you can use customer-managed encryption keys (CMEK) for Filestore. For details, see Encrypt data with customer-managed encryption keys.
Enable deletion protection
Set the instance's deletion protection setting. By default, this setting is disabled. For more information, see Deletion protection.
Add a deletion protection setting description
Add a description of the justification behind the deletion protection setting you chose. For more information, see Deletion protection.
What's next
- Learn how to configure an instance for use with the NFSv4.1 protocol.
- Learn how to connect instances to clients:
- Mount the Filestore file share on a Compute Engine VM instance.
- Access Filestore instances with the Filestore CSI driver.
- Use Filestore instances as external datastores for VMware ESXi hosts in VMware Engine.
- Mount file shares on remote clients.
- Mount a Filestore instance to a Cloud Run service to share data between containers and services.
- See how to retrieve instance details, such as the instance's IP address, so that you can access the Filestore file share from clients.
- Troubleshoot instance creation issues related to Filestore.
- Learn more about Virtual Private Cloud (VPC) networks and subnets.
- Learn more about networking and IP resource requirements for Filestore.