Persistent Disks

You can attach a persistent disk to a paid Render web service, private service, or background worker. This enables you to preserve local filesystem changes across deploys and restarts.

By default, Render services have an ephemeral filesystem. Without a persistent disk, any changes you make to a service’s local files are lost every time the service redeploys or restarts.

Persistent disks are useful for services such as:

Persistent disks use the same high-performance SSDs as Render’s managed PostgreSQL and Redis. All disks are encrypted at rest, and so are their automatic daily snapshots.

Before you attach a persistent disk, it’s helpful to understand important limitations and considerations.

Setup

You create persistent disks from the Render Dashboard. You can do so during service creation (click Advanced at the bottom of the creation form), or any time after creation from your service’s Disks page:

Adding a persistent disk in the Render Dashboard

  1. Set your disks’s name.
    • This value is for informational purposes only.
  2. Set your disk’s mount path (such as /var/data).
    • Only filesystem changes under this path are preserved across deploys and restarts! The rest of your service’s filesystem remains ephemeral.
  3. Choose a disk size.
    • You can increase your disk’s size later, but you can’t decrease it. Pick the smallest value that currently works for your service.
  4. Save your changes.

After you save, Render triggers a new deploy for your service. The disk becomes available as soon as the deploy is live.

Monitoring usage

View your disk’s usage over time from your service’s Disks page in the Render Dashboard:

Disk usage shown in the Render Dashboard

Disk snapshots

Render automatically creates a snapshot of your persistent disk once every 24 hours. If your disk experiences critical data loss or corruption, you can completely restore its state to any available snapshot. Snapshots are available for at least seven days after they’re created.

Important:

  • If you restore a snapshot, all changes to your disk that occurred after the snapshot are lost.
  • Render doesn’t support restoring only a portion of a disk snapshot.
  • Do not restore a snapshot of a disk that’s used for a custom database instance. See details.

Restore a snapshot from your service’s Disks page in the Render Dashboard:

Restoring a disk snapshot in the Render Dashboard

Restoring a custom database

If you use a persistent disk specifically to back a custom database instance on Render (such as MySQL or MongoDB), do not perform a disk restore for database recovery purposes. If you do, your database might restore to a corrupted state.

Instead, create regular backups of your database using a tool like mysqldump for MySQL or mongodump for MongoDB. Restore your database’s state using one of these backups.

Transferring files

You can securely transfer files between your disk-backed service and your local machine using a tool like SCP or Magic-Wormhole.

SCP

After you set up SSH for your service, you can transfer files using SCP.

For example, if your ssh command looks like this:

ssh YOUR_SERVICE@ssh.YOUR_REGION.render.com

Then your scp commands look like this:

# Copying a file from your service to your local machine
scp -s YOUR_SERVICE@ssh.YOUR_REGION.render.com:/path/to/remote/file /destination/path/for/local/filefile        100% 5930KB 999.9KB/s   00:05

# Copying a file from your local machine to your service
scp -s /path/to/local/file YOUR_SERVICE@ssh.YOUR_REGION.render.com:/destination/path/for/remote/filefile        100% 5930KB 999.9KB/s   00:05

We recommend using SCP with the -s flag to use the more modern SFTP protocol. Future releases of SCP will default to using SFTP, and this flag will no longer be needed.

Magic-Wormhole

The Magic-Wormhole library enables you to transfer files to and from your disk-backed service without using SSH and SCP.

  1. In the Render Dashboard, go to your service’s Shell page.

  2. If you have a Docker-image-backed service, use the shell to install magic-wormhole:

    • Run apt update && apt install magic-wormhole or the equivalent for your environment.
    • The magic-wormhole library is pre-installed on all Render native runtimes.
  3. Use the shell to transfer your file with the wormhole command:

    wormhole send /path/to/filename.txtSending 10.5 MB file named 'filename.txt'
    Wormhole code is: 4-forever-regain
  4. Note the code that appears in the output from wormhole. Then, from any internet-connected machine, install magic-wormhole and run wormhole receive, entering in the code when prompted.

Disk limitations and considerations

When attaching a persistent disk to your service, note the following:

  • Only filesystem changes under your disk’s mount path are preserved across deploys and restarts.

    • The rest of your service’s filesystem remains ephemeral.
  • A persistent disk is accessible by only a single service instance, and only at runtime. This means:

    • You can’t access a service’s disk from any other service.

    • Scaling a disk-backed service (early access) has limited applications.

    • You can’t access persistent disks during a service’s build command or pre-deploy command (these commands run on separate compute).

    • You can’t access a service’s disk from a one-off job you run for the service (one-off jobs run on separate compute).

  • Adding a disk to a service prevents zero-downtime deploys. This is because:

    • When you redeploy your service, Render stops the existing instance before bringing up the new instance.

    • This instance swap takes a few seconds, during which your service is unavailable.

    • This is a necessary safeguard to prevent data corruption that can occur when different versions of an app read and write to the same disk simultaneously.

  • You can’t add a disk to a cron job service.

    • As an alternative, you can add a disk to a background worker, which is useful for processes that run continuously and don’t expose a port.
  • You can increase your disk’s size later, but you can’t decrease it. Pick the smallest value that currently works for your service.

    • Increasing a disk’s size does not cause downtime. The additional storage becomes available to your service within a few seconds.

Scaling disk-backed services (early access)

This is an early access feature. Enable it from the Early Access section of your Account Settings or Team Settings page in the Render Dashboard.

Disk-backed services can support both manual scaling and autoscaling (after you enable the early access feature). As with other services, you configure scaling for a disk-backed service in the Render Dashboard.

In addition to improving performance under load, scaling a disk-backed service to two or more instances enables it to support zero-downtime deploys (if each instance can operate independently).

Use cases

Scaling is helpful for services that use their disk as a standalone cache while performing large, long-running tasks. By scaling up these services, different instances can execute independent tasks in parallel.

Do not scale a disk-backed service that hosts a centralized (non-distributed) database. Each service instance uses a completely separate disk, which means your data will become fragmented across disconnected stores.

For details, learn how disk scaling works.

How disk scaling works

When you scale a disk-backed service, Render attaches a separate disk to each instance:

Instance 0
Instance 1
Instance 2
Disk 0
Disk 1
Disk 2

Render does not sync any data between disks.

Each instance can access only its own disk. However, your instances can intercommunicate to share data. See details.

Retention of scaled disks

If you scale down a disk-backed service, Render temporarily retains any disks that were attached to a deprovisioned instance:

Instance 0
Instance 1
Instance 2
Disk 0
Disk 1
Disk 2

Render deletes an unattached disk after a day or two unless it’s reattached to a new instance. During the early access period, the duration of the disk retention period is not defined or guaranteed. Render does not bill you for disks while they are unattached.

If you later scale up the same service, Render can reattach available disks instead of provisioning new ones:

Instance 0
Instance 1
Instance 2
Disk 0
Disk 1
Disk 2

This enables new instances to spin up much faster.

Zero-downtime deploys with disks

Whenever you redeploy a disk-backed service, Render replaces its running instances one at a time. This means that while a particular instance is being replaced, all other instances remain up and running. This enables zero-downtime deploys for a disk-backed service, if each instance can operate independently.

Here are the steps for a new deploy:

  1. Render terminates a single instance, leaving its disk idle. Other instances remain active, preventing downtime.

    Instance 0
    v1
    Instance 1
    v1
    Instance 2
    v1
    Disk 0
    Disk 1
    Disk 2
  2. Render brings up a new instance running the service’s latest build. The idle disk is attached to the new instance.

    Instance 0
    v2
    Instance 1
    v1
    Instance 2
    v1
    Disk 0
    Disk 1
    Disk 2
  3. Render repeats the above steps for each remaining instance in turn. This completes the redeploy.

Communicating between instances

Unlike with other Render services, you can route private network requests to a specific instance of a disk-backed service. This enables your instances to intercommunicate, which is necessary for the peer-to-peer architecture of a distributed database like Cassandra.

Internal addresses for individual instances

Your service’s N active instances have integer identifiers 0 through N-1. A running instance can obtain its own identifier via the RENDER_INSTANCE_ID environment variable.

The format of RENDER_INSTANCE_ID differs between scaled disk-backed services and other services:

  • Scaled disk-backed service: srv-cn5b11gcmk4c73966s8g-1 (Service ID followed by incremental integer ID)
  • Other services: srv-cn5b11gcmk4c73966s8g-7bb5b7f84b-fzkqp (Service ID followed by generated string ID)

The internal address for a specific disk-backed instance has the following format:

[Service ID]-[Instance ID].[Service Name]:[Port]

So, for an instance with the following properties:

PropertyValue
Service IDsrv-cn5b11gcmk4c73966s8g
Instance ID1
Service Namemy-disk-service
Port7000

The internal address for that specific instance is:

srv-cn5b11gcmk4c73966s8g-1.my-disk-service:7000

To send a request that Render load-balances as usual, send a request to the service-level internal address:

my-disk-service:7000

Dynamically obtaining the current instance count

You cannot dynamically obtain the current instance count for a service that has autoscaling enabled.

To know which instance IDs are available for communication, you might need to fetch the current instance count for your service. You can do this via the Render API’s Retrieve service endpoint. The serviceDetails.numInstances field indicates the current instance count (note that some instances might still be spinning up).

Again, serviceDetails.numInstances corresponds to the current instance count for manually scaled services only. If your service has autoscaling enabled, you can’t obtain the current instance count.