Docker — volume/create

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. If a volume with the given name already exists, Docker returns the existing volume without error — making this operation idempotent.

When to Use

Tenant provisioning: Create a named database volume for each new customer during an onboarding workflow, naming it with the tenant ID for easy identification and targeted backup.
Deployment setup: Create all required application data volumes before calling container/create, ensuring the deployment fails fast at the volume stage rather than at container start.
Backup destination: Create a named volume as the backup destination to mount in a database container, isolating backup data from application data.
Shared storage: Create a named volume that multiple containers in the same service will mount read-write for shared file access (e.g., uploaded assets).

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	optional	Volume name. If omitted, Docker generates a random hex name. Always provide a meaningful name in production workflows.
`Driver`	string	optional	Volume driver to use (e.g., `local`, `nfs`, `convoy`). Defaults to `local`.
`Labels`	string	optional	JSON object of key-value label pairs to apply to the volume (e.g., `{"tenant_id":"0042","env":"prod"}`).

Sample Configuration

{
  "resource": "volume",
  "operation": "create",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket"
  },
  "Name": "db-tenant-{{ $vars.tenantId }}",
  "Driver": "local",
  "Labels": "{\"tenant_id\":\"{{ $vars.tenantId }}\",\"created_by\":\"provisioning-workflow\",\"env\":\"prod\"}"
}

Validation Errors

Error Code	Condition	Resolution
`CONFIG_ERROR`	Connection settings malformed.	Check `dockerHost` and `connectionType`.
`DOCKER_API_ERROR`	Invalid volume name (contains illegal characters) or driver not installed.	Use only alphanumeric characters, hyphens, and underscores in volume names. Ensure the driver plugin is installed.
`AUTH_FAILED`	TLS handshake failed.	Verify `tlsCertPath` contains valid certificates.

Output

Success Port

Field	Type	Description
`status`	string	`"ok"` on success (also returned if volume already exists).
`resource`	string	`"volume"`
`operation`	string	`"create"`
`volumeInfo.Name`	string	Volume name (generated or provided).
`volumeInfo.Driver`	string	Driver used for this volume.
`volumeInfo.Mountpoint`	string	Host filesystem path of the volume data directory.
`volumeInfo.CreatedAt`	string	ISO 8601 creation timestamp.

Error Port

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

Sample Output

{
  "status": "ok",
  "resource": "volume",
  "operation": "create",
  "volumeInfo": {
    "Name": "db-tenant-0042",
    "Driver": "local",
    "Mountpoint": "/var/lib/docker/volumes/db-tenant-0042/_data",
    "CreatedAt": "2026-05-26T09:15:00Z"
  }
}

Expression Reference

Expression	Returns
`{{ $output.volumeInfo.Name }}`	The volume name — pass to `container/create` for the mount binding.
`{{ $output.volumeInfo.Mountpoint }}`	Host path — use for external backup job targeting.
`{{ $output.volumeInfo.CreatedAt }}`	Creation timestamp — store in tenant record for audit purposes.

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 }}`.
Always name volumes in production workflows	Auto-generated names create operational blind spots. Provide a meaningful `Name` in all production `volume/create` calls.
Apply labels for metadata tracking	Use `Labels` to store tenant ID, environment, and workflow origin — this enables targeted backup and cleanup operations.
Never remove volumes without confirming backup	Volume data is permanently deleted on removal. Downstream `volume/remove` nodes must only fire after backup confirmation.
Restrict container/exec to approved commands	Arbitrary exec access is root-equivalent. GuardRail exec policies restrict allowed command prefixes.

Examples

Example 1 — Tenant Provisioning Workflow

When a new tenant is onboarded, create a dedicated database volume named with the tenant ID, then create and start the tenant's database container mounting that volume.

// Step 1 — volume/create
{
  "resource": "volume",
  "operation": "create",
  "Name": "db-tenant-{{ $trigger.tenantId }}",
  "Labels": "{\"tenant_id\":\"{{ $trigger.tenantId }}\",\"env\":\"prod\"}"
}

// Step 2 — container/create
{
  "resource": "container",
  "operation": "create",
  "Image": "postgres:16",
  "Name": "db-{{ $trigger.tenantId }}",
  "Volumes": "{{ $node['volume-create'].output.volumeInfo.Name }}:/var/lib/postgresql/data"
}

Example 2 — Idempotent Pre-Deploy Setup

In a deployment workflow, always attempt to create the required volumes. Since volume creation is idempotent (returns existing volume if already present), this step is safe to re-run.

// These three volume/create nodes can run in parallel:
{ "Name": "app-uploads", "Driver": "local" }
{ "Name": "app-config",  "Driver": "local" }
{ "Name": "app-cache",   "Driver": "local" }

// Then proceed to container/create only after all three succeed.

Example 3 — NFS-Backed Shared Volume

Create a volume backed by an NFS mount for shared storage across multiple containers on the same host.

{
  "resource": "volume",
  "operation": "create",
  "Name": "shared-assets",
  "Driver": "local",
  "Labels": "{\"type\":\"nfs-backed\",\"nfs_server\":\"nfs.internal\"}"
}