Upgrade

All components in Elemental are managed using Kubernetes. Below is how to use Kubernetes approaches to upgrade the components.

Elemental Teal node upgrade

Elemental Teal is upgraded with the Elemental Operator. Refer to the Elemental Operator documentation for complete information.

Upgrade can be achieve either with CLI or UI:

Upgrade via command line interface

There are two ways of selecting nodes for upgrading. Via a cluster target, which will match ALL nodes in a cluster that matches our selector or via node selector, which will match nodes based on the node labels. Node selector allows us to be more targeted with the upgrade while cluster selector just selects all the nodes in a matched cluster.

Updating an existing ManagedOSImage is ineffective.
Once a version upgrade is completed on all targeted clusters, you can safely delete the ManagedOSImage and create a new one to trigger a new upgrade.

Upgrade - 图1info

From version 1.5.0 of the Elemental Operator, the ManagedOSImage is an editable resource and can be used to reconcile a desired OS image or image version to all targeted clusters.

  • With ‘clusterTarget’
  • With nodeSelector
  • With FORCE flag

You can target nodes for an upgrade via a clusterTarget by setting it to the cluster name that you want to upgrade. All nodes in a cluster that matches that name will match and be upgraded.

upgrade-cluster-target.yaml

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSImage
  3. metadata:
  4.   name: my-upgrade
  5.   namespace: fleet-default
  6. spec:
  7.   # Set to the new Elemental version you would like to upgrade to or track the latest tag
  8.   osImage: "registry.suse.com/suse/sle-micro/5.5:latest"
  9.   clusterTargets:
  10.     - clusterName: my-cluster

You can target nodes for an upgrade via a nodeSelector by setting it to the label and value that you want to match. Any nodes containing that key with the value will match and be upgraded.

upgrade-node-selector.yaml

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSImage
  3. metadata:
  4.   name: my-upgrade
  5.   namespace: fleet-default
  6. spec:
  7.   # Set to the new Elemental version you would like to upgrade to
  8.   osImage: "registry.suse.com/suse/sle-micro/5.5:latest"
  9.   clusterTargets:
  10.     - clusterName: my-cluster
  11.   nodeSelector:
  12.     matchLabels:
  13.       kubernetes.io/hostname: my-machine

When upgrading to an older version or the same version that is already running the upgrade-procedure will be skipped.

It is possible to force upgrades to older versions by setting the FORCE environment variable as shown below.

upgrade-force.yaml

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSImage
  3. metadata:
  4.   name: my-upgrade
  5.   namespace: fleet-default
  6. spec:
  7.   # Set to the new Elemental version you would like to upgrade to
  8.   osImage: "registry.suse.com/suse/sle-micro/5.5:latest"
  9.   clusterTargets:
  10.     - clusterName: my-cluster
  11.   upgradeContainer:
  12.     envs:
  13.       - name: FORCE
  14.         value: "true"

Selecting source for upgrade

  • Via ‘osImage’
  • Via ‘ManagedOSVersion’

Just specify an OCI image on the osImage field

upgrade-cluster-target.yaml

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSImage
  3. metadata:
  4.   name: my-upgrade
  5.   namespace: fleet-default
  6. spec:
  7.   # Set to the new Elemental version you would like to upgrade to or track the latest tag
  8.   osImage: "registry.suse.com/suse/sle-micro/5.5:latest"
  9.   clusterTargets:
  10.     - clusterName: my-cluster

In this case we use the auto populated ManagedOSVersion resources to set the wanted managedOSVersionName field. See section Managing available versions to understand how the ManagedOSVersion are managed.

upgrade-managedos-version.yaml

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSImage
  3. metadata:
  4.   name:  my-upgrade
  5.   namespace: fleet-default
  6. spec:
  7.   # Set to the new ManagedOSVersion you would like to upgrade to
  8.   managedOSVersionName: v0.1.0-alpha22-amd64
  9.   clusterTargets:
  10.     - clusterName: my-cluster

Upgrade - 图2Warning

If both osImage and ManagedOSVersion are defined in the same ManagedOSImage be aware that osImage takes precedence.

Managing available versions

An ManagedOSVersionChannel resource can be created in a Kubernetes cluster where the Elemental operator is installed to synchronize available versions for upgrades.

It has a syncer in order to generate ManagedOSVersion automatically. Currently, we provide a json syncer and a custom one.

  • Json syncer
  • Custom syncer

This syncer will fetch a json from url and parse it into valid ManagedOSVersion resources.

managed-os-version-json

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSVersionChannel
  3. metadata:
  4.   name: elemental-versions
  5.   namespace: fleet-default
  6. spec:
  7.   options:
  8.     URI: "https://raw.githubusercontent.com/rancher/elemental-docs/main/examples/upgrade/versions.json"
  9.     Timeout: "1m"
  10.   type: json

A custom syncer allows more flexibility on how to gather ManagedOSVersion by allowing custom commands with custom images.

This type of syncer allows to run a given command with arguments and env vars in a custom image and output a json file to /data/output. The generated data is then automounted by the syncer and then parsed so it can gather create the proper versions.

Upgrade - 图3info

The only requirement to make your own custom syncer is to make it output a json file to /data/output and keep the correct json structure.

Elemental project provides an Elemental Teal channel to list all ManagedOSVersions released as a custom syncer. See the Elemental Teal channel resource definition below:

managed-os-version-channel-json.yaml

  1. apiVersion: elemental.cattle.io/v1beta1
  2. kind: ManagedOSVersionChannel
  3. metadata:
  4.   name: elemental-channel
  5.   namespace: fleet-default
  6. spec:
  7.   options:
  8.     image: registry.suse.com/rancher/elemental-channel:latest
  9.   type: custom

In both cases the file that the operator expects to parse is a json file with the versions on it as follows

versions.json

  1. [
  2.   {
  3.       "metadata": {
  4.           "name": "my-flavor-v0.1.0"
  5.       },
  6.       "spec": {
  7.           "version": "v0.1.0",
  8.           "type": "container",
  9.           "metadata": {
  10.               "upgradeImage": "foo/bar-os:v0.1.0-myflavor",
  11.               "displayName": "Foo Bar OS - My Flavor"
  12.           }
  13.       }
  14.   },
  15.   {
  16.     "metadata": {
  17.         "name": "my-flavor-v0.1.0-iso"
  18.     },
  19.     "spec": {
  20.         "version": "v0.1.0",
  21.         "type": "iso",
  22.         "metadata": {
  23.             "uri": "foo/bar-iso:v0.1.0-myflavor",
  24.             "displayName": "Foo Bar ISO - My Flavor"
  25.         }
  26.     }
  27.   }
  28. ]

Upgrade via user interface

To upgrade via the UI, you have to go in the Elemental Advanced menu, then click on Update Groups.

Choose a name, select clusters to target and choose between the two upgrade ways:

Elemental Upgrade Menu

  • Via Managed OS Version
  • Via Image from registry

In this case, a OS Version Channels is used to auto populated OS Versions resources.

The channel bellow is provide by us but you can bring your own channel as well.

See section Managing available versions to understand how the ManagedOSVersion are managed.

Create OS Version Channel

After a short syncing time, you will see your OS Versions appears in the OS Versions menu.

Elemental OS Version menu

Finally, you can select the OS Versions when you create your Upgrade Group according to the following screenshot:

Select OS Version in Upgrade Group

Just specify an OCI image on the Image path field to upgrade to:

Upgrade via Image Registry

Click on the Create button to start the upgrade process, if you have multiple nodes, the upgrade will be done sequentially node by node.