# MachineDeployments

MachineDeployments allow you to manage different groups of Nodes with different configurations. MetaKube performs rolling updates on Nodes when the configuration of a MachineDeployment changes.

## Node lifecycle

### Cluster API

MetaKube models the lifecycle of Nodes with the Kubernetes [Cluster API](<https://github.com/kubernetes-sigs/cluster-api>) which defines custom resources that are `MachineDeployment`, `MachineSet` and `Machine`.

### Provisioning

When MetaKube creates a new Machine (for example, during a [rolling update](<#rolling-update>)), MetaKube will:

1. **Create OpenStack resources** (port, server, floating IP)
2. Wait until Node comes up and becomes Ready

   1. Server boots and gets initialization config from the OpenStack metadata service
   2. Server runs initialization code and installs Kubelet
   3. Kubelet gets a client certificate through the CSR
   4. **Kubelet registers the Node for the first time**
   5. OpenStack cloud controller manager initializes the Node metadata (for example, addresses)
   6. Critical DaemonSet Pods (CNI) start running
   7. MetaKube removes the `node.syseleven.de/not-ready:NoSchedule` taint and marks the Node as Ready

### Deletion

MetaKube may delete Machines as part of:

- Rolling updates
- Scaling down of MachineDeployments
- Deletion of MachineDeployments
- If Node hasn't joined the cluster in 2h

To deprovision a Kubernetes Node, MetaKube will:

1. Mark Machine object for deletion
2. Start [draining](<https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/>) the Node, honoring potential PodDisruptionBudgets
3. Clean up resources in cloud
4. Delete the Machine object

With this process, you can delete a Machine (`kubectl -n kube-system delete machine my-node-1234`) to replace a particular Kubernetes Node.

> [!NOTE]
>
> **Info**
>
> If a user deletes the server corresponding to a Kubernetes Node directly in OpenStack, the OpenStack cloud controller manager (node controller) deletes the Node object and MetaKube cleans up the corresponding Machine and creates a replacement.

### Rolling Update

Any change to a MachineDeployment's [machine template](<#machinetemplate>) will trigger a rolling update of the nodes.

MetaKube will gradually scale up the new MachineSet and wait until the Nodes join the cluster and become Ready before scaling down the old MachineSet.

You can manually trigger a rollover with this `kubectl` command:

```bash
kubectl -n kube-system patch machinedeployment $machinedeployment -p '{"spec": {"template": {"metadata": {"annotations": {"kubectl.kubernetes.io/restartedAt": "'$(date +"%Y-%m-%dT%T.%3N%z")'"}}}}}' --type merge
```

## Configuration

> [!NOTE]
>
> **Info**
>
> Not all of these options are available through every client (UI, Terraform). Some clients may instead use default values.

### MachineDeployment

| Field | Type | Explanation |
| --- | --- | --- |
| `spec.replicas` |  | MetaKube will maintain this number of nodes for this MachineDeployment.<br>See also [autoscaling](<https://documentation.syseleven.de/en/products/metakube-core/concepts/nodes/autoscaling/index.md>) as an alternative to a static replica count. |
| `spec.strategy.rollingUpdate.maxSurge` | `integer` or `percentage` | During a rolling update, MetaKube may start provisioning this many more new nodes than `spec.replicas`. |
| `spec.strategy.rollingUpdate.maxUnavailable` | `integer` or `percentage` | During a rolling update, MetaKube may start removing this many nodes below `spec.replicas` before new nodes become Ready. |
| `spec.template` | MachineTemplate | Template for the machines that get created.<br>**Note:** *Any change to the machine template will trigger a rolling update!* |

### MachineTemplate

| Field | Type | Explanation |
| --- | --- | --- |
| `metadata.labels` | `map(string)` | Labels that are added to the nodes |
| `spec.versions.kubelet` | `string` (SemVer) | The version of Kubelet. Should ideally be kept the same as the control plane version.<br>Changing this will replace existing nodes with new ones.<br><br>You can upgrade the control plane and Kubelet versions independently, as long as it doesn't violate the Kubernetes version skew policy.<br>See [supported Kubernetes versions](<https://documentation.syseleven.de/en/products/metakube-core/concepts/kubernetes-versions/index.md>) for what Kubelet versions are supported for a given control plane version. |
| `spec.taints` | `list(taint)`, see [docs](<https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#concepts>) | Taints that are added to the nodes |
| `spec.providerSpec.value.cloudProviderSpec` | CloudProviderSpec | Cloud provider specific configuration |
| `spec.providerSpec.value.operatingSystem` | `string` | Distro of the operating system. Either `ubuntu` or `flatcar`. |
| `spec.providerSpec.value.operatingSystemSpec` | OperatingSystemSpec | Operating system specific configuration |
| `spec.providerSpec.value.sshPublicKeys` | `list(string)` | Authorized SSH public keys *initially* installed on the machine<br>Once initialized, the keys are managed by the `ssh-key-agent` DaemonSet Pod. |

### CloudProviderSpec (OpenStack)

| Field | Type | Explanation |
| --- | --- | --- |
| `flavor` | `string` | **Name** of Flavor to use for the OpenStack server<br>See [OpenStack cloud documentation](<https://www.syseleven.de/support/#flavors>) for a list of available Flavors and [here](<https://documentation.syseleven.de/en/products/metakube-core/concepts/nodes/resources/profiles/#flavors>) for limitations. |
| `floatingIpPool` | `string` | **Name** of external network that floating IPs for servers would be allocated from |
| `image` | `string` | OpenStack operating system image **name** or **ID** |
| `rootDiskSizeGB` | `number` | Capacity of root disk in GB<br>*Not available for localstorage flavors.*<br>**Note**: *The replacement disk will incur the standard fee for network storage.* |
| `securityGroups` | `list(string)` | **Names** of security groups that are associated with the server port |
| `serverGroupID` | `string` | **ID** of the server group the server belongs to<br>Defaults to cluster-wide shared server group, see [topology](<https://documentation.syseleven.de/en/products/metakube-core/concepts/nodes/topology/index.md>) |
| `subnet` | `string` | **ID** of subnet the server port is allocated in |
| `tags` | `list(string)` | Additional tags for the server |

### OperatingSystemSpec (Ubuntu)

| Field | Type | Explanation |
| --- | --- | --- |
| `distUpgradeOnBoot` | `bool` | Whether to upgrade packages and reboot (if necessary) on first boot |
