Manage Volumes

Use the ZEDEDA CLI (ZCLI) to manage volumes from the command line. A volume provides storage on an edge node for an edge application to store its working copy, runtime data, and logs, and lets applications on the same node share data with each other. This article covers zcli volume-instance commands, with syntax and examples for each operation. The console GUI calls these resources volumes; the CLI command name is volume-instance.

Before You Start

ZCLI is installed and authenticated against your enterprise. See Get Started.
You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
The project and the edge node or node cluster that will host the volume already exist. List them with zcli project show, zcli edge-node show, or zcli edge-node-cluster show.
For GUI-based volume management, see Volumes Overview, Create Volumes, and Manage Volumes.

Volume Types and Access Modes

The --volume-type flag selects the kind of volume to create. The console GUI exposes the following two types.

`--volume-type` value	GUI name	Description
`CONTENT_TREE`	Image Volume	Downloads an immutable application image from your datastore to the node. Pass the image name with `--image`. Edge applications use this as a read-only base image, so set `--access-mode=READONLY`.
`BLOCKSTORAGE`	Block Storage	Provides writable storage for application data. You specify the access mode and the maximum size, and you can optionally initialize the volume from an existing image volume with `--content-tree`.

The CLI also accepts HOSTFS, TMPFS, SECRET, NFS, AWS-BLOCKSTORAGE, and EMPTDIR (an empty directory) for other deployment scenarios. These types are not exposed in the console GUI. The zcli volume-instance --help text lists the empty-directory type as EMTDIR, but ZCLI rejects that spelling. Use EMPTDIR. The --access-mode flag sets the permission applications have on the volume.

`--access-mode` value	GUI name	Description
`READONLY`	Read Only	Applications can read from this volume but cannot write to it.
`READWRITE`	Read Write	Applications can read from and write to this volume.
`MULTIREAD-SINGLEWRITE`	Multi Read / Single Write	Behaves the same as Read Write. Multiple applications can read; writes are handled as single-writer access.

Create a volume

Create a volume on a single edge node with --edge-node, or on a node cluster with --edge-node-cluster. You must pass exactly one of the two. The --size value is the maximum size in bytes. If you omit --title or --description, ZCLI sets both to the volume name.

zcli volume-instance create <name> --volume-type=<volume-type> --project=<project> (--edge-node=<edge-node> | --edge-node-cluster=<edge-node-clulster>) --size=<size> --access-mode=<access-mode> [--content-tree=<name>] [--label=<label>] [--image=<image>] [--title=<title>] [--description=<description>]

Flag	Description
`--volume-type`	Volume type. See the preceding table for supported values.
`--project`	Name of the project the volume belongs to. List projects with `zcli project show`.
`--edge-node`	Name of the edge node that hosts the volume. List nodes with `zcli edge-node show`.
`--edge-node-cluster`	Name of the node cluster that hosts the volume. List clusters with `zcli edge-node-cluster show`.
`--size`	Maximum volume size in bytes.
`--access-mode`	Access mode. See the preceding table for supported values.
`--image`	Name of the application image that backs an image volume.
`--content-tree`	Name of an existing image volume to use as the initial content of a block storage volume.
`--label`	An optional identifier used to select preferred volumes for deployments. This is the same Label field shown in the console. It is separate from the volume name, which is what an edge app drive references.
`--title`	Display title. Defaults to the volume name.
`--description`	Description. Defaults to the volume name.

Example (block storage volume with a 10 GB maximum size on a single node):

zcli volume-instance create MY_VOLUME --volume-type=BLOCKSTORAGE --project=MY_PROJECT --edge-node=MY_NODE --size=10737418240 --access-mode=READWRITE

Example (image volume backed by an application image):

zcli volume-instance create MY_IMAGE_VOLUME --volume-type=CONTENT_TREE --image=MY_IMAGE --project=MY_PROJECT --edge-node=MY_NODE --size=10737418240 --access-mode=READONLY

Example (block storage volume initialized from an existing image volume on a node cluster):

zcli volume-instance create MY_SHARED_VOLUME --volume-type=BLOCKSTORAGE --content-tree=MY_IMAGE_VOLUME --project=MY_PROJECT --edge-node-cluster=MY_CLUSTER --size=21474836480 --access-mode=READWRITE

The volume name is the label that an edge application drive uses to attach the volume. When you define an edge application, add a drive and set its tag to the volume name. EVE-OS (Edge Virtualization Engine) maps the drive to the volume on the node by that tag, so the volume must already exist on the node before the application instance starts. For the GUI procedure, see Attach Volumes to Multiple Applications.

View volumes

