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.

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.

With 'clusterTarget'

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

apiVersion: elemental.cattle.io/v1beta1
kind: ManagedOSImage
metadata:
  name: my-upgrade
  namespace: fleet-default
spec:
  # Set to the new Elemental version you would like to upgrade to or track the latest tag
  osImage: "registry.opensuse.org/isv/rancher/elemental/teal52/15.3/rancher/elemental-node-image/5.2:latest"
  clusterTargets:
    - clusterName: my-cluster

With nodeSelector

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

apiVersion: elemental.cattle.io/v1beta1
kind: ManagedOSImage
metadata:
  name: my-upgrade
  namespace: fleet-default
spec:
  # Set to the new Elemental version you would like to upgrade to
  osImage: "registry.opensuse.org/isv/rancher/elemental/teal52/15.3/rancher/elemental-node-image/5.2:latest"
  clusterTargets:
    - clusterName: my-cluster
  nodeSelector:
    matchLabels:
      kubernetes.io/hostname: my-machine

Selecting source for upgrade

Via 'osImage'

Just specify an OCI image on the osImage field

upgrade-cluster-target.yaml

apiVersion: elemental.cattle.io/v1beta1
kind: ManagedOSImage
metadata:
  name: my-upgrade
  namespace: fleet-default
spec:
  # Set to the new Elemental version you would like to upgrade to or track the latest tag
  osImage: "registry.opensuse.org/isv/rancher/elemental/teal52/15.3/rancher/elemental-node-image/5.2:latest"
  clusterTargets:
    - clusterName: my-cluster

Via 'ManagedOSVersion'

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

apiVersion: elemental.cattle.io/v1beta1
kind: ManagedOSImage
metadata:
  name:  my-upgrade
  namespace: fleet-default
spec:
  # Set to the new ManagedOSVersion you would like to upgrade to
  managedOSVersionName: v0.1.0-alpha22-amd64
  clusterTargets:
    - clusterName: my-cluster

Warning

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

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

managed-os-version-json

apiVersion: elemental.cattle.io/v1beta1
kind: ManagedOSVersionChannel
metadata:
  name: elemental-versions
  namespace: fleet-default
spec:
  options:
    URI: "https://raw.githubusercontent.com/rancher/elemental-docs/main/examples/upgrade/versions.json"
    Timeout: "1m"
  type: json

Custom syncer

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.

info

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.

See below for an example use of our discovery plugin, which gathers versions from either git or github releases.

managed-os-version-channel-json.yaml

apiVersion: elemental.cattle.io/v1beta1
kind: ManagedOSVersionChannel
metadata:
  name: elemental-versions
  namespace: fleet-default
spec:
  options:
    args:
      - github
    command:
      - /usr/bin/upgradechannel-discovery
    envs:
      - name: REPOSITORY
        value: rancher/elemental
      - name: IMAGE_PREFIX
        value: quay.io/costoolkit/elemental
    image: quay.io/costoolkit/upgradechannel-discovery:v0.3-4b83dbe
  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

[
  {
    "metadata": {
      "name": "v0.1.0"
    },
    "spec": {
      "version": "v0.1.0",
      "type": "container",
      "metadata": {
        "upgradeImage": "foo/bar:v0.1.0"
      }
    }
  },
  {
    "metadata": {
      "name": "v0.2.0"
    },
    "spec": {
      "version": "v0.2.0",
      "type": "container",
      "metadata": {
        "upgradeImage": "foo/bar:v0.2.0"
      }
    }
  }
]