Skip to main content
The Network Storage service enables a new kind of mount that refers to a shared service rather than to a local directory. This service allows you to store data and share it between different apps.
Writing to network mounts is slightly slower than to local mounts, most noticeably during high-volume sequential file creation — in that case, a local mount is more effective. Applications polling network mounts for a new file may not immediately detect it even though it exists.Detection can be delayed by approximately 30 seconds, so polling logic should account for this delay and not treat a missing file as an error until that window has passed.

​
Supported versions

You can select the major and minor version. Patch versions are applied periodically for bug fixes and other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a maintenance window configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window.
  • 1.0
This service is the Upsun Cloud network storage implementation, not the version of a third-party application.
It isn’t possible to upgrade or downgrade the network storage service version while keeping existing data in place. Changing the service version requires that the service be reinitialized. Any change to the service version results in existing data becoming inaccessible.

​
Deprecated versions

The following versions are still available in your projects, but they’re at their end of life and are no longer receiving security updates from upstream.
  • 2.0
To ensure your project remains stable in the future,switch to a supported version.

​
Retired versions

The following versions have been retired and are no longer available. If your project uses a retired version, you must update to a supported version. No retired versions.

​
Usage example

​
1. Configure the service

To define the service, use the network-storage type: SERVICE_NAME must be RFC 1123 compliant, since it’s used as the network storage’s hostname:
  • At most 63 characters
  • Lowercase alphanumeric characters or - only (no underscores)
  • Starts and ends with an alphanumeric character
Name the service for what it stores, for example, shared-uploads.
Changing the name of an existing service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

​
2. Add the mount

To define the mount accessible by your application, use the following configuration:
  • <TARGET_PATH> is the path to your mount within the app container (relative to the app’s root).
  • SERVICE_NAME is the name you defined in step 1.
  • <SOURCE_PATH> specifies where the mount points inside the service.
    If the source_path is an empty string (""), your mount points to the entire service.
    If you don’t define a source_path, Upsun Cloud uses the MOUNT_PATH as default value, without leading or trailing slashes. For example, if your mount lives in the /my/files/ directory within your app container, it will point to a my/files directory within the service.

​
Example configuration

​
Multi-application usage

If your project contains multiple apps, they may share storage mounts. Alternatively, they may use shared service mounts. If the source_path is the same for both apps, the files are shared between the two applications even if the mount location is different. It’s also possible to have one app mount a source_path that’s a subdirectory of another application’s mount. For example:
.upsun/config.yaml
In this example, app1 has access to the entire uploads directory by writing to web/uploads. app2 has two mounts that it can write to: process and done. The process mount refers to the same directory as the web/uploads/incoming directory does on app1, and the done mount refers to the same directory as the web/uploads/done directory on app1.

​
How do I give my workers access to my main application’s files?

If you need to use a worker with access to the same file mount as your web-serving app, define all the necessary mounts as service mounts. The following example assumes a Network Storage service named files has been defined in .upsun/config.yaml. Drupal files directories are shared between the web and worker instances, while the Drush backup directory is unique to the web instance.

​
How can I migrate data from a storage mount to a service mount?

Network Storage service mounts can be shared between different apps, while storage mounts can only be shared between different instances of the same app. To move data from a storage mount to a service one, follow these instructions. Assuming you have the following storage mount:
.upsun/config.yaml
  1. Add a new network-storage service to your configuration, naming it shared-uploads:
Make sure you allocate enough disk space to your shared-uploads service for your existing files with some buffer.
  1. Add a new service mount, named new-uploads:
Note that each mount is on a different storage service, which is why they can have the same source_path.
  1. Deploy your changes.
  2. Copy all your files from the storage (web/uploads) mount to the service (new-uploads) mount using rsync:
  3. Reverse the mounts. To do so, rename the storage mount to old-uploads, and point the web/uploads directory to the service mount:
  1. Push your changes and check that the files are now accessible from the service mount (now named web/uploads). To check that no files were lost during the transfer, run the following command:
  2. Delete the contents of the old-uploads storage mount before removing it.
  3. Push your changes again.
Last modified on September 29, 2026