delonix volume

Volumes nomeados e bind mounts: create, ls, inspect, rm, apply.

Named volumes and bind mounts: create, ls, inspect, rm, apply.

Wrapper fino sobre o VolumeStore. No container run, -v nome:/destino[:ro] resolve para um volume nomeado (criado on-demand) e -v /host:/destino[:ro] para um bind mount — a distinção é automática.

Duas formas de create: um driver com as suas opções (--driver/--opt, ao estilo docker volume create — local por omissão, ou NFS/CIFS/SMB/WebDAV com credenciais do cofre), ou uma fatia isolada e com quota talhada de um volume já existente (--parent).

A thin wrapper over VolumeStore. In container run, -v name:/dest[:ro] resolves to a named volume (created on demand) and -v /host:/dest[:ro] to a bind mount — the distinction is automatic.

Two shapes of create: a driver with its options (--driver/--opt, Docker's own docker volume create idiom — local by default, or NFS/CIFS/SMB/WebDAV with vault credentials), or an isolated, quota'd slice carved out of an already-existing volume (--parent).

📄 Implementação real em Rust: cmd/volume.rs

Usage: delonix volume [OPTIONS] <COMMAND>

Commands:
  create    Create a named volume
  rm        Remove a volume
  describe  Readable detail of one or more volumes, `kubectl describe` style
  inspect   Details of a volume (includes real on-disk usage)
  ls        List the volumes
  apply     Apply the `kind: Volume` documents from a manifest (idempotent by name)
  prune     DESTROY every local volume that nothing references
  snapshot  Point-in-time snapshots of a volume (tar.gz under the volume; safe in rootless)
  help      Print this message or the help of the given subcommand(s)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

COMMAND MAP:
  Lifecycle    create · rm
  Inspect      ls · inspect · describe
  Declarative  apply
  Maintenance  prune · snapshot

EXAMPLES:
  # a named volume, so the data outlives the container that writes to it
  delonix volume create pgdata

  # what exists, with driver and mountpoint
  delonix volume ls

  # how much disk one of them really holds, measured from inside the userns
  delonix volume inspect pgdata

SEE ALSO:
  delonix container run · delonix volume create · delonix volume snapshot ·
  delonix dashboard

  delonix › volume

`volume snapshot`

Point-in-time snapshots of a volume (tar.gz under the volume; safe in rootless)

Usage: delonix volume snapshot [OPTIONS] <COMMAND>

Commands:
  create   Create a snapshot NOW (default name: UTC timestamp)
  rm       Delete a snapshot
  ls       List the snapshots of a volume
  restore  Restore a snapshot INTO the volume (replaces the current data — stop the consumers first)
  help     Print this message or the help of the given subcommand(s)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

COMMAND MAP:
  Lifecycle    create · rm
  Inspect      ls
  Maintenance  restore

EXAMPLES:
  # freeze the current contents of a volume as a tar.gz, safe in rootless
  delonix volume snapshot create pgdata

  # what has been kept, and when
  delonix volume snapshot ls pgdata

SEE ALSO:
  delonix volume inspect · delonix volume rm · delonix vm snapshot

  delonix › volume › snapshot

ExemplosExamples

Tirar e listar snapshots de um volume

Take and list a volume's snapshots

delonix volume snapshot create dados antes-da-migracao
delonix volume snapshot ls dados

Voltar a um snapshot (o conteúdo actual do volume é substituído)

Roll back to a snapshot (the volume's current contents are replaced)

delonix volume snapshot restore dados antes-da-migracao

Apagar um snapshot que já não serve

Delete a snapshot that is no longer useful

delonix volume snapshot rm dados antes-da-migracao

`volume describe`

Readable detail of one or more volumes, kubectl describe style.

For humans; use inspect for the usual compact view.

Usage: delonix volume describe [OPTIONS] <NAMES>...

Arguments:
  <NAMES>...
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -n, --namespace <NAMESPACE>
          Namespace that owns them (default: the unscoped root)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # a kubectl-style block, meant to be read rather than parsed
  delonix volume describe pgdata

  # several at once, to compare them side by side
  delonix volume describe pgdata backups

SEE ALSO:
  delonix volume inspect · delonix volume ls · delonix volume rm

  delonix › volume › describe

ExemplosExamples

Detalhe de um volume (uso, quota, montagens)

Volume detail (usage, quota, mounts)

delonix volume describe dados

`volume create`

Create a named volume.

Two shapes, and a document may use only one: a driver + its options (--driver/--opt), or a quota'd slice of an already-existing volume (--parent) — the same two the kind: Volume manifest accepts as nfs:/cifs:/webdav: and share: blocks.

Usage: delonix volume create [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --driver <DRIVER>
          Volume driver: `local` (default, a plain local directory) | `nfs` | `cifs`/`smb` (Samba/Windows) | `webdav` (Nextcloud/ownCloud).
          
          Non-local drivers are configured entirely through `--opt` — the same idiom `docker volume create --driver <name> --opt k=v` uses, and one flag family instead of the two this used to have (`--type`+`--server`/`--share` for the network form, `--driver nfs`+`--device` for the raw one — the same information written twice two different ways).
          
          [default: local]

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --opt <KEY=VALUE>
          Driver option, `key=value`. Repeatable. For `nfs`/`cifs`/`smb`/ `webdav`: `server` (required — host/IP, or the base URL for `webdav`), `share` (required — NFS path, CIFS share name, or the WebDAV URL path), `username`, `password` (prefer `password-secret`), `password-secret` (vault secret with a `password` key), `ro=true` (mount read-only), `options` (extra mount options, e.g. `vers=4.1,soft`)

      --quota <QUOTA>
          Quota (e.g. `2g`) — only applied if `--quota` is given

      --alert-pct <ALERT_PCT>
          Usage percentage above which `ls`/`describe` flag a WARN (default 90)

      --parent <PARENT>
          Carve this volume out of an ALREADY-EXISTING one (a quota'd, isolated subdirectory — what `kind: ShareVolume` used to be a Kind of its own for). Mounts nothing of its own: exclusive with `--driver`/`--opt`

  -n, --namespace <NAMESPACE>
          Namespace that will own the share (default: the unscoped root) — only with `--parent`

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # a local named volume — the default driver
  delonix volume create pgdata

  # with a size cap, so one workload cannot fill the whole disk
  delonix volume create pgdata --quota 20g

  # a NAS export becomes a named volume any container can mount
  delonix volume create nas --driver nfs --opt server=10.0.0.5 --opt share=/mnt/pool/media

  # an SMB share with the password read from the vault, never from the shell
  # history
  delonix volume create backups --driver smb --opt server=nas.local --opt share=backups --opt username=delonix --opt password-secret=nas-creds

  # an isolated, individually-quota'd slice carved out of an already-mounted
  # volume
  delonix volume create app-data --parent nas --quota 5g

SEE ALSO:
  delonix volume ls · delonix volume inspect · delonix secret create · delonix
  container run

  delonix › volume › create

ExemplosExamples

Com quota, driver local por omissão

With quota and the nfs driver available

delonix volume create dados --quota 10G

NFS de um TrueNAS, montado directamente como volume

NFS from a TrueNAS, mounted straight as a volume

delonix volume create media --driver nfs --opt server=10.0.0.5 --opt share=/mnt/pool/media

SMB/CIFS com a password do cofre, nunca do argv

SMB/CIFS with the password from the vault, never from argv

delonix volume create docs --driver cifs --opt server=nas --opt share=docs --opt username=user --opt password-secret=nas-pass

Uma fatia isolada e com quota própria de um volume já existente

An isolated, individually-quota'd slice of an already-existing volume

delonix volume create tenant-a --parent media --quota 1G

`volume ls`

List the volumes

Usage: delonix volume ls [OPTIONS]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -o, --output <OUTPUT>
          Output format: `table` (default) or `json` (ADR-0005)
          
          [default: table]
          [possible values: table, json]

  -n, --namespace <NAMESPACE>
          Show this namespace's volumes instead of the unscoped ones

  -A, --all-namespaces
          Every namespace at once, plus the unscoped root — a share that exists and is invisible is how an operator removes its parent believing nothing hangs off it (B5 CLI collapse: `sharevolume ls` always listed this way; `volume ls` now can too)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # every volume, with driver and mountpoint
  delonix volume ls

  # as JSON, for a backup job or a monitoring script
  delonix volume ls -o json

  # every namespace at once, so a share hanging off a parent is never
  # invisible
  delonix volume ls -A

SEE ALSO:
  delonix volume inspect · delonix volume describe · delonix volume create ·
  delonix system df

  delonix › volume › ls

ExemplosExamples

delonix volume ls

Todas as namespaces de uma vez — uma partilha nunca fica invisível

Every namespace at once — a share is never invisible

delonix volume ls -A

`volume inspect`

Details of a volume (includes real on-disk usage)

Usage: delonix volume inspect [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -o, --output <OUTPUT>
          Output format: `table` (default, the historical text) or `json` (ADR-0005)
          
          [default: table]
          [possible values: table, json]

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # driver, mountpoint, quota and the REAL usage — an unreadable directory is
  # reported as unknown, never as zero
  delonix volume inspect pgdata

SEE ALSO:
  delonix volume describe · delonix volume ls · delonix volume create

  delonix › volume › inspect

ExemplosExamples

delonix volume inspect dados

`volume rm`

Remove a volume.

Refuses while a container or a share carved out of it still references it (use --force to remove it anyway).

Usage: delonix volume rm [OPTIONS] <NAME>

Arguments:
  <NAME>
          

Options:
  -f, --force
          Remove it even with live references — DESTROYS the data of whatever is still using it

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --destroy-remote
          ALSO destroy the storage this volume was provisioned with on a remote NAS (`spec.provision`). Irreversible, and on another machine. Refused for a volume that only mounts a share someone else made

      --purge-data
          Also delete the data of a SHARE (a volume with a `--parent`) — the subdirectory it points at survives by default (the parent's data is not this command's to destroy). Refused on a volume that is not a share: its own removal already takes its data with it

  -n, --namespace <NAMESPACE>
          Namespace that owns it (default: the unscoped root)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # remove a volume nothing references any more
  delonix volume rm pgdata

  # force it past a live reference — this DESTROYS the data of whatever still
  # uses it
  delonix volume rm -f pgdata

  # un-register a share — the data on the parent is PRESERVED
  delonix volume rm app-data

  # un-register and delete the underlying subdirectory as well
  delonix volume rm app-data --purge-data

SEE ALSO:
  delonix volume ls · delonix volume snapshot create · delonix container rm ·
  delonix volume prune

  delonix › volume › rm

ExemplosExamples

delonix volume rm dados

Remove o registo de uma partilha; os DADOS ficam (a não ser que peças --purge-data)

Un-register a share's record; the DATA stays unless you ask for --purge-data

delonix volume rm tenant-a

`volume apply`

Apply the kind: Volume documents from a manifest (idempotent by name)

Usage: delonix volume apply [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # apply only the `kind: Volume` documents of a manifest, idempotent by name
  delonix volume apply -f delonix-manifest.yaml

  # the volumes of a shipped example, leaving the other kinds untouched
  delonix volume apply -f examples/volume.yaml

SEE ALSO:
  delonix stack apply · delonix stack plan · delonix volume create · delonix
  volume ls

  delonix › volume › apply

ExemplosExamples

delonix volume apply -f delonix-manifest.yaml

`volume prune`

DESTROY every local volume that nothing references.

This deletes data. It only takes a volume that is unreferenced by any container (running OR stopped), is not a share carved out of another volume, was not provisioned on a remote NAS, and uses the local driver. Anything else is kept and the reason is printed — a prune that silently skips is worse than one that refuses.

Usage: delonix volume prune [OPTIONS]

Options:
  -f, --force
          Skip the confirmation prompt (REQUIRED when stdin is not a terminal)

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --namespace <NAMESPACE>
          Sweep the volumes owned by THIS namespace, and nothing else.
          
          This is the teardown primitive: when a tenant is deleted its volumes stay on disk under its own namespace, where an unscoped prune never looks. Refused for a namespace that owns no volume — a filter that silently matches nothing is how a cleanup is believed to have run.

  -A, --all-namespaces
          Sweep the unscoped root AND every namespace

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # DESTROY every local volume nothing references — the data does not come
  # back
  delonix volume prune

  # in CI, where there is no terminal to confirm at
  delonix volume prune -f

  # reclaim the disk of a tenant that no longer exists — its volumes live
  # under its own namespace, where an unscoped prune never looks
  delonix volume prune --namespace acme -f

  # the whole store: the unscoped root AND every tenant
  delonix volume prune -A -f

SEE ALSO:
  delonix volume rm · delonix volume ls · delonix volume snapshot create ·
  delonix system prune

  delonix › volume › prune

ExemplosExamples

DESTRUIR todos os volumes locais que nada referencia (só a raiz sem dono)

delonix volume prune

Recuperar o disco de um inquilino que já não existe — os volumes dele vivem # no seu próprio namespace, onde um prune sem âmbito nunca olha

delonix volume prune --namespace acme -f

A loja inteira: a raiz sem dono E todos os inquilinos

delonix volume prune -A -f

LaboratórioLab

Prova que um volume nomeado sobrevive a um restart do container — ao contrário de escrever directamente no rootfs.

delonix volume create dados
delonix container run -d --name db -v dados:/var/lib/data alpine sleep infinity
delonix container exec db sh -c 'echo ok > /var/lib/data/marca'
delonix container stop db && delonix container start db
delonix container exec db cat /var/lib/data/marca

Prove a named volume survives a container restart — unlike writing straight to the rootfs.

delonix volume create data
delonix container run -d --name db -v data:/var/lib/data alpine sleep infinity
delonix container exec db sh -c 'echo ok > /var/lib/data/mark'
delonix container stop db && delonix container start db
delonix container exec db cat /var/lib/data/mark

DesafioChallenge

Tira um snapshot do volume dados depois de escrever nele, e usa volume describe para veres o histórico de snapshots.

Take a snapshot of the data volume after writing to it, and use volume describe to see the snapshot history.