Docker — volume/inspect

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.

When to Use

Pre-attach verification: Confirm that a volume exists and retrieve its mountpoint before attaching it to a new container via container/create.
Label metadata retrieval: Read custom labels such as tenant_id or created_by to pass metadata downstream in a provisioning or audit workflow.
Driver configuration audit: Verify that the correct volume driver and driver options are configured, especially for NFS or cloud-backed volumes.
External backup targeting: Retrieve the Mountpoint path to pass to an external backup agent that operates directly on the host filesystem.

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

Operation Fields

Field	Type	Badge	Description
`Name`	string	required	Volume name to inspect.

Sample Configuration

{
  "resource": "volume",
  "operation": "inspect",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket"
  },
  "Name": "db-tenant-0042"
}

Validation Errors

Error Code	Condition	Resolution
`MISSING_INPUT`	`Name` field is empty.	Provide the volume name to inspect.
`NOT_FOUND`	Volume does not exist on the host.	Create the volume with `volume/create` or verify the name.
`CONFIG_ERROR`	Connection settings malformed.	Check `dockerHost` and `connectionType`.
`AUTH_FAILED`	TLS handshake failed.	Verify certificates in `tlsCertPath`.

Output

Success Port

Field	Type	Description
`status`	string	`"ok"` on success.
`resource`	string	`"volume"`
`operation`	string	`"inspect"`
`volumeInfo.Name`	string	Volume name.
`volumeInfo.Driver`	string	Volume driver (e.g., `local`).
`volumeInfo.Mountpoint`	string	Host filesystem path where volume data resides.
`volumeInfo.Labels`	object	Key-value label pairs.
`volumeInfo.CreatedAt`	string	ISO 8601 creation timestamp.
`volumeInfo.Scope`	string	`"local"` or `"global"` (Swarm).
`volumeInfo.Status`	object	Driver-specific status information (driver-dependent).

Error Port

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

Sample Output

{
  "status": "ok",
  "resource": "volume",
  "operation": "inspect",
  "volumeInfo": {
    "Name": "db-tenant-0042",
    "Driver": "local",
    "Mountpoint": "/var/lib/docker/volumes/db-tenant-0042/_data",
    "Labels": {
      "tenant_id": "0042",
      "created_by": "tenant-provisioning-workflow",
      "env": "prod"
    },
    "CreatedAt": "2026-05-01T08:30:00Z",
    "Scope": "local",
    "Status": {}
  }
}

Expression Reference

Expression	Returns
`{{ $output.volumeInfo.Name }}`	Volume name — pass to `container/create` mount configuration.
`{{ $output.volumeInfo.Mountpoint }}`	Host path — feed to external backup agent.
`{{ $output.volumeInfo.Labels['tenant_id'] }}`	Tenant ID label value.
`{{ $output.volumeInfo.CreatedAt }}`	Creation timestamp — use for age-based cleanup decisions.
`{{ $output.volumeInfo.Scope }}`	`"local"` or `"global"` — distinguish Swarm global volumes.

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 }}`.
Never interpolate user input into the Name field	Volume names must come from trusted workflow variables, not raw user input.
Handle NOT_FOUND gracefully	Route the `NOT_FOUND` error port to a `volume/create` branch for idempotent setup workflows.
Never remove volumes without confirming backup	Volume data is permanently deleted on removal. Confirm backup before any downstream `volume/remove` call.
Restrict container/exec to approved commands	Arbitrary exec access is root-equivalent. GuardRail exec policies restrict allowed command prefixes.

Examples

Example 1 — Verify Before Attach

Before creating a container, inspect the target volume to confirm it exists and retrieve its name for the mount binding. Route to volume/create if not found.

{
  "resource": "volume",
  "operation": "inspect",
  "Name": "db-tenant-{{ $vars.tenantId }}"
}
// Success port → container/create using volumeInfo.Name
// Error port (NOT_FOUND) → volume/create then retry

Example 2 — Retrieve Mountpoint for Backup

Get the host-filesystem path of a tenant database volume and submit it to an external backup scheduler via an HTTP Request node.

// After volume/inspect:
{
  "url": "https://backup.internal/api/schedule",
  "method": "POST",
  "body": {
    "sourcePath": "{{ $node['volume-inspect'].output.volumeInfo.Mountpoint }}",
    "tenantId": "{{ $node['volume-inspect'].output.volumeInfo.Labels.tenant_id }}"
  }
}

Example 3 — Label-Based Metadata Read

During a tenant offboarding workflow, inspect the tenant's volume to read its metadata labels and record them in the audit log before proceeding to backup and removal.

// Read tenant metadata from volume labels:
{
  "tenant_id": "{{ $output.volumeInfo.Labels.tenant_id }}",
  "created_by": "{{ $output.volumeInfo.Labels.created_by }}",
  "mountpoint": "{{ $output.volumeInfo.Mountpoint }}",
  "created_at": "{{ $output.volumeInfo.CreatedAt }}"
}