Skip to main content
Version: v3.8.0

Workload volumes and lifecycle

How Edgelet stores microservice volume data on disk, what is removed when a workload is deleted, and how operators reclaim space.

Applies to all container engines. Embedded edgelet engine behavior is called out where it differs from Docker/Podman.

Why this matters​

On the embedded edgelet engine, a VOLUME mapping does not use Docker's volume subsystem. Edgelet creates a persistent directory under {diskDirectory}/volumes/data/ and bind-mounts it into the container.

Deleting a microservice removes the container, but usually not the volume data. Orphaned data is reclaimed by volume prune (scheduled or manual), not at delete time.

Operators who need immediate cleanup must run prune or delete the directories manually.

On-disk layout​

Base path: {diskDirectory} (default /var/lib/edgelet/).

volumes/
  data/{microservice-uuid}/{volume-name}/     # VOLUME-type persistent data (edgelet engine)
  microservices/{microservice-uuid}/          # Per-MS mount staging (secrets/configmaps)
  secrets/{volume-name}/                      # Controller secret payloads (shared)
  configMaps/{volume-name}/                   # Controller configmap payloads (shared)

Image layers and container filesystems live under /var/lib/edgelet-containerd/ (embedded engine), not under volumes/data/. Backing up edgelet.db alone does not back up VOLUME data. See Persistence.

Volume mapping types​

TypehostDestinationEdgelet behavior
VOLUMERelative name, e.g. mydataCreates {diskDirectory}/volumes/data/{ms-uuid}/mydata/ and bind-mounts it
VOLUME_MOUNTController volume nameMaterializes under volumes/microservices/{ms-uuid}/ from shared secrets/ or configMaps/ trees
BINDAbsolute host path, e.g. /opt/dataBind-mounts that path; Edgelet never deletes it

Local deploy manifests (edgelet deploy -f) support BIND and VOLUME only. Controller workloads may also use VOLUME_MOUNT for secrets and configmaps synced from the Controller.

What happens when a microservice is deleted​

Deletion paths:

  • Controller: microservice marked delete: true in Controller snapshot → process manager reconciles removal
  • Local: edgelet ms rm <id> or EdgeletAPI delete of a local workload

In all cases Edgelet:

  1. Stops and removes the container
  2. Runs volume-mount cleanup for that microservice UUID

Always removed​

PathWhen
Container / CRI sandboxOn delete
volumes/microservices/{uuid}/On delete (per-MS secret/configmap symlinks)

Not removed on delete​

PathReason
volumes/data/{uuid}/VOLUME data is intentionally persistent until prune
volumes/secrets/, volumes/configMaps/Shared controller artifacts; other workloads may still reference them
BIND host pathsOperator-managed; Edgelet does not touch them

deleteWithCleanup (controller workloads)​

When the Controller sets deleteWithCleanup: true on a microservice:

EngineEffect
docker / podmanContainer remove may pass RemoveVolumes to the engine; also removes the image when cleanup is requested
edgelet (embedded)deleteWithCleanup does not delete volumes/data/ — the engine ignores the cleanup flag for volumes. The main extra effect is image removal when cleanup is requested

Local edgelet ms rm always uses non-cleanup removal (container only; no automatic image or volume data delete).

When volume data is actually deleted​

Volume prune (embedded engine)​

PruneVolumes removes orphaned directories under volumes/data/{uuid}/ and volumes/microservices/{uuid}/ for any microservice UUID that has no running container.

Triggered by:

  • Scheduled prune (pruningFrequency in config) — runs containers → volumes → images
  • Manual prune:
edgelet system prune volumes
edgelet system prune all

Full deprovision (scope=all)​

Agent deprovision stops all workloads, then runs container and volume prune hooks. This is the broadest automatic cleanup short of wiping diskDirectory.

Manual cleanup​

sudo rm -rf /var/lib/edgelet/volumes/data/<microservice-uuid>

Or run edgelet system prune volumes to remove all orphaned volume trees.

Operator checklist​

GoalAction
Delete workload, keep data for redeployedgelet ms rm or controller delete — data remains under volumes/data/{uuid}/
Delete workload and reclaim disk soonedgelet system prune volumes or wait for scheduled prune
Backup stateful workloadsCopy edgelet.db and volumes/data/ (and BIND paths if used)
Wipe node completelyStop services, remove diskDirectory (see Persistence)

Troubleshooting​

Disk usage grows after microservices are deleted​

  1. List remaining volume data:

    sudo du -sh /var/lib/edgelet/volumes/data/*

  2. Confirm no container still references the UUID: edgelet ms ls

  3. Prune orphans: edgelet system prune volumes

Redeployed microservice has empty volume​

VOLUME data is keyed by microservice UUID. A new deployment with a new UUID gets a new directory. To preserve data across UUID changes, use BIND to a fixed host path you control.

See also​

Group 3See anything wrong with the document? Help us improve it!

Edit this page on GitHub!