Merge pull request k0sproject#391 from makhov/remotemachine-pool-docs

RemoteMachine pooling docs
makhov · Jan 2, 2024 · 0713035 · 0713035
2 parents 2063938 + 1480d93
commit 0713035
Show file tree

Hide file tree

Showing 2 changed files with 521 additions and 5 deletions.
diff --git a/docs/capi-remote.md b/docs/capi-remote.md
@@ -99,3 +99,81 @@ spec:
     # This defines which SSH key to use for connecting to the machine. The Secret needs to have key 'value' with the SSH private key in it.
     name: footloose-key
 ```
+
+## Using `RemoteMachine`s in `machineTemplate`s of higher-level objects
+
+Objects like `K0sControlPlane` or `MachineDeployment` use `machineTemplate` to define the template for the `Machine` objects they create. 
+Since k0smotron remote machine provider can't create machines on its own, it works with a pool of pre-created machines.
+
+```yaml
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: RemoteMachineTemplate
+metadata:
+  name: remote-test-template
+  namespace: default
+spec:
+  template:
+    spec:
+      pool: default
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: PooledRemoteMachine
+metadata:
+  name: remote-test-0
+  namespace: default
+spec:
+  pool: default
+  machine:
+    address: 1.2.3.4
+    port: 22
+    user: root
+    sshKeyRef:
+      name: footloose-key-0
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+kind: PooledRemoteMachine
+metadata:
+  name: remote-test-1
+  namespace: default
+spec:
+  pool: default
+  machine:
+    address: 2.3.4.5
+    port: 22
+    user: root
+    sshKeyRef:
+      name: footloose-key-1
+```
+
+Then you can use the `RemoteMachineTemplate` in the `machineTemplate` of `K0sControlPlane`:
+
+```yaml
+apiVersion: controlplane.cluster.x-k8s.io/v1beta1
+kind: K0sControlPlane
+metadata:
+  name: remote-test
+spec:
+  replicas: 1
+  k0sVersion: v1.27.1+k0s.0
+  k0sConfigSpec:
+    k0s:
+      apiVersion: k0s.k0sproject.io/v1beta1
+      kind: ClusterConfig
+      metadata:
+        name: k0s
+      spec:
+        api:
+          extraArgs:
+            anonymous-auth: "true"
+  machineTemplate:
+    infrastructureRef:
+      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+      kind: RemoteMachineTemplate
+      name: remote-test-template
+      namespace: default
+---
+… # other objects omitted for brevity
+```
+
+When CAPI controller creates a `RemoteMachine` from template object for the `K0sControlPlane`, k0smotron will pick one of the `PooledRemoteMachine` objects and use it's values for the `RemoteMachine` object.