EVE-OS / ZEDEDA Application Volumes

Covers: what a volume is, what has to be configured in the GUI vs Terraform, how to deploy an app with a volume, and how to grow a volume after deployment. Primary examples use an image-backed HDD drive; HDD_EMPTY is covered as a separate use case at the end.

Sources: lf-edge/eve, zededa/zedcloud Terraform provider docs, ZEDEDA Help Center (Storage Overview, Manage an Edge Application Instance, ZCLI volume-instance docs).

A volume instance is the storage object EVE-OS attaches to an app instance as a drive. It backs one of:

• The app's rootfs / OS disk (built from a Content Tree / image) — drive type HDD
• A blank data disk for app data — drive type HDD_EMPTY
• A shared/persistent data volume that can outlive the app instance or be shared between app instances on the same node

A volume can be:

• Implicit — created automatically as part of an app instance's drive list (defined inline on the app manifest)
• Explicit — created ahead of time as its own object (zcli volume-instance create) and then referenced by label when the app is deployed

Underlying storage is a qcow2 file (ext4 persist) or a zvol (ZFS persist), depending on how the edge node's /persist partition was provisioned at install time — see the separate EVE-OS Partitioning / ZFS wiki page for that layer. Volumes live inside whichever persist backend the node has.

• Volume instances can be created standalone: Edge Node > Storage > Volume Instances > Add, or created implicitly while adding a drive to an app instance.
• On the app instance's Drives pane, define per drive: Drive Type, Image, Mount Path, Max Size, Preserve, Encrypted, and (for explicit volumes) Volume Label.
• Editing Drives on an existing app instance triggers a Purge & Update — the app purges and comes back online. Data on that drive is wiped unless Preserve was set.

• Resource: zedcloud_application_instance (or zedcloud_deployment for policy-driven rollout).
• Drive block fields: drvtype, maxsize, preserve, mountpath, imagename / imvolname / mvolname, volumelabel.
• App-instance-level field: allow_storage_resize (bool, default false) — must be true to permit a later maxsize change to apply.
• Standalone volume instances can also be managed as their own resource/data source (zedcloud_volume_instance family) and referenced by label from the app instance.

• Explicit volume: zcli volume-instance create <name> –volume-type=<type> –project=<project> (–edge-node=<node> | –edge-node-cluster=<cluster>) –size=<size> –access-mode=<mode>
• Update: zcli volume-instance update <name> [–title=…] [–description=…]
• App-instance-level resize permission is passed the same way as the GUI/TF flag, camelCase in JSON: “allowStorageResize”: true

This is the common case: a single image-backed drive that serves as both the app's rootfs and its data storage, sized larger than the image itself so there's room to grow later.

1. Go to Edge Applications > Marketplace, select or create the edge app.
2. Deploy the app: Edge Applications > Deploy, pick the target edge node.
3. On the Drives pane, add the drive:
   1. Drive Type: HDD
   2. Image: select the app's image / content tree
   3. Mount Path: / (or empty) to define the rootfs
   4. Max Size: set this above the image's native size if you want growable headroom (e.g. image is 4 GB, set Max Size to 20 GB)
   5. Preserve: enable if this disk's contents should survive a future purge
4. Complete networking/resources panes as normal and click Deploy.
5. Confirm in Edge Node > App Instances that the instance reaches RUNNING and the drive shows the expected size under app instance details.

resource "zedcloud_application_instance" "example" {
  name         = "my-app-instance"
  app_id       = zedcloud_application.example.id
  device_id    = data.zedcloud_edgenode.target.id
  project_id   = data.zedcloud_project.example.id
 
  drives {
    drvtype     = "HDD"
    imagename   = "my-app-image"
    mountpath   = "/"
    maxsize     = "21474836480"   # 20 GiB ceiling, even if the image itself is much smaller
    preserve    = true
  }
 
  allow_storage_resize = true
}

1. terraform plan / terraform apply.
2. Verify state: terraform state show zedcloud_application_instance.example or check the GUI app instance detail page.

Important: this is not a live/hot resize. Editing a drive on an existing app instance triggers a Purge & Update — the app purges and restarts. Data on that drive is lost unless preserve is set on it.

1. Confirm the drive you're growing has Preserve set (if you need to keep its data).
2. Go to Edge Applications > App Instances, select the instance, Edit.
3. If not already enabled, enable Allow Storage Resize at the app instance level.
4. On the Drives pane, raise the Max Size field for the HDD drive.
5. Save. The GUI will show a Purge and update notification — confirm it.
6. Wait for the app instance to purge and come back RUNNING.
7. Log into the guest and grow the filesystem to use the new space (EVE resizes the backing volume, not the guest's partition/fs — see step below).

resource "zedcloud_application_instance" "example" {
  # ...unchanged config...
 
  drives {
    drvtype     = "HDD"
    imagename   = "my-app-image"
    mountpath   = "/"
    maxsize     = "42949672960"   # was 20 GiB, now 40 GiB
    preserve    = true
  }
 
  allow_storage_resize = true    # must be true BEFORE the maxsize change is allowed to apply
}

1. terraform apply. If allow_storage_resize was false on the last-applied state, apply that change first, then apply the maxsize change (or in the same apply if the provider allows it — verify against current provider version behavior before assuming ordering).
2. Confirm the app instance purges and comes back up.

EVE enlarges the backing volume (qcow2/zvol); it does not grow the guest's partition or filesystem automatically. After the app instance comes back up:

• Linux ext4: growpart /dev/xxx N then resize2fs /dev/xxxN
• Linux xfs: growpart then xfs_growfs <mountpoint>
• Windows: Disk Management > right-click volume > Extend Volume

HDD_EMPTY is a second, complementary pattern rather than an alternative to the above: a completely blank disk, not backed by any image or content tree, used as a separate data drive alongside an HDD rootfs drive.

• No image, no content tree, no hash to verify — EVE just allocates raw space up to maxsize.
• Arrives to the guest as a raw, unformatted block device. The guest OS (or first-boot cloud-init) has to partition and format it itself.
• Typically mounted at a data path (e.g. /data, /var/lib/mysql), separate from /.
• Same preserve, maxsize, and allow_storage_resize mechanics apply — grown the same way as described in section 5, just as a second drive block rather than the rootfs drive.

drives {
  drvtype     = "HDD_EMPTY"
  maxsize     = "10737418240"   # 10 GiB blank data disk
  preserve    = true
  mountpath   = "/data"
}

Use this when you want the OS/app image to stay a fixed, replaceable artifact (rebuilt cleanly on every app update) while the data lives on its own drive that is never touched by an image update — as opposed to the HDD pattern in sections 4-5, where rootfs and data share one disk and the whole disk gets rebuilt from the image on update unless preserve is set.

• Exact ordering requirement between setting allow_storage_resize=true and applying a maxsize change in a single Terraform apply — not confirmed from docs, test on a non-prod app instance first.
• Whether any current EVE-OS version auto-grows the guest filesystem on boot after a resize (e.g., via cloud-init growpart module) — not confirmed; assume manual step is required unless verified for your specific image.
• This applies to app instance drives only. It does not expand the underlying /persist storage pool (ext4 disk or ZFS pool) — see the separate Partitioning/ZFS page for that, which is a install-time/reinstall operation, not a controller-driven one.