Run show with no arguments to list every volume in your enterprise. Pass a name or --uuid to view a single volume, and add --detail for the full configuration and run state. To list the volumes on one node, pass --project together with --edge-node. The --edge-node and --edge-node-cluster filters require --project.

zcli volume-instance show [[[<name> | --uuid=<uuid>] [--detail]] | [[--name-pattern=<name-pattern>] [--summary] [--page-size=<page-size>] [--project=<project> [--edge-node=<edge-node> | --edge-node-cluster=<edge-node-cluster>]]]]

Flag	Description
`--detail`	Show the full configuration and status of one volume.
`--uuid`	Select a volume by its UUID instead of its name.
`--name-pattern`	Match all volumes whose name contains this substring.
`--summary`	Print a summary of volumes by state and by type instead of the full list.
`--page-size`	Number of records each API call returns. ZCLI still retrieves the full list; a smaller page size makes more calls that are each less likely to time out.
`--project`	List only volumes in this project.
`--edge-node`	List only volumes on this edge node. Requires `--project`.
`--edge-node-cluster`	Intended to list only volumes on this node cluster. Requires `--project`. ZCLI currently does not apply this filter (see the following note).

Example (list all volumes):

zcli volume-instance show

Example (list the volumes on one node):

zcli volume-instance show --project=MY_PROJECT --edge-node=MY_NODE

Example response:

VolumeInstance    Project      Edge Node    Type
--------------    --------     ---------    -----
MY_VOLUME         MY_PROJECT   MY_NODE      Blockstorage
MY_IMAGE_VOLUME   MY_PROJECT   MY_NODE      Content_tree

ZCLI currently does not apply the --edge-node-cluster filter. ZCLI checks that the cluster exists, but zcli volume-instance show --project=MY_PROJECT --edge-node-cluster=MY_CLUSTER returns every volume in MY_PROJECT.

Example (match volumes by name substring):

zcli volume-instance show --name-pattern=MY_VOL

Example (show one volume in detail):

zcli volume-instance show MY_VOLUME --detail

Example response:

Volume Instance Name: MY_VOLUME
Volume Instance ID: 3f2c9a1e-7b4d-4c6e-9a1f-2d8e5b7c4a10
Volume Instance Title: MY_VOLUME
Volume Instance Description: MY_VOLUME

Type: Blockstorage
Access Mode: READWRITE
Volume Inst size: 10.0 GB
Project: MY_PROJECT
Edge Node: MY_NODE
isMultiattached: False
isImplicit: False

Opstate: Online
Volume Inst size Status: currSize: 1.2 GB , maxSize: 10.0 GB

Version: 1
Created at: Mon Oct 06 2025 09:14:22 AM
Created By: user@zededa.com
Last Updated at: Mon Oct 06 2025 09:14:22 AM
Last Updated By: user@zededa.com

Update a volume

You can update only the title and description of a volume. The name, type, access mode, size, and assigned node cannot be changed after creation. If you pass neither flag, ZCLI reports that there is nothing to update.

zcli volume-instance update <name> [--title=<title>] [--description=<description>]

Example:

zcli volume-instance update MY_VOLUME --title=MY_NEW_VOLUME_TITLE

Delete a volume

Deleting a volume releases its storage on the node. A volume cannot be deleted while it is attached to more than one application instance; detach it from those applications first. Without -f, ZCLI prompts you to confirm.

zcli volume-instance delete <name> [-f]

Example:

zcli volume-instance delete MY_VOLUME

Example response:

Delete volume-instance MY_VOLUME? [Y/N]: Y

The -f flag forces deletion without a confirmation prompt.

zcli volume-instance delete MY_VOLUME -f

Next Steps

Create Volumes

Create image and block storage volumes using the console GUI.

Manage Volumes

View, update, and delete volumes using the console GUI.

Attach Volumes to Multiple Applications

Share one block storage volume between edge applications on the same node.

Overview

All ZCLI command procedures, organized by resource type.

Get started

Infrastructure

Applications

Monitoring and Usage

Administration and Marketplace

Manage Volumes

Before You Start

Volume Types and Access Modes

Manage Volumes

Create a volume

View volumes

Update a volume

Delete a volume

Next Steps

Create Volumes

Manage Volumes

Attach Volumes to Multiple Applications

Overview

​Before You Start

​Volume Types and Access Modes

​Manage Volumes

​Create a volume

​View volumes

​Update a volume

​Delete a volume

​Next Steps

Create Volumes

Manage Volumes

Attach Volumes to Multiple Applications

Overview

Before You Start

Volume Types and Access Modes

Manage Volumes

Create a volume

View volumes

Update a volume

Delete a volume

Next Steps