> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Filesystem
Filesystem is shared persistent NFS storage that can be mounted by multiple instances and clusters simultaneously. It is region-bound and attaches to a single VPC. Use it when you need shared, persistent storage accessible from more than one compute resource. You can also define snapshot policies to create recurring point-in-time snapshots and retain a defined number of them.
**Prerequisites:** You need a [VPC network](/docs/network/vpc-networks) and at least one [instance](/docs/compute/create-new-instances) or [cluster](/docs/compute/managed-kubernetes) in the same VPC before you can use the filesystem.
## Summary
This page explains how to create and use **Filesystem** storage in the nscale console.
By following the steps, you will:
* Create a **project-scoped**, **region-bound** shared filesystem
* Attach the filesystem to a **single network** so multiple instances/clusters in that network can share it
* Define **snapshot policies** to automate point-in-time filesystem snapshots
* Retrieve the **NFS mount command** and use it to mount the filesystem from your compute resources
**Who should use this:** console users who need shared, persistent storage that can be mounted by more than one instance or cluster (within the same network).
## Availability
This feature is currently only available for the reserved cloud service environment.
**Subnet sizing requirement:** Your VPC must have at least a **/24 CIDR block** (256 IP addresses). Make sure your subnet is sized appropriately before creating a filesystem.
**Single network attachment:** Each filesystem can only be attached to **one VPC at a time**. Plan your network layout accordingly. To move a filesystem to a different VPC, you must detach it first.
## Requirements
* Permissions to **create and manage storage resources** in the console
* A target **region** selected for the storage resource (Filesystem is region-bound)
* A **network** to attach the storage to (Filesystem attaches to a single network)
* At least one **instance or cluster** in the same network where you will mount the filesystem
If **no VPC** is selected, the **mount command** is **not** provided. You must select a VPC to get the mount command.
## Filesystem lifecycle
| Action | Details |
| ------------------- | ----------------------------------------------------------------------- |
| **Create** | Provide a name, capacity, and select the VPC to attach to |
| **Resize** | Increase the filesystem capacity at any time from the console |
| **Snapshot policy** | Configure recurring filesystem snapshots and retention |
| **Mount** | Use the NFS mount command from any instance/cluster in the attached VPC |
| **Detach** | Detach the filesystem from its current VPC before moving it to another |
| **Delete** | Permanently remove the filesystem and all data stored on it |
**Deleting a filesystem permanently removes all data and associated snapshots.** This action cannot be undone. Ensure you have backups or have migrated data before deleting.
## Snapshot policies
Snapshot policies automate filesystem snapshots on a recurring schedule. Nscale enables **Default Snapshot Protection** by default, and you can add up to **4** snapshot policies with custom schedules and retention.
Default Snapshot Protection is platform-managed. It runs daily at `04:00Z`, keeps the last `7` snapshots, and is controlled separately from user-managed snapshot policies.
Use snapshot policies when you need recurring point-in-time protection for filesystem data. Deleting a filesystem is permanent and deletes its associated snapshots.
### Schedule options
All snapshot policy times are in UTC and use `HH:MMZ` format, for example `04:00Z`.
| Cadence | Required fields | Notes |
| ----------- | ---------------------------------------------- | ---------------------------------------------------- |
| **Hourly** | `interval: hourly` | Do not set `timeOfDay`, `dayOfWeek`, or `dayOfMonth` |
| **Daily** | `interval: daily`, `timeOfDay` | Runs once per day at the specified UTC time |
| **Weekly** | `interval: weekly`, `dayOfWeek`, `timeOfDay` | `dayOfWeek` must be `monday` through `sunday` |
| **Monthly** | `interval: monthly`, `dayOfMonth`, `timeOfDay` | `dayOfMonth` must be between `1` and `28` |
The retention value, `keep`, is the number of snapshots to retain and must be at least `1`.
When updating policies through the API, policy names are identity keys. Changing a policy name creates a new policy and removes the old one.
### API behavior
Default Snapshot Protection is managed with `spec.defaultSnapshotProtectionEnabled`. User-managed snapshot policies are managed inline on the filesystem resource as `spec.snapshotPolicies`.
| Operation | `defaultSnapshotProtectionEnabled` value | Result |
| ----------------- | ---------------------------------------- | ---------------------------------------------------------- |
| **Create** | Omitted | Enables Default Snapshot Protection |
| **Create** | `false` | Creates the filesystem without Default Snapshot Protection |
| **Update** | Omitted | Preserves the current Default Snapshot Protection setting |
| **Update** | `true` or `false` | Enables or disables Default Snapshot Protection |
| **Create/Update** | `null` | Invalid request |
| Operation | `snapshotPolicies` value | Result |
| ---------- | ------------------------ | ------------------------------------------------- |
| **Create** | Omitted or `[]` | Stores no user-managed snapshot policies |
| **Create** | Non-empty list | Stores the supplied user-managed policies exactly |
| **Update** | Omitted | Preserves existing user-managed policies |
| **Update** | `[]` | Clears all user-managed policies |
| **Update** | Non-empty list | Replaces the full user-managed policy list |
Public API reads return user-managed snapshot policies only. The platform-managed Default Snapshot Protection policy is not included in `spec.snapshotPolicies` or `status.snapshotPolicies`.
Omit `snapshotPolicies` when you do not want to change user-managed policies. Do not send `null`.
Do not use `system-default` as a user-managed policy name while Default Snapshot Protection is enabled. That name is reserved for Nscale's platform-managed default protection.
Example user-managed policy list:
```json theme={null}
{
"snapshotPolicies": [
{
"name": "daily",
"schedule": {
"interval": "daily",
"timeOfDay": "04:00Z"
},
"retention": {
"keep": 7
}
},
{
"name": "weekly",
"schedule": {
"interval": "weekly",
"dayOfWeek": "monday",
"timeOfDay": "02:30Z"
},
"retention": {
"keep": 4
}
}
]
}
```
## Step-by-step
1. **Choose the project and region**
* In the Console, select the **project** you want to use under **All Projects**
* Select the **region** where you want the filesystem to live
2. **Create (or select) the network you will attach storage to**
* Create a new network, or select an existing one in the same region
* Confirm the network is in the **same region** as the storage you plan to create
* **Important:** Filesystem supports **a single network attachment**. Plan accordingly if you have multiple networks
3. **Create the Filesystem**
* Go to **Storage → Filesystem** in the console
* Provide the required values (for example: name and capacity)
* Create the filesystem
* You should see the filesystem appear in the resource list, and its status move to a "ready/available" state
4. **Configure snapshot policies (optional)**
* Use the **Snapshot policies** section when creating or editing the filesystem
* Review Default Snapshot Protection, which is enabled by default
* Add user-managed policies if you need additional cadences, UTC schedules, or retention rules
* Save the filesystem and verify each user-managed policy reaches a ready/provisioned state
5. **Get the NFS mount command**
* In the filesystem details, locate the action or section to Mount your filesystem
* Copy the **NFS mount command**
* You should see a mount command that you can run from a Linux host in the attached network
6. **Mount from your compute (instance or cluster)**
* From a target instance (or nodes in your cluster) that are connected to the same network:
* Run the mount command you copied
* Confirm the mount worked by verifying the mount point is accessible and read/write as expected
## View filesystem details
Click any filesystem in the list to view its detail page. The detail page includes:
* **Overview** — filesystem status, capacity, attached VPC, and mount command
* **Instances** — all instances in the attached VPC that can access this filesystem, with search filtering
* **Snapshot policies** — schedules, retention, and provisioning state for each policy
The **Instances** tab helps you see at a glance which compute resources are using the filesystem.
## Quotas
To check your current filesystem quota, go to the **Resource Usage** section on the **Dashboard**. The dashboard shows your filesystem storage usage (e.g., 1 GiB / 1 TiB) alongside GPU, server, cluster, and network quotas.
## Common issues / troubleshooting
1. **Symptom:** You can't attach the filesystem to the selected network
**Likely cause:** The filesystem is already attached to a different network (single network attachment), or the network is in a different region.
**Fix:** Verify the filesystem's current attachment and region. If it's attached already, detach it first and re-attach to the intended network. Ensure network and filesystem are in the same region.
2. **Symptom:** The mount command fails from your instance/cluster
**Likely cause:** The instance/cluster is not in the attached network, or network access rules prevent NFS connectivity.
**Fix:** Confirm the compute resource is connected to the same network the filesystem is attached to. Then verify network/security rules permit NFS traffic (exact ports/rules depend on your setup).
3. **Symptom:** No mount command is shown in the filesystem details
**Likely cause:** No VPC has been selected for the filesystem.
**Fix:** Edit the filesystem and select a VPC. The mount command will appear once a VPC is attached.
4. **Symptom:** A snapshot policy is rejected or does not provision
**Likely cause:** The policy name, schedule, or retention does not match the validation rules. Common issues include using a non-UTC time, setting `timeOfDay` on an hourly policy, omitting `dayOfWeek` on a weekly policy, or using a monthly `dayOfMonth` after `28`.
**Fix:** Update the policy so the schedule fields match its cadence and `keep` is at least `1`.
5. **Symptom:** Existing snapshot policies changed after an API update
**Likely cause:** API updates replace the full `snapshotPolicies` list when a non-empty list is supplied, or clear all user-managed policies when `[]` is supplied.
**Fix:** Include every policy you want to keep in the update request. Omit `snapshotPolicies` if you only want to update other filesystem fields.
6. **Symptom:** A policy named `system-default` is rejected
**Likely cause:** Default Snapshot Protection is enabled or is still cleaning up, so `system-default` is reserved for the platform-managed policy.
**Fix:** Use a different policy name, or wait until Default Snapshot Protection has been disabled and cleanup has completed before claiming that name.
***
## Related resources
Create the network your filesystem attaches to
Mount the filesystem from your compute instances
Access shared storage from your Kubernetes clusters
Manage filesystems programmatically via the Networking and Storage API