0
# Node Management
1

2
Docker swarm node management for controlling worker and manager nodes in a swarm cluster. Nodes represent individual Docker daemons participating in the swarm, with capabilities for promotion, demotion, labeling, and availability control.
3

4
## Capabilities
5

6
### Node Inspection
7

8
Inspect node details including role, availability, and system information.
9

10
```python { .api }
11
def inspect(x: Union[str, List[str]]) -> Union[Node, List[Node]]:
12
    """
13
    Inspect one or more nodes in the swarm.
14
    
15
    Parameters:
16
    - x: Node name(s) or ID(s)
17
    
18
    Returns:
19
    Node object(s) with detailed information
20
    """
21
```
22

23
### Node Listing
24

25
List all nodes in the swarm cluster.
26

27
```python { .api }
28
def list() -> List[Node]:
29
    """
30
    List all nodes in the swarm.
31
    
32
    Returns:
33
    List of Node objects
34
    """
35
```
36

37
### Node Promotion and Demotion
38

39
Promote worker nodes to managers or demote managers to workers.
40

41
```python { .api }
42
def promote(x: Union[str, List[str]]) -> None:
43
    """
44
    Promote worker nodes to manager nodes.
45
    
46
    Parameters:
47
    - x: Node name(s) or ID(s) to promote
48
    """
49

50
def demote(x: Union[str, List[str]]) -> None:
51
    """
52
    Demote manager nodes to worker nodes.
53
    
54
    Parameters:
55
    - x: Node name(s) or ID(s) to demote
56
    """
57
```
58

59
### Node Updates
60

61
Update node configuration including availability, labels, and role.
62

63
```python { .api }
64
def update(
65
    node: Union[str, Node],
66
    availability: Optional[str] = None,
67
    labels_add: Optional[Dict[str, str]] = None,
68
    rm_labels: Optional[List[str]] = None,
69
    role: Optional[str] = None
70
) -> None:
71
    """
72
    Update node configuration.
73
    
74
    Parameters:
75
    - node: Node name, ID, or Node object
76
    - availability: Node availability (active, pause, drain)
77
    - labels_add: Labels to add to the node
78
    - rm_labels: Label keys to remove from the node
79
    - role: Node role (manager, worker)
80
    """
81
```
82

83
### Node Task Monitoring
84

85
List tasks running on specific nodes.
86

87
```python { .api }
88
def ps(x: Optional[Union[str, List[str]]] = None) -> List[Task]:
89
    """
90
    List tasks running on nodes.
91
    
92
    Parameters:
93
    - x: Node name(s) or ID(s) (current node if none specified)
94
    
95
    Returns:
96
    List of Task objects
97
    """
98
```
99

100
### Node Removal
101

102
Remove nodes from the swarm cluster.
103

104
```python { .api }
105
def remove(
106
    x: Union[str, List[str]], 
107
    force: bool = False
108
) -> None:
109
    """
110
    Remove nodes from the swarm.
111
    
112
    Parameters:
113
    - x: Node name(s) or ID(s) to remove
114
    - force: Force removal of nodes
115
    """
116
```
117

118
**Usage Examples:**
119

120
```python
121
from python_on_whales import docker
122

123
# List all nodes in swarm
124
nodes = docker.node.list()
125
for node in nodes:
126
    print(f"Node: {node.description.hostname} - Role: {node.spec.role}")
127

128
# Promote worker to manager
129
docker.node.promote("worker-01")
130

131
# Update node availability and add labels
132
docker.node.update(
133
    "node-01",
134
    availability="drain",
135
    labels_add={"maintenance": "true", "zone": "us-east-1a"}
136
)
137

138
# List tasks on specific node
139
tasks = docker.node.ps("manager-01")
140
for task in tasks:
141
    print(f"Task: {task.name} - Service: {task.service_id}")
142
```
143

144
## Types
145

146
```python { .api }
147
class Node:
148
    id: str
149
    version: DockerObjectVersion
150
    created_at: datetime
151
    updated_at: datetime
152
    spec: NodeSpec
153
    description: NodeDescription
154
    status: NodeStatus
155
    manager_status: Optional[ManagerStatus]
156
    
157
    def update(
158
        self,
159
        availability: Optional[str] = None,
160
        labels_add: Optional[Dict[str, str]] = None,
161
        rm_labels: Optional[List[str]] = None,
162
        role: Optional[str] = None
163
    ) -> None:
164
        """Update this node's configuration."""
165
    
166
    def ps(self) -> List[Task]:
167
        """List tasks running on this node."""
168

169
class NodeSpec:
170
    name: Optional[str]
171
    labels: Dict[str, str]
172
    role: str  # "manager" or "worker"
173
    availability: str  # "active", "pause", "drain"
174

175
class NodeDescription:
176
    hostname: str
177
    platform: Dict[str, str]
178
    resources: Dict[str, Any]
179
    engine: Dict[str, Any]
180

181
class NodeStatus:
182
    state: str  # "ready", "down", "unknown"
183
    message: Optional[str]
184
    addr: str
185

186
class ManagerStatus:
187
    leader: bool
188
    reachability: str  # "reachable", "unreachable"
189
    addr: str
190

191
class DockerObjectVersion:
192
    index: int
193
```