ZEDEDA WiKi

User Tools

Site Tools

Trace: • creating-a-model
zededa:eve-app-volumes

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
zededa:eve-app-volumes [2026/07/06 14:22] – mczededa:eve-app-volumes [2026/07/06 18:53] (current) – mc
Line 5: Line 5:
 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]]. 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 (Storage Overview, Manage an Edge Application Instance, ZCLI volume-instance docs).+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 standalone object (**Library > Volume Instances > +**) 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''
  
-==== Standalone Volume Instance — Type options ====+**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.
  
-When adding a standalone Volume Instance via the GUI, **Type** is one of:+===== 2. Key fields =====
  
-  * **Content Tree** — image-backed. An **Image** field appears (Select/Search Image) to pick the content tree. This is the standalone-object equivalent of an ''HDD'' drive. +==== Standalone Volume Instance (''zedcloud_volume_instance'') ====
-  * **Block Storage** — blank. No Image field. Instead a **Max Storage Size** field appears (value + unit, e.g. Bytes). This is the standalone-object equivalent of ''HDD_EMPTY''.+
  
-Both types also require:+Created independently of any app, targets an edge node or cluster directly.
  
-  * **Access Mode**: ''Read'' or ''Read/Write'' +^ GUI field ^ TF field ^ Notes ^ 
-  * **Edge Node**: the target node the volume instance is delivered to (required either way — a standalone volume instance is still provisioned on a specific node, not floating free of one) +| Type | ''type'' | ''VOLUME_INSTANCE_TYPE_BLOCKSTORAGE'' confirmed (blank disk). Content Tree type presumably ''VOLUME_INSTANCE_TYPE_CONTENTTREE'' — not yet confirmed against a real example. | 
-  * Optional: **Label**, **Encrypted** (Block Storage), **Deploy Edge Nodes Cluster** toggle if targeting a cluster instead of a single node+| 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. |
  
-**Important layering note:** everything on this page — ''maxsize'', ''preserve'', ''allow_storage_resize'', drive type — is a **controller-side config object** (EVE's ''VolumeConfig'', defined in ''pillar/types/volumes.go''). 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.+==== App-attached image/drive (''manifest.images'' block, inside ''zedcloud_application'') ====
  
-===== 2. Key fields (controller/app-instance layer) =====+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 ^ Where it shows up ^ What it does ^ +^ Field ^ Notes ^ 
-| 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). | +| ''imagename'' | Set for an image-backed entry (references a ''zedcloud_image'' by name). Used for the app's own container/rootfs image. | 
-| Max Size (''maxsize'' / ''maxsizebytes'') | GUI Drives pane "Max Size" / TF ''maxsize'' | Capacity ceiling for the drive, as seen by the app-instance config. For ''HDD'', this must be >= the image size; any headroom above the image size is usable, growable space on that same disk. **This value is what volumemgr uses to size the actual backing object** — see companion page for what that object is. | +| ''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. | 
-| 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. | +| ''imageformat'' | ''CONTAINER'' for the app's own OCI image; ''QCOW2'' for an attached persistent block-storage volume. | 
-| 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. | +| ''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.) | 
-| Volume Label (''volumelabel'') | GUI Drives pane / TF | References a pre-created (explicit) volume instance instead of an inline drive definition. | +| ''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. | 
-| Mount Path (''mountpath'') | GUI Drives pane / TF | Path inside the app where the drive is mounted. Empty or ''/'' defines the rootfs. |+| ''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 51: Line 63:
   * 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).   * 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).
   * Implicit volumes are created inline while adding a drive to an app instance instead — no separate object.   * Implicit volumes are created inline while adding a drive to an app instance instead — no separate object.
-  * 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. +  * 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** — the app purges and comes back online. Data on that drive is wiped unless Preserve was set.+  * 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 65: 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) =====+===== 5. Step-by-step: Grow a volume =====
  
-**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. +**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.
- +
-==== Via GUI ==== +
- +
-  - 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 ====
  
-Raising ''maxsize'' enlarges the backing storage object (whatever volumemgr made it — see companion page); 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 — the app-instance config just declares ''maxsize'', and volumemgr allocates raw space up to that. +
-  * 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 ''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.
-  * How ''maxsize'' actually gets realized on disk (qcow2 vs. per-app zvol, thin vs. thick) — this is a **different layer** than anything on this page. See [[eve-volume-provisioning|EVE-OS Volume Provisioning: Pool Layer vs. Per-App Layer]]. +  * 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 instance drives**. 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.+  * 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.1783347760.txt.gz · Last modified: by mc