knot.volume
The knot.volume library provides volume management functions. Volumes are standalone volume definitions that spaces can mount: on local container platforms (docker, podman, apple, container) a named container volume, and on Nomad a CSI or host volume. CSI volumes exist only on Nomad. See Volumes for the definition formats.
Execution Environment
| Environment | Behaviour |
|---|---|
Embedded (MCP tool execution, event sinks, plugin handlers, remote/space scripts, knot run-script) |
Available; authenticated automatically via the Go-provided knot.apiclient transport. |
| Health check scripts | Only when the space’s environment sets KNOT_API_PORT or KNOT_URL/KNOT_TOKEN: there is no built-in transport, so the Python knot.apiclient configures itself from the agent (as the space owner) or those variables, and calls raise otherwise. See Environment Compatibility. |
| External (standalone scripts) | Python implementation; configure knot.apiclient first (or set the KNOT_* environment variables). |
Functions
| Function | Description |
|---|---|
list() |
List all volumes |
get(volume_id) |
Get volume by ID or name |
nodes(platform) |
List available nodes for a platform |
validate(platform, definition) |
Validate a volume definition without saving |
create(name, definition, platform='', node_id='') |
Create a new volume |
update(volume_id, name=None, definition=None, platform=None, node_id=None) |
Update volume properties; None keeps the current value. Returns True |
delete(volume_id) |
Delete a volume |
start(volume_id) |
Start a volume |
stop(volume_id) |
Stop a volume |
is_running(volume_id) |
Check if volume is running |
Usage
import knot.volume as volume
# List all volumes
volumes = volume.list()
for v in volumes:
status = "active" if v['active'] else "inactive"
print(f"{v['name']}: {status} ({v['platform']}) node={v['node_hostname']}")
# List available nodes for docker platform
nodes = volume.nodes("docker")
for n in nodes:
print(f"{n['hostname']} ({n['node_id']})")
# A local-container volume definition: a volumes map with exactly one volume
definition = "volumes:\n my_data:\n"
# Validate a volume definition first
result = volume.validate("docker", definition)
print(result["valid"])
# Create a volume on a specific node
volume_id = volume.create(
"my-volume",
definition=definition,
platform="docker",
node_id=nodes[0]['node_id']
)
# Create a volume with auto node selection
volume_id = volume.create(
"other-volume",
definition="volumes:\n other_data:\n",
platform="docker"
)
# Start a volume
volume.start("my-volume")
# Check if running
if volume.is_running("my-volume"):
print("Volume is active")
# Stop a volume
volume.stop("my-volume")Volume Properties
Volumes contain:
id- Volume IDname- Volume namedefinition- Volume definition YAML (fromget()only)active- Whether the volume is active/runningzone- Zone where volume is runningnode_id- ID of the node the volume is assigned tonode_hostname- Hostname of the node the volume is assigned toplatform- Platform type (docker, podman, nomad, etc.)
Node Properties
Nodes returned by nodes() contain:
node_id- Node IDhostname- Node hostname
Validation
validate(platform, definition) returns:
valid- Whether the volume definition is validerrors- List of validation errors withfieldandmessage, plusline(the 1-based line in the definition) when the problem can be placed. The key is absent when the definition is valid, so read it with.get("errors", [])
Definition Format
The volume definition is a YAML string, and its shape depends on the platform.
On the local container platforms (docker, podman, apple, container) it is a top-level volumes map holding exactly one volume (Docker and Podman also accept a driver and driver_opts, e.g. for NFS; Apple accepts a size):
volumes:
my_data:On Nomad it is a volumes list with exactly one CSI (plugin_id, capacities, mount options) or host volume:
volumes:
- id: "test_home"
name: "test_home"
plugin_id: "hostpath"
capacity_min: 10G
capacity_max: 10GSee Volumes for the full formats.