> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Manage Volumes

> Use ZCLI commands to create, view, update, and delete volumes on edge nodes and node clusters from the command line.

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](https://zededa.mintlify.site/zcli-reference/get-started.md).
* You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).
* 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](https://zededa.mintlify.site/new-ui/infrastructure-services/node-volumes-overview.md), [Create Volumes](https://zededa.mintlify.site/new-ui/infrastructure-services/volumes/create-volumes.md), and [Manage Volumes](https://zededa.mintlify.site/new-ui/infrastructure-services/volumes/manage-volumes.md).

## 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. |

## Manage Volumes

### 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.

```text theme={"dark"}
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):

```text theme={"dark"}
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):

```text theme={"dark"}
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):

```text theme={"dark"}
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](https://zededa.mintlify.site/new-ui/infrastructure-services/volumes/attach-volumes-to-multiple-applications.md).

### 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`.

```text theme={"dark"}
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):

```text theme={"dark"}
zcli volume-instance show
```

Example (list the volumes on one node):

```text theme={"dark"}
zcli volume-instance show --project=MY_PROJECT --edge-node=MY_NODE
```

Example response:

```text theme={"dark"}
VolumeInstance    Project      Edge Node    Type
--------------    --------     ---------    -----
MY_VOLUME         MY_PROJECT   MY_NODE      Blockstorage
MY_IMAGE_VOLUME   MY_PROJECT   MY_NODE      Content_tree
```

> [!NOTE]
>
> 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):

```text theme={"dark"}
zcli volume-instance show --name-pattern=MY_VOL
```

Example (show one volume in detail):

```text theme={"dark"}
zcli volume-instance show MY_VOLUME --detail
```

Example response:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli volume-instance update <name> [--title=<title>] [--description=<description>]
```

Example:

```text theme={"dark"}
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.

```text theme={"dark"}
zcli volume-instance delete <name> [-f]
```

Example:

```text theme={"dark"}
zcli volume-instance delete MY_VOLUME
```

Example response:

```text theme={"dark"}
Delete volume-instance MY_VOLUME? [Y/N]: Y
```

The `-f` flag forces deletion without a confirmation prompt.

```text theme={"dark"}
zcli volume-instance delete MY_VOLUME -f
```

## Next Steps

> [card] [Create Volumes](https://zededa.mintlify.site/new-ui/infrastructure-services/volumes/create-volumes.md)
>
> Create image and block storage volumes using the console GUI.

> [card] [Manage Volumes](https://zededa.mintlify.site/new-ui/infrastructure-services/volumes/manage-volumes.md)
>
> View, update, and delete volumes using the console GUI.

> [card] [Attach Volumes to Multiple Applications](https://zededa.mintlify.site/new-ui/infrastructure-services/volumes/attach-volumes-to-multiple-applications.md)
>
> Share one block storage volume between edge applications on the same node.

> [card] [Overview](https://zededa.mintlify.site/zcli-reference/overview.md)
>
> All ZCLI command procedures, organized by resource type.