Using Operating System Manager

Starting with KKP 2.21, OSM will be enabled by default for all the new user clusters. It is highly recommended to use OSM instead of user-data from machine-controller, which is consideread deprecated and will be removed in the near future.

OSM can be configured using the dashboard or CLI.

Via UI

Enable OSM

Create a new cluster from the dashboard and toggle Operating System Manager feature on.

Selecting OperatingSystemProfile

Via CLI

On cluster creation, set the following values in Cluster resource:

apiVersion: kubermatic.k8c.io/v1
kind: Cluster
metadata:
  name: crh4xbxz5f
spec:
...
  enableOperatingSystemManager: true
...

Custom OperatingSystemProfiles

To use custom OperatingSystemProfiles, users can do the following:

1. Create their CustomOperatingSystemProfile resource on the seed cluster in the kubermatic namespace. These resources will be automatically synced to the kube-system namespace of the user-clusters.

apiVersion: operatingsystemmanager.k8c.io/v1alpha1
kind: CustomOperatingSystemProfile
metadata:
  name: osp-install-curl
  namespace: kubermatic
spec:
  osName: "ubuntu"
  osVersion: "20.04"
  version: "v1.0.0"
  supportedCloudProviders:
    - name: "aws"
  bootstrapConfig:
    files:
      - path: /opt/bin/bootstrap
        permissions: 755
        content:
          inline:
            encoding: b64
            data: |
              #!/bin/bash

              apt update && apt install -y curl jq              

      - path: /etc/systemd/system/bootstrap.service
        permissions: 644
        content:
          inline:
            encoding: b64
            data: |
              [Install]
              WantedBy=multi-user.target

              [Unit]
              Requires=network-online.target
              After=network-online.target
              [Service]
              Type=oneshot
              RemainAfterExit=true
              ExecStart=/opt/bin/bootstrap              

    modules:
      runcmd:
        - systemctl restart bootstrap.service

  provisioningConfig:
    files:
      - path: /opt/hello-world
        permissions: 644
        content:
          inline:
            encoding: b64
            data: echo "hello world"

2. Create OperatingSystemProfile resources in the kube-system namespace of the user cluster, after cluster creation.

Updating existing OperatingSystemProfiles

OSPs are immutable by design and any modifications to an existing OSP requires a version bump in .spec.version. Users can create custom OSPs in the seed namespace or in the user cluster and manage them.

KKP ships default OSPs for different operating systems and it is not recommended to update default OSPs. Since KKP manages those resources and will revert any changes made on them.

Migrating existing clusters

For migrating existing clusters, user can enable OSM using either the CLI or UI. That would enable OSM on the user cluster level. Although the machines will not be rotated automatically. To perform this rotation for existing MachineDeployments please follow the guide at Rolling Restart MachineDeploments.