Documentation Index
Fetch the complete documentation index at: https://mintlify.com/fussybeaver/bollard/llms.txt
Use this file to discover all available pages before exploring further.
Nodes are Engine instances participating in a Docker Swarm. Bollard exposes full node management through the Docker client, allowing you to list, inspect, update availability/role, and delete nodes. All methods are async and return Result<T, bollard::errors::Error>.
Swarm mode must be enabled and the client must connect to a manager node for all node API calls.
list_nodes
Retrieve all nodes visible to the swarm manager, with optional filtering.
pub async fn list_nodes(
&self,
options: Option<ListNodesOptions>,
) -> Result<Vec<Node>, Error>
Options — ListNodesOptionsBuilder
| Builder method | Description |
|---|
.filters(&HashMap<&str, Vec<&str>>) | Filter by id, label, membership (accepted | pending), name, or role (manager | worker). |
Returns
Result<Vec<Node>, Error>
Example
use bollard::Docker;
use bollard::query_parameters::ListNodesOptionsBuilder;
use std::collections::HashMap;
#[tokio::main]
async fn main() -> Result<(), bollard::errors::Error> {
let docker = Docker::connect_with_socket_defaults()?;
let mut filters = HashMap::new();
filters.insert("role", vec!["manager"]);
let options = ListNodesOptionsBuilder::default()
.filters(&filters)
.build();
let nodes = docker.list_nodes(Some(options)).await?;
for node in &nodes {
println!("{:?}", node.id);
}
Ok(())
}
inspect_node
Fetch detailed information about a single node by its ID or name.
pub async fn inspect_node(
&self,
node_name: &str,
) -> Result<Node, Error>
Returns
Result<Node, Error> — a Node model containing id, version, created_at, updated_at, spec, description, and status.
Example
use bollard::Docker;
#[tokio::main]
async fn main() -> Result<(), bollard::errors::Error> {
let docker = Docker::connect_with_socket_defaults()?;
let node = docker.inspect_node("my-node-id").await?;
println!("Hostname: {:?}", node.description
.as_ref()
.and_then(|d| d.hostname.as_ref()));
println!("Status: {:?}", node.status);
Ok(())
}
delete_node
Remove a node from the swarm. By default this only succeeds for nodes in a down state; pass force: true to remove an active node.
pub async fn delete_node(
&self,
node_name: &str,
options: Option<DeleteNodeOptions>,
) -> Result<(), Error>
Options — DeleteNodeOptionsBuilder
| Builder method | Type | Description |
|---|
.force(bool) | bool | Force-remove the node even if it is still active. |
Returns
Result<(), Error>
Example
use bollard::Docker;
use bollard::query_parameters::DeleteNodeOptionsBuilder;
#[tokio::main]
async fn main() -> Result<(), bollard::errors::Error> {
let docker = Docker::connect_with_socket_defaults()?;
let options = DeleteNodeOptionsBuilder::default()
.force(true)
.build();
docker.delete_node("my-node-id", Some(options)).await?;
println!("Node removed");
Ok(())
}
Force-deleting a manager node without first demoting it may reduce manager quorum. Always demote managers with update_node before removing them.
update_node
Change a node’s role or availability. You must supply the current version index to prevent lost-update races.
pub async fn update_node(
&self,
node_id: &str,
spec: NodeSpec,
options: UpdateNodeOptions,
) -> Result<(), Error>
Options — UpdateNodeOptionsBuilder
| Builder method | Type | Description |
|---|
.version(i64) | i64 | Required. Current version index from inspect_node. |
Key NodeSpec fields
| Field | Type | Description |
|---|
name | Option<String> | Human-readable label for the node. |
role | Option<NodeSpecRoleEnum> | MANAGER or WORKER. |
availability | Option<NodeSpecAvailabilityEnum> | ACTIVE, PAUSE, or DRAIN. |
labels | Option<HashMap<String, String>> | Arbitrary key/value labels for scheduling constraints. |
Returns
Result<(), Error>
Example
use bollard::Docker;
use bollard::query_parameters::UpdateNodeOptionsBuilder;
use bollard::models::{NodeSpec, NodeSpecAvailabilityEnum, NodeSpecRoleEnum};
#[tokio::main]
async fn main() -> Result<(), bollard::errors::Error> {
let docker = Docker::connect_with_socket_defaults()?;
let node_id = "my-node-id";
// Always fetch current version before updating
let current = docker.inspect_node(node_id).await?;
let version = current.version.unwrap().index.unwrap();
let spec = NodeSpec {
role: Some(NodeSpecRoleEnum::WORKER),
availability: Some(NodeSpecAvailabilityEnum::DRAIN),
name: Some("draining-worker".to_string()),
..Default::default()
};
let options = UpdateNodeOptionsBuilder::default()
.version(version)
.build();
docker.update_node(node_id, spec, options).await?;
println!("Node drained");
Ok(())
}
Set availability to DRAIN before removing a worker node. This gracefully reschedules all running tasks to other nodes before the delete.
