ZEDEDA WiKi

User Tools

Site Tools

Trace:
zededa:eve-app-volumes

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
zededa:eve-app-volumes [2026/07/06 14:06] – created mczededa:eve-app-volumes [2026/07/06 18:53] (current) – mc
Line 3: Line 3:
 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. 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: [[https://github.com/lf-edge/eve|lf-edge/eve]], [[https://registry.terraform.io/providers/zededa/zedcloud/latest|zededa/zedcloud Terraform provider docs]], ZEDEDA Help Center (Storage Overview, Manage an Edge Application Instance, ZCLI volume-instance docs).+This page stays at the **controller/app-instance config layer** — the fields you set in the GUI, Terraform, or zcli. For what actually happens on the storage backend underneath (qcow2 vs. zvol, pool RAID vs. per-app resize), see the companion page: [[eve-volume-provisioning|EVE-OS Volume Provisioning: Pool Layer vs. Per-App Layer]]. 
 + 
 +Sources: [[https://github.com/lf-edge/eve|lf-edge/eve]], [[https://registry.terraform.io/providers/zededa/zedcloud/latest|zededa/zedcloud Terraform provider docs]], ZEDEDA Help Center, and real working Terraform (confirmed against actual ''zedcloud_application'' / ''zedcloud_volume_instance'' resources, not just provider doc snippets).
  
 ===== 1. What a volume is ===== ===== 1. What a volume is =====
  
-A **volume instance** is the storage object EVE-OS attaches to an app instance as a drive. It backs one of:+A **volume/drive** is a storage object attached to an app. It backs one of:
  
   * The app's rootfs / OS disk (built from a Content Tree / image) — drive type **HDD**   * 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 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 shared/persistent data volume that can outlive the app, created standalone and attached by reference
  
 A volume can be: A volume can be:
  
-  * **Implicit** — created automatically as part of an app instance's drive list (defined inline on the app manifest) +  * **Implicit** — an entry in the ''images'' list inside the app's ''manifest'' block, defined inline, tied to that app 
-  * **Explicit** — created ahead of time as its own object (''zcli volume-instance create'') and then referenced by label when the app is deployed+  * **Explicit** — a standalone ''zedcloud_volume_instance'' resource (or GUI: **Library > Volume Instances > +**), created independently, then **attached to an app via ''volumelabel''** referencing the standalone volume's ''label''
  
-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.+**Important layering note:** everything on this page — ''maxsize'', ''preserve'', ''ignorepurge'', ''drvtype'' — is a **controller-side config object**. It says nothing about how the volume is physically stored. EVE's ''volumemgr'' agent on the node reads this config and decides how to realize it on whatever persist backend the node has (ext4 or ZFS). That translation step is a completely separate layer — see the companion page.
  
 ===== 2. Key fields ===== ===== 2. Key fields =====
  
-^ Field ^ Where it shows up ^ What it does ^ +==== Standalone Volume Instance (''zedcloud_volume_instance'') ==== 
-| Drive Type (''drvtype'') | GUI Drives pane / TF ''drvtype'' | ''HDD'' = image-backed. ''CDROM'' = read-only image, optical semantics. ''NET'' = network-backed. ''HDD_EMPTY'' = blank disk of ''maxsize'' (covered in section 6). | + 
-| Max Size (''maxsize'' / ''maxsizebytes'') | GUI Drives pane "Max Size" / TF ''maxsize'' | Capacity ceiling for the drive. For ''HDD'', this must be >= the image size; any headroom above the image size is usable, growable space on that same disk. | +Created independently of any app, targets an edge node or cluster directly. 
-| Preserve (''preserve'') | GUI Drives pane "Preserve" | Whether this drive's data survives a purge/refresh of the app instance, vs. being rebuilt from the source image. | + 
-| Allow Storage Resize (''allow_storage_resize'' / ''allowStorageResize'') | App instance level, GUI/zcli/TF | Must be enabled before an existing app instance's drive size can be increased. Default: false. | +^ GUI field ^ TF field ^ Notes ^ 
-| Volume Label (''volumelabel'') | GUI Drives pane / TF | References a pre-created (explicit) volume instance instead of an inline drive definition. | +| Type | ''type'' | ''VOLUME_INSTANCE_TYPE_BLOCKSTORAGE'' confirmed (blank disk). Content Tree type presumably ''VOLUME_INSTANCE_TYPE_CONTENTTREE'' — not yet confirmed against a real example. | 
-| Mount Path (''mountpath'') | GUI Drives pane / TF | Path inside the app where the drive is mounted. Empty or ''/'' defines the rootfs. |+| Access Mode | ''accessmode'' | ''VOLUME_INSTANCE_ACCESS_MODE_READWRITE'' confirmed. Read-only presumably ''VOLUME_INSTANCE_ACCESS_MODE_READONLY'' — not confirmed. | 
 +| Max Storage Size | ''size_bytes'' | Integer bytes. | 
 +| Edge Node | ''device_id'' | Single edge node target. | 
 +| (cluster target) | ''edge_node_cluster { id = ... }'' | Used instead of ''device_id'' for a cluster. | 
 +| Encrypted | ''cleartext'' | Inverted — ''cleartext = false'' means encrypted. | 
 +| Label | ''label'' | This is the string an app's ''images'' block references via ''volumelabel'' to attach this standalone volume. | 
 + 
 +==== App-attached image/drive (''manifest.images'' block, inside ''zedcloud_application'') ==== 
 + 
 +This is the actual, confirmed schema — nested inside ''manifest { }'', as a repeated ''images { }'' block, **not** a top-level ''drives'' block as earlier drafts of this page assumed. 
 + 
 +^ Field ^ Notes ^ 
 +| ''imagename'' | Set for an image-backed entry (references a ''zedcloud_image'' by name). Used for the app's own container/rootfs image. | 
 +| ''volumelabel'' | Set instead of ''imagename'' when this entry attaches a pre-created standalone ''zedcloud_volume_instance'' by its ''label''. Mutually exclusive with ''imagename'' in the real examples seen. | 
 +| ''imageformat'' | ''CONTAINER'' for the app's own OCI image; ''QCOW2'' for an attached persistent block-storage volume. | 
 +| ''drvtype'' | ''HDD'' confirmed for a persistent data disk. (''HDD_EMPTY'', ''CDROM'', ''NET'' — see section 6 and drive-type discussion earlier in this doc's history; not all re-confirmed against a real example yet.) | 
 +| ''mountpath'' | Path inside the app, e.g. ''/data''. Setting ''mountpath'' causes EVE to automatically mount that volume at that path inside the guest — this applies to **both container-type and VM-type apps**, not just containers. The guest doesn't need a manual mount step to get the volume attached at that path; EVE handles it. (The exact guest-side mechanism for VM apps — e.g. whether it's cloud-init-driven, an fstab entry EVE injects, or a guest agent — isn't confirmed from source; noted as an open item in section 7.) This is separate from whether the *filesystem on that volume* needs formatting on first use, or resizing after a ''maxsize'' change — see the guest-side step in section 5. | 
 +| ''cleartext'' | Inverted, same convention as the standalone volume instance — ''false'' means encrypted. | 
 +| ''ignorepurge'' | Real, distinct field from ''preserve'' — both appear together in real examples (''ignorepurge = true'', ''preserve = true''). Exact semantic split between the two is still not confirmed from proto-level source; treat as "there are two separate purge-related knobs here, not one," rather than assuming they're synonyms. | 
 +| ''preserve'' | See above — set alongside ''ignorepurge'', not instead of it. | 
 +| ''maxsize'' | **Bare integer, bytes** — e.g. ''maxsize = 1073741824'' for 1 GiB. Not a quoted string (correcting an earlier draft of this page). | 
 +| ''target'' | Seen as ''target = "Disk"'' on a persistent-volume image entry. Other possible values (e.g. for kernel/initrd-style entries) not confirmed. | 
 + 
 +==== App-level version field ==== 
 + 
 +  * ''user_defined_version'' (on ''zedcloud_application'') — a real example carries the comment *"bump to force a new app version after adding the :1080->:80 portmap ACL"*. This strongly implies **this is the mechanism that pushes a manifest change (including an ''images'' block edit like a ''maxsize'' bump) out to the running app** — bump the version string, apply, and the controller treats it as a new app version to roll out. This replaces an earlier, unconfirmed guess on this page about an ''allow_storage_resize'' flag gating resize — that field does not appear in any real example provided and should be treated as unverified/likely incorrect unless you find it in an actual working config.
  
 ===== 3. What's required to configure — GUI vs Terraform ===== ===== 3. What's required to configure — GUI vs Terraform =====
Line 34: Line 61:
 ==== GUI ==== ==== GUI ====
  
-  * Volume instances can be created standalone: Edge Node > Storage > Volume Instances > Add, or created implicitly while adding a drive to an app instance. +  * Standalone volume instances: **Library > Volume Instances > +** (Add Volume Instance). Set Type (Content Tree or Block Storage), Access Mode, target Edge Node, and either Image (Content Tree) or Max Storage Size (Block Storage). 
-  * 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. +  * Implicit volumes are created inline while adding a drive to an app instance instead — no separate object. 
-  * 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.+  * On the app's **Drives pane** (GUI's view into the ''manifest.images'' list), define per drive: Drive Type, Image or Volume Label, Mount Path, Max Size, Preserve. 
 +  * Editing Drives on an **existing** app instance triggers a **Purge & Update** in the GUI — the app purges and comes back online. Data on that drive is wiped unless Preserve was set.
  
 ==== Terraform (zededa/zedcloud provider) ==== ==== Terraform (zededa/zedcloud provider) ====
  
-  * Resource: ''zedcloud_application_instance'' (or ''zedcloud_deployment'' for policy-driven rollout). +  * Standalone volume: ''zedcloud_volume_instance'' — see field table above. 
-  * Drive block fields: ''drvtype'', ''maxsize'', ''preserve'', ''mountpath'', ''imagename'' / ''imvolname'' / ''mvolname'', ''volumelabel''. +  * App + attached volume: ''zedcloud_application'', with a ''manifest { images { ... } }'' block per drive. See section 4 for a full real example. 
-  * App-instance-level field: ''allow_storage_resize'' (bool, default false) — must be ''true'' to permit a later ''maxsize'' change to apply. +  * To attach a standalone volume instance to an app, reference its ''label'' via ''volumelabel'' in one of the app's ''images'' entries — do not redeclare size/type there, those live on the volume instance itself. 
-  * 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.+  * Bump ''user_defined_version'' on the ''zedcloud_application'' resource to push out a manifest change.
  
 ==== ZCLI ==== ==== ZCLI ====
Line 49: Line 77:
   * Explicit volume: ''zcli volume-instance create <name> --volume-type=<type> --project=<project> (--edge-node=<node> | --edge-node-cluster=<cluster>) --size=<size> --access-mode=<mode>''   * 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=...]''   * 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'' 
  
-===== 4. Step-by-step: Deploy an app with a volume (HDD) =====+===== 4. Step-by-step: Deploy an app with a persistent volume =====
  
-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. +This is the real, confirmed pattern: a standalone ''zedcloud_volume_instance'' (persistent, survives app redeploys) attached to an app's second ''images'' entry by ''volumelabel'', alongside the app's own container image as the first entry.
- +
-==== Via GUI ==== +
- +
-  - Go to **Edge Applications > Marketplace**, select or create the edge app. +
-  - Deploy the app: **Edge Applications > Deploy**, pick the target edge node. +
-  - On the **Drives pane**, add the drive: +
-    - Drive Type: **HDD** +
-    - Image: select the app's image / content tree +
-    - Mount Path: ''/'' (or empty) to define the rootfs +
-    - 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) +
-    - Preserve: enable if this disk's contents should survive a future purge +
-  - Complete networking/resources panes as normal and click **Deploy**. +
-  - Confirm in **Edge Node > App Instances** that the instance reaches ''RUNNING'' and the drive shows the expected size under app instance details.+
  
 ==== Via Terraform ==== ==== Via Terraform ====
  
 <code hcl> <code hcl>
-resource "zedcloud_application_instance" "example" { +# 1. Standalone persistent volume, targeting a specific edge node 
-  name         = "my-app-instance" +resource "zedcloud_volume_instance" "tf_demo_vol1_cont_persist" { 
-  app_id       = zedcloud_application.example.id +  device_id  = zedcloud_edgenode.demo_en_onlogic_cl250.id  # Edge Node ID 
-  device_id    = data.zedcloud_edgenode.target.id +  accessmode = "VOLUME_INSTANCE_ACCESS_MODE_READWRITE" 
-  project_id   = data.zedcloud_project.example.id+  cleartext  = false 
 +  label      = "adv-vol1-cont-persist" 
 +  name       = "adv-vol1-cont-persist" 
 +  size_bytes = 1073741824   # 1 GiB 
 +  title      = "adv-vol1-persist" 
 +  type       = "VOLUME_INSTANCE_TYPE_BLOCKSTORAGE"
  
-  drives { +  lifecycle { 
-    drvtype     = "HDD" +    ignore_changes = [device_id]
-    imagename   = "my-app-image" +
-    mountpath   = "/" +
-    maxsize     = "21474836480"   # 20 GiB ceiling, even if the image itself is much smaller +
-    preserve    = true+
   }   }
 +}
  
-  allow_storage_resize = true+# 2. App that attaches the volume above as its second drive 
 +resource "zedcloud_application" "tf_nginx_app_1" { 
 +  name     = "TF-STND-NGINX-APP-1" 
 +  title    = "TF-STND-NGINX-APP-1" 
 +  networks = 1 
 +  manifest { 
 +    ac_kind    = "VMManifest" 
 +    ac_version = "1.2.0" 
 +    name       = "TF-NGINX-APP-1" 
 +    owner { 
 +      user    = "Manny" 
 +      company = "Zededa" 
 +      website = "www.zededa.com" 
 +      email   = "manny@zededa.com" 
 +    } 
 +    desc { 
 +      app_category = "APP_CATEGORY_CLOUD_APPLICATION" 
 +      category     = "APP_CATEGORY_UNSPECIFIED" 
 +      logo = { 
 +        url = "https://nginx.org/img/nginx_logo.svg" 
 +      } 
 +    } 
 +    images { 
 +      # first drive: the app's own container image 
 +      imagename   = zedcloud_image.demo_nginx_alpine.name 
 +      cleartext   = false 
 +      ignorepurge = true 
 +      imageformat = "CONTAINER" 
 +    } 
 +    images { 
 +      # second drive: attach the standalone persistent volume from above 
 +      volumelabel = zedcloud_volume_instance.tf_demo_vol1_cont_persist.label 
 +      imageformat = "QCOW2" 
 +      mountpath   = "/data" 
 +      cleartext   = false 
 +      drvtype     = "HDD" 
 +      ignorepurge = true 
 +      preserve    = true 
 +      maxsize     = 1073741824 
 +      target      = "Disk" 
 +    } 
 +    interfaces { 
 +      name         = "eth0" 
 +      type         = "ip" 
 +      directattach = false 
 +      privateip    = false 
 +      acls { 
 +        matches { 
 +          type  = "ip" 
 +          value = "0.0.0.0/0" 
 +        } 
 +      } 
 +    } 
 +    vmmode    = "HV_PV" 
 +    enablevnc = true 
 +    resources { 
 +      name  = "resourceType" 
 +      value = "custom" 
 +    } 
 +    resources { 
 +      name  = "cpus" 
 +      value = 2 
 +    } 
 +    resources { 
 +      name  = "memory" 
 +      value = 2097152 
 +    } 
 +    configuration { 
 +      custom_config { 
 +        add      = true 
 +        name     = "cloud-config" 
 +        override = true 
 +        template = "" 
 +      } 
 +    } 
 +    app_type            = "APP_TYPE_CONTAINER" 
 +    deployment_type     = "DEPLOYMENT_TYPE_STAND_ALONE" 
 +    cpu_pinning_enabled = false 
 +  } 
 +  user_defined_version = "1" 
 +  origin_type          = "ORIGIN_LOCAL" 
 +  project_access_list  = []
 } }
 </code> </code>
  
   - ''terraform plan'' / ''terraform apply''.   - ''terraform plan'' / ''terraform apply''.
-  - Verify state: ''terraform state show zedcloud_application_instance.example'' or check the GUI app instance detail page. +  - Confirm in the GUI that the app instance reaches ''RUNNING'' and the second drive shows the persistent volume attached at ''/data''.
- +
-===== 5. Step-by-step: Grow a volume (HDD) =====+
  
-**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.+===== 5. Step-by-step: Grow a volume =====
  
-==== Via GUI ==== +**Important:** this is not a live/hot resize. Applying a manifest change that alters an ''images'' entry triggers a purge/redeploy of the app. Data on that drive is lost unless ''preserve''/''ignorepurge'' are set appropriately on that entry.
- +
-  - Confirm the drive you're growing has **Preserve** set (if you need to keep its data). +
-  - Go to **Edge Applications > App Instances**, select the instance, **Edit**. +
-  - If not already enabled, enable **Allow Storage Resize** at the app instance level. +
-  - On the Drives pane, raise the **Max Size** field for the HDD drive. +
-  - Save. The GUI will show a **Purge and update** notification — confirm it. +
-  - Wait for the app instance to purge and come back ''RUNNING''. +
-  - 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).+
  
 ==== Via Terraform ==== ==== Via Terraform ====
 +
 +  - Raise ''maxsize'' on the relevant ''images'' block (or ''size_bytes'' on the standalone ''zedcloud_volume_instance'', if the volume is standalone rather than inline).
 +  - **Bump ''user_defined_version''** on the ''zedcloud_application'' resource — this is the confirmed mechanism (see the real example's own comment: *"bump to force a new app version"*) for pushing the manifest change out.
 +  - ''terraform apply''.
 +  - Confirm the app redeploys and the drive reflects the new size.
  
 <code hcl> <code hcl>
-resource "zedcloud_application_instance" "example" { +images { 
-  # ...unchanged config... +  volumelabel = zedcloud_volume_instance.tf_demo_vol1_cont_persist.label 
- +  imageformat = "QCOW2" 
-  drives { +  mountpath   = "/data" 
-    drvtype     = "HDD" +  cleartext   = false 
-    imagename   = "my-app-image" +  drvtype     = "HDD" 
-    mountpath   = "/" +  ignorepurge = true 
-    maxsize     = "42949672960"   # was 20 GiB, now 40 GiB +  preserve    = true 
-    preserve    = true +  maxsize     = 2147483648   # was 1 GiB, now 2 GiB 
-  } +  target      = "Disk"
- +
-  allow_storage_resize = true    # must be true BEFORE the maxsize change is allowed to apply+
 } }
 +# ...
 +user_defined_version = "2"   # bumped from "1" to push this change out
 </code> </code>
  
-  - ''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). +If the volume is instead a standalone ''zedcloud_volume_instance'' (not inline in the app's ''images'' list), raise ''size_bytes'' on that resource directly and apply — no app-side version bump needed in that case, since the volume object is independent of the app manifest.
-  - Confirm the app instance purges and comes back up.+
  
-==== Guest-side step (both paths) ====+==== Guest-side step ====
  
-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:+Mounting the volume at ''mountpath'' is automatic for both VM and container apps (see section 2). What is **not** automatic is growing the filesystem living on that volume after a ''maxsize'' increase:
  
 +  * **Raw/unformatted disk (no filesystem yet, e.g. a fresh ''HDD_EMPTY'')**: still needs an initial partition/format the first time it's used, regardless of app type — ''mountpath'' auto-mounts the device, it doesn't format it.
 +  * **Existing filesystem, size increased via ''maxsize''**: whether the filesystem auto-expands to fill the new space, or needs an explicit resize, is **not confirmed** either way — for a VM app this would normally be the classic ''growpart''/''resize2fs''/''xfs_growfs'' pattern run inside the guest; for a container app it may depend on how EVE re-presents the resized volume on next purge/redeploy. Verify on a test app instance by growing ''maxsize'', redeploying, and checking available space at the mount path before assuming either "just works."
 +
 +Reference commands if a manual resize turns out to be needed:
   * Linux ext4: ''growpart /dev/xxx N'' then ''resize2fs /dev/xxxN''   * Linux ext4: ''growpart /dev/xxx N'' then ''resize2fs /dev/xxxN''
   * Linux xfs: ''growpart'' then ''xfs_growfs <mountpoint>''   * Linux xfs: ''growpart'' then ''xfs_growfs <mountpoint>''
   * Windows: Disk Management > right-click volume > Extend Volume   * Windows: Disk Management > right-click volume > Extend Volume
  
-===== 6. Other use case: HDD_EMPTY (blank data disk) =====+===== 6. Other use case: HDD_EMPTY (blank data disk, no attached content) =====
  
-**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. +**HDD_EMPTY** is the drive-type equivalent of a standalone ''VOLUME_INSTANCE_TYPE_BLOCKSTORAGE'' volume, but declared inline in an app's ''images'' block instead of as a standalone object — no image, no content tree, no ''volumelabel'' reference, just a blank disk sized by ''maxsize''.
- +
-  * 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. +
- +
-<code hcl> +
-drives { +
-  drvtype     = "HDD_EMPTY" +
-  maxsize     = "10737418240"   # 10 GiB blank data disk +
-  preserve    = true +
-  mountpath   = "/data" +
-} +
-</code>+
  
-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.+  * No ''imagename'' and no ''volumelabel'' — the entry is purely ''drvtype = "HDD_EMPTY"'' plus ''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. 
 +  * Use this over a standalone volume instance when the data disk is specific to one app and doesn't need to be managed as its own independent object (e.g. reused across app versions, or attached to a different app later).
  
 ===== 7. Open questions / to verify before relying on this in production ===== ===== 7. Open questions / to verify before relying on this in production =====
  
-  * 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. +  * Exact semantic split between ''ignorepurge'' and ''preserve'' — both are confirmed real, distinct fields that appear together in working examples, but the precise difference in behavior between them is not confirmed from proto-level source. 
-  * Whether setting ''maxsize'' well above the image size immediately consumes that much physical persist space, or is thin-provisioned — see [[eve-volume-provisioning|Does maxsize Fully Provision the Disk?]] for the qcow2 vs. ZFS zvol breakdown.+  * Whether ''allow_storage_resize'' is a real field at all — it does not appear in any real example seen so far. Earlier drafts of this page asserted it existed based on generic provider-doc search snippets; treat that as unverified/likely wrong unless confirmed against an actual working resource. 
 +  * Full set of valid values for ''target'' on an ''images'' block — only ''"Disk"'' confirmed. 
 +  * Full set of valid ''type''/''accessmode'' enum values on ''zedcloud_volume_instance'' beyond ''VOLUME_INSTANCE_TYPE_BLOCKSTORAGE'' and ''VOLUME_INSTANCE_ACCESS_MODE_READWRITE''.
   * 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.   * 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.+  * How ''maxsize''/''size_bytes'' actually gets realized on disk (qcow2 vs. per-app zvol, thin vs. thick) — different layer than anything on this page. See [[eve-volume-provisioning|EVE-OS Volume Provisioning: Pool Layer vs. Per-App Layer]]. 
 +  * This page is entirely about **app-attached volumes**. It does not cover the underlying ''/persist'' storage pool (ext4 disk or ZFS pool, RAID level) — that is an install-time/reinstall decision made via grub.cfg, not a controller-driven one. Covered on the EVE-OS Partitioning / ZFS wiki page.
zededa/eve-app-volumes.1783346811.txt.gz · Last modified: by mc