​

Overview

Persistent Disks let an App Service keep state on disk across deploys, restarts, and container recycles. They are the recommended option for workloads that need durable local storage but don’t fit into one of Aptible’s Managed Databases, for example, JupyterLab notebooks, or self-hosting third-party tools that require local disk. By default, App Containers run with an ephemeral filesystem: any data written outside of an attached Persistent Disk is lost when the container is recycled. A Persistent Disk is a separately-provisioned volume that is mounted into the container and survives the container’s lifecycle. Under the hood, each Persistent Disk is an AWS EBS gp3 volume, and all Persistent Disks are encrypted at rest using AWS EBS volume encryption.

​

When to use a Persistent Disk

Reach for a Persistent Disk when:

• You need a small amount of durable local state, and a Managed Database is the wrong shape for the data (for example, a working directory for a stateful background job, or a self-managed search index).
• The data does not need to be shared across multiple replicas.
• You can tolerate the operational tradeoffs described in Limitations below. Most importantly, the Service is pinned to a single container and a single Availability Zone.

Persistent Disks are not for:

• Shared, multi-writer storage across containers. A disk attaches to one Service at a time, and that Service is pinned to a single container, so multiple processes on different containers cannot read or write the same disk.
• Automatic backups. Aptible does not snapshot Persistent Disks. Backing up disk contents is your responsibility.
• Cross-AZ failover. A disk lives in one Availability Zone, and the Service that mounts it runs in that same AZ for the life of the disk.
• Object-store-style large-file workloads. For bulk file storage, media, or shared blobs, AWS S3 (or another object store) is a better fit.
• Self-hosted databases. Use a Managed Database instead.

If you need shared, multi-writer storage, a managed object store (for example, AWS S3) or a Managed Database is usually a better fit.

​

Creating and attaching a disk

The Aptible Dashboard offers creating a Persistent Disk and attaching it to a Service as a single flow. Under the hood, these are two separate operations: the create can succeed even if the attach fails, in which case the disk exists unattached and can be attached afterward. You specify:

• The Service the disk will attach to.
• The size of the disk in GB.
• The mount point inside the container (for example, /var/data).

Once attached, the Service is restarted so the new container can mount the volume. The Service’s container is scheduled into the same Availability Zone as the disk (see Limitations).

​

Mount points

The mount point is the path inside the container at which the disk is exposed. It must be an absolute path, and it should not collide with a path that is populated by your container image (otherwise, the image contents at that path will be hidden by the mount). A common choice is a dedicated directory like /var/data or /mnt/data. The mount point is set when the disk is first attached and cannot be changed in place. To move data to a new mount point, detach the disk, re-attach it at the new path, and update your application code.

​

Detaching a disk

A disk can be detached from a Service from the Aptible Dashboard. Detaching stops the running container, unmounts the disk, and starts a new container without the disk attached. The disk itself is preserved and can later be re-attached to a Service in the same Environment as the disk or destroyed. Detaching restarts the Service’s container so it comes back up without the disk mounted. Plan for a brief interruption when you detach. Destroying a disk permanently deletes its contents. There is no undo: make sure any data you want to keep is backed up before you destroy a disk.

​

Resizing a disk

A Persistent Disk can be resized up at any time from the Aptible Dashboard. Increasing the size grows the volume in place: you do not need to detach the disk or create a new one, and the data on the disk is preserved. Like attaching and detaching, resizing requires a brief restart of the Service so the new container can use the resized volume. A disk cannot be made smaller. If you need to reduce the size of a disk, create a new, smaller disk, copy your data over, and detach and destroy the original.

​

Limitations

Persistent Disks introduce some constraints that don’t apply to stateless App Services. Plan for these before you adopt them.

​

Single Availability Zone

A Persistent Disk lives in a single Availability Zone. The Service’s container must run in the same AZ as its disk, so the Service is effectively pinned to that AZ for the life of the disk. If the AZ becomes unavailable, the Service will be unavailable until the AZ recovers. If your workload requires multi-AZ resilience for the data on disk, use a Managed Database or an external object store instead.

​

Single container per Service

A Service with a Persistent Disk attached must be scaled to a container count of 1. You cannot scale horizontally: the disk cannot be shared across multiple containers, and Aptible will not let you increase the container count while a disk is attached. If you need to scale a workload horizontally, split the durable state out (into a Managed Database, an object store, or a separate Service) so the horizontally-scaled Service can stay stateless. See App Scaling for more on how Services are scaled.

​

No zero-downtime deploys

A normal Aptible App Service is deployed with a zero-downtime Release: a new container is started, traffic shifts to it, and the old container is stopped only after the new one is healthy. A Service with a Persistent Disk cannot deploy with zero downtime. The disk can only be mounted into one container at a time, so deploys (and any operation that recycles the container, such as a restart, scale, configuration change, or attaching, detaching, or resizing the disk) follow a stop-then-start pattern: the existing container is stopped, the disk is unmounted, the new container is started, and the disk is re-mounted. Plan for a brief interruption on every deploy of a Service with a Persistent Disk. See Releases for more on the deploy lifecycle.

​

Permissions

Persistent Disks are managed with the same environment-scoped permissions as your other resources, such as Apps and Databases. There is no special or privileged access required. Creating a disk and attaching it to a Service require the Deployment permission. Resizing or modifying a disk requires the Deployment or Ops permission, and detaching a disk requires the Deployment or Destruction permission. Deleting a disk requires the Destruction permission. See the Roles & Permissions matrix for the full action-to-permission mapping.

​

Pricing

Persistent Disks are billed at $0.20 per GB per month of provisioned capacity, independent of the Service they are attached to. Billing is based on the size you provision, not the amount of data you store. A disk bills for as long as it exists, whether or not it is currently attached to a Service. Detaching a disk preserves its data and continues to bill for it. Only destroying the disk stops billing. Disks are provisioned as gp3 volumes with a baseline of 3,000 IOPS at no additional charge; IOPS and throughput are not user-configurable. If a disk is provisioned with IOPS above the baseline, the additional IOPS are billed at $0.01 per provisioned IOPS per month. Most disks run at the baseline and incur no IOPS charge.

​

Related

• Managing Apps
• App Scaling
• Releases
• Managed Databases for multi-writer or multi-AZ durable storage