Docker — volume/list

About Docker volumes: Docker volumes provide persistent storage that survives container restarts and removal. Volumes are managed by Docker, not the host filesystem — they are stored in /var/lib/docker/volumes/ by default and must be explicitly removed to free disk space.

When to Use

Orphan audit: Enumerate all volumes on the host and cross-reference against running containers to identify volumes no longer attached to any container — these are candidates for cleanup.
Pre-migration inventory: List all named volumes before a host migration to plan which volumes need data transfer or backup before decommissioning the host.
Dependency verification: Before starting a stack of dependent services, verify that all required named data volumes already exist on the host.
Storage accounting: List volumes with their mountpoints to feed into a disk-usage calculation job for capacity planning.
Convention-based backup targeting: Find all volumes whose names match a naming convention (e.g., all names starting with db-) to add to a scheduled backup workflow.

Configuration

Connection

Field	Type	Default	Description
`dockerHost`	string	`unix:///var/run/docker.sock`	Docker daemon socket path or TCP endpoint.
`connectionType`	string	`unixsocket`	One of: `unixsocket`, `tcp`, `tcptls`.
`tlsCertPath`	string	—	TLS certificate directory. Required for `tcptls`. optional
`timeoutSeconds`	int	30	Operation timeout in seconds. optional

Operation Fields

This operation requires no additional input fields. Set resource to volume and operation to list.

Sample Configuration

{
  "resource": "volume",
  "operation": "list",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket"
  }
}

Validation Errors

Error Code	Condition	Resolution
`CONFIG_ERROR`	Connection settings missing or malformed.	Verify `dockerHost` and `connectionType`.
`AUTH_FAILED`	TLS handshake failed.	Confirm `tlsCertPath` points to a valid cert directory.
`DOCKER_API_ERROR`	Daemon returned an unexpected error.	Check Docker daemon logs on the host.

Output

Success Port

Field	Type	Description
`status`	string	`"ok"` on success.
`resource`	string	`"volume"`
`operation`	string	`"list"`
`listVolumes`	array	Array of volume summary objects.
`listVolumes[].Name`	string	Volume name (user-specified or auto-generated hex string).
`listVolumes[].Driver`	string	Volume driver (e.g., `local`, `nfs`).
`listVolumes[].Mountpoint`	string	Host filesystem path where the volume data is stored.
`listVolumes[].Labels`	object	Key-value label pairs applied to the volume.
`listVolumes[].CreatedAt`	string	ISO 8601 creation timestamp.

Error Port

Fires when the operation fails. Output contains status: "error", errorCode, and errorMessage.

Sample Output

{
  "status": "ok",
  "resource": "volume",
  "operation": "list",
  "listVolumes": [
    {
      "Name": "db-tenant-0042",
      "Driver": "local",
      "Mountpoint": "/var/lib/docker/volumes/db-tenant-0042/_data",
      "Labels": {
        "tenant_id": "0042",
        "created_by": "tenant-provisioning-workflow"
      },
      "CreatedAt": "2026-05-01T08:30:00Z"
    },
    {
      "Name": "app-uploads",
      "Driver": "local",
      "Mountpoint": "/var/lib/docker/volumes/app-uploads/_data",
      "Labels": {},
      "CreatedAt": "2026-04-15T12:00:00Z"
    }
  ]
}

Expression Reference

Expression	Returns
`{{ $output.listVolumes[0].Name }}`	Name of the first volume.
`{{ $output.listVolumes.length }}`	Total number of volumes on the host.
`{{ $output.listVolumes[0].Mountpoint }}`	Host path of the volume — use for external backup job targeting.
`{{ $output.listVolumes[0].Labels['tenant_id'] }}`	Custom label value (e.g., tenant ID).
`{{ $output.listVolumes[0].CreatedAt }}`	ISO 8601 creation time — use for age-based cleanup rules.

Node Policies & GuardRails

Policy	Enforcement
Never expose Docker daemon TCP without TLS	Use `tcptls` for remote connections. Plain `tcp` is blocked in production GuardRail profiles.
Store TLS certificates in Credentials Manager	Reference `tlsCertPath` via `{{ $credentials.dockerTlsCertPath }}`.
Use named volumes in workflows	Auto-generated volume names (hex strings) reduce workflow readability. Always assign meaningful names via `volume/create`.
Never remove volumes without confirming backup	Volume removal is irreversible. Downstream `volume/remove` nodes should only fire after backup confirmation.
Always handle the error port	Docker daemon may be unavailable. Workflows without error port wiring will silently fail on daemon downtime.
Restrict container/exec to approved commands	Arbitrary exec access is root-equivalent. GuardRail exec policies restrict allowed command prefixes.

Examples

Example 1 — Identify Orphaned Volumes

List all volumes and all containers, then find volume names not referenced in any container's mount configuration.

// Step 1 — volume/list to get all volume names
// Step 2 — container/list to get all containers
// Step 3 — Filter node: volumes whose Name does not appear in any container Mounts[].Name
// Step 4 — Loop: remove each orphan via volume/remove

Example 2 — Verify Required Volumes Before Stack Start

Before starting a multi-container application stack, verify all required data volumes exist. Abort with an error if any are missing.

// After volume/list:
{{ ['db-data', 'app-uploads', 'app-config'].every(
    name => $output.listVolumes.some(v => v.Name === name)
) }}

Example 3 — Backup Target Discovery

Find all volumes matching a db- naming prefix and submit each mountpoint to a backup scheduler.

// Filter expression to extract db- volumes:
{{ $output.listVolumes.filter(v => v.Name.startsWith('db-')) }}

// For each matched volume, pass Mountpoint to backup job:
{{ $loopItem.Mountpoint }}