Skip to content

Commit f623352

Browse files
makhovmakhov
authored
pre/post-StartCommands docs (#1241)
Signed-off-by: makhov <[email protected]>
1 parent 0ff1af1 commit f623352

File tree

2 files changed

+228
-0
lines changed

2 files changed

+228
-0
lines changed

‎docs/capi-bootstrap.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,122 @@ This configuration sets up a `Machine` object that will trigger the k0smotron co
4040

4141
For reference on what can be configured via `K0sWorkerConfig` see the [reference docs](resource-reference/bootstrap.cluster.x-k8s.io-v1beta1.md).
4242

43+
## Pre/Post Start Commands
44+
45+
k0smotron supports executing custom commands before and after starting k0s on worker and controller nodes. This feature is useful for:
46+
47+
- Installing additional packages or dependencies
48+
- Configuring system settings
49+
- Setting up monitoring agents
50+
- Running health checks
51+
- Performing cleanup operations
52+
53+
### PreStartCommands
54+
55+
Commands specified in `preStartCommands` are executed before k0s binary is downloaded and installed.
56+
57+
```yaml
58+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
59+
kind: K0sWorkerConfig
60+
metadata:
61+
name: worker-config
62+
spec:
63+
version: v1.27.2+k0s.0
64+
preStartCommands:
65+
- "apt-get update && apt-get install -y curl jq"
66+
- "mkdir -p /etc/k0s/monitoring"
67+
- "echo 'export MONITORING_ENABLED=true' >> /etc/environment"
68+
```
69+
70+
### PostStartCommands
71+
72+
Commands specified in `postStartCommands` are executed after k0s has started successfully. These commands run after the k0s service is running and the node is ready.
73+
74+
```yaml
75+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
76+
kind: K0sWorkerConfig
77+
metadata:
78+
name: worker-config
79+
spec:
80+
version: v1.27.2+k0s.0
81+
postStartCommands:
82+
- "systemctl enable monitoring-agent"
83+
- "systemctl start monitoring-agent"
84+
- "kubectl get nodes --kubeconfig=/var/lib/k0s/pki/admin.conf"
85+
```
86+
87+
### Command Execution Order
88+
89+
The commands are executed in the following order:
90+
91+
1. **PreStartCommands** - Custom commands before k0s starts
92+
2. **Download and Install** - k0s binary download and installation
93+
3. **k0s start** - k0s service startup
94+
4. **PostStartCommands** - Custom commands after k0s starts
95+
96+
### Use Cases
97+
98+
#### Installing Monitoring Agents
99+
100+
```yaml
101+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
102+
kind: K0sWorkerConfig
103+
metadata:
104+
name: worker-with-monitoring
105+
spec:
106+
version: v1.27.2+k0s.0
107+
preStartCommands:
108+
- "curl -fsSL https://get.docker.com | sh"
109+
- "systemctl enable docker"
110+
- "systemctl start docker"
111+
postStartCommands:
112+
- "docker run -d --name node-exporter -p 9100:9100 prom/node-exporter"
113+
- "echo 'Node exporter started on port 9100'"
114+
```
115+
116+
#### Configuring System Settings
117+
118+
```yaml
119+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
120+
kind: K0sWorkerConfig
121+
metadata:
122+
name: worker-with-config
123+
spec:
124+
version: v1.27.2+k0s.0
125+
preStartCommands:
126+
- "echo 'vm.max_map_count=262144' >> /etc/sysctl.conf"
127+
- "sysctl -p"
128+
- "echo 'net.core.somaxconn=65535' >> /etc/sysctl.conf"
129+
- "sysctl -p"
130+
postStartCommands:
131+
- "echo 'System configuration applied successfully'"
132+
- "sysctl vm.max_map_count net.core.somaxconn"
133+
```
134+
135+
#### Health Checks and Validation
136+
137+
```yaml
138+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
139+
kind: K0sWorkerConfig
140+
metadata:
141+
name: worker-with-health-checks
142+
spec:
143+
version: v1.27.2+k0s.0
144+
postStartCommands:
145+
- "kubectl get nodes --kubeconfig=/var/lib/k0s/pki/admin.conf"
146+
- "kubectl describe node $(hostname) --kubeconfig=/var/lib/k0s/pki/admin.conf"
147+
- "echo 'Health check completed successfully'"
148+
```
149+
150+
### Important Notes
151+
152+
- Commands are executed as root user
153+
- Each command is executed in a separate shell session
154+
- If any command fails, the bootstrap process will fail
155+
- Commands are executed in the order they appear in the array
156+
- Environment variables from the system are available to the commands
157+
- The k0s kubeconfig is available at `/var/lib/k0s/pki/admin.conf` for PostStartCommands
158+
43159
The `infrastructureRef` in the `Machine` object specifies a reference to the provider-specific infrastructure required for the operation of the machine. In the above example, the kind `AWSMachine` indicates that the machine will be run on AWS. The parameters within `infrastructureRef` will be provider-specific and vary based on your chosen infrastructure.
44160

45161
```yaml

‎docs/capi-controlplane-bootstrap.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,118 @@ By applying this yaml, k0smotron will create 3 machines based on the `MachineTem
6464

6565
For a full reference on `K0sControlPlane` configurability see the [reference docs](resource-reference/controlplane.cluster.x-k8s.io-v1beta1.md).
6666

67+
## Pre/Post Start Commands
68+
69+
k0smotron supports executing custom commands before and after starting k0s on control plane nodes. This feature is useful for:
70+
71+
- Installing additional packages or dependencies
72+
- Configuring system settings
73+
- Setting up monitoring agents
74+
- Running health checks
75+
- Performing cleanup operations
76+
77+
### PreStartCommands
78+
79+
Commands specified in `preStartCommands` are executed before k0s binary is downloaded and installed.
80+
81+
```yaml
82+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
83+
kind: K0sControlPlane
84+
metadata:
85+
name: cp-test
86+
spec:
87+
replicas: 3
88+
k0sConfigSpec:
89+
preStartCommands:
90+
- "apt-get update && apt-get install -y curl jq"
91+
- "mkdir -p /etc/k0s/monitoring"
92+
- "echo 'export MONITORING_ENABLED=true' >> /etc/environment"
93+
```
94+
95+
### PostStartCommands
96+
97+
Commands specified in `postStartCommands` are executed after k0s has started successfully. These commands run after the k0s service is running and the control plane is ready.
98+
99+
```yaml
100+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
101+
kind: K0sControlPlane
102+
metadata:
103+
name: cp-test
104+
spec:
105+
replicas: 3
106+
k0sConfigSpec:
107+
postStartCommands:
108+
- "systemctl enable monitoring-agent"
109+
- "systemctl start monitoring-agent"
110+
- "kubectl get nodes --kubeconfig=/var/lib/k0s/pki/admin.conf"
111+
```
112+
113+
### Command Execution Order
114+
115+
The commands are executed in the following order:
116+
117+
1. **PreStartCommands** - Custom commands before k0s starts
118+
2. **Download and Install** - k0s binary download and installation
119+
3. **k0s start** - k0s service startup
120+
4. **PostStartCommands** - Custom commands after k0s starts
121+
122+
### Use Cases
123+
124+
#### Installing Monitoring Agents on Control Plane
125+
126+
```yaml
127+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
128+
kind: K0sControlPlane
129+
metadata:
130+
name: cp-with-monitoring
131+
spec:
132+
replicas: 3
133+
k0sConfigSpec:
134+
preStartCommands:
135+
- "curl -fsSL https://get.docker.com | sh"
136+
- "systemctl enable docker"
137+
- "systemctl start docker"
138+
postStartCommands:
139+
- "docker run -d --name node-exporter -p 9100:9100 prom/node-exporter"
140+
- "echo 'Node exporter started on port 9100'"
141+
```
142+
143+
#### Configuring System Settings for Control Plane
144+
145+
```yaml
146+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
147+
kind: K0sControlPlane
148+
metadata:
149+
name: cp-with-config
150+
spec:
151+
replicas: 3
152+
k0sConfigSpec:
153+
preStartCommands:
154+
- "echo 'vm.max_map_count=262144' >> /etc/sysctl.conf"
155+
- "sysctl -p"
156+
- "echo 'net.core.somaxconn=65535' >> /etc/sysctl.conf"
157+
- "sysctl -p"
158+
postStartCommands:
159+
- "echo 'System configuration applied successfully'"
160+
- "sysctl vm.max_map_count net.core.somaxconn"
161+
```
162+
163+
#### Health Checks and Validation for Control Plane
164+
165+
```yaml
166+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
167+
kind: K0sControlPlane
168+
metadata:
169+
name: cp-with-health-checks
170+
spec:
171+
replicas: 3
172+
k0sConfigSpec:
173+
postStartCommands:
174+
- "kubectl get nodes --kubeconfig=/var/lib/k0s/pki/admin.conf"
175+
- "kubectl describe node $(hostname) --kubeconfig=/var/lib/k0s/pki/admin.conf"
176+
- "echo 'Control plane health check completed successfully'"
177+
```
178+
67179
## Downscaling the control plane
68180

69181
**WARNING: Downscaling is a potentially dangerous operation.**

0 commit comments

Comments
 (0)