Skip to content

Update to version1.8 #485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
davidcassany merged 2 commits into from
Jan 20, 2026
Merged

Update to version1.8 #485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3eb9398
Update latest releases
davidcassany Jan 16, 2026
613d698
Add new v1.8 version from Next
davidcassany Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ ISO or disk images.

<ButtonGroup size="small">
<Button variant="contained" href="https://elemental.docs.rancher.com/release-notes">Latest Release:</Button>
<Button variant="outlined" href="https://elemental.docs.rancher.com/release-notes">v1.7.3</Button>
<Button variant="outlined" href="https://elemental.docs.rancher.com/release-notes">v1.8.0</Button>
</ButtonGroup>

## Welcome to Elemental
Expand Down
31 changes: 4 additions & 27 deletions docs/release-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ Here's the different components, their latest version and a link to the respecti

| Name | Version | Release Notes |
|----------------------------------------------------------------------|---------|------------------------------------------------------------------------------|
| [Elemental Operator](https://github.com/rancher/elemental-operator/) | v1.7.3 | [Link](https://github.com/rancher/elemental-operator/releases/tag/v1.7.3) |
| [Elemental Toolkit](https://github.com/rancher/elemental-toolkit/) | v2.2.2 | [Link](https://github.com/rancher/elemental-toolkit/releases/tag/v2.2.2) |
| [Elemental Linux](https://github.com/rancher/elemental) | v2.2.0 | [Link](https://github.com/rancher/elemental/releases/tag/v2.2.0) |
| [Elemental Operator](https://github.com/rancher/elemental-operator/) | v1.8.0 | [Link](https://github.com/rancher/elemental-operator/releases/tag/v1.8.0) |
| [Elemental Toolkit](https://github.com/rancher/elemental-toolkit/) | v2.3.2 | [Link](https://github.com/rancher/elemental-toolkit/releases/tag/v2.3.2) |
| [Elemental Linux](https://github.com/rancher/elemental) | v2.3.0 | [Link](https://github.com/rancher/elemental/releases/tag/v2.3.0) |
| [Elemental UI](https://github.com/rancher/elemental-ui) | v3.0.1 | [Link](https://github.com/rancher/elemental-ui/releases/tag/elemental-3.0.1) |

:::note Information on docs versioning
Expand Down Expand Up @@ -91,29 +91,6 @@ OS channel is `v2.2.0-4.4`. The ManagedOSVersion of type `container` is correctl
version of the ManagedOSVersion of type `iso` is `v2.2.0-4.3`: the `iso` type contains instead the OS version `v2.2.0-4.4`,
as would result by checking the `/etc/os-release` file of the installed machine.

### Predictable Network Interface Names

The SLE Micro OS images with versions v2.1.1 and v2.1.2 (released in the default
[ManagedOSVersionChannel](managedosversionchannel-reference))
adopt predictable network interface names by default.

This is a change from SLE Micro OS images previously released, so you should expect your
Elemental hosts to switch the network interface names from the `ethX` template to the `enpXsY` one.

You can disable the predictable network interface names by passing the `net.ifnames=0` argument
to the kernel command line. To make it permanent:

```sh
grub2-editenv /oem/grubenv set extra_cmdline=net.ifnames=0
```

:::warning
The adoption of the predictable network interface names feature was not a planned one:
it will be reverted in the next SLE Micro OS images starting from version v2.1.3.
These OS images will include the `net.ifnames=0` kernel command line argument by default.
The v2.1.3 OS images will be released via the default Elemental 1.6 channel.
:::

### SSH root access

The SLE Micro OS images released in the current Elemental version (through the default
Expand All @@ -123,5 +100,5 @@ key or add a new user to the system.

### Kernel Panic on hypervisors

OS Images based on SL Micro 6.0 can fail to boot with a kernel panic on virtual machines using an unsupported CPU type.
OS Images based on SL Micro 6.0 can fail to boot with a kernel panic on virtual machines using an unsupported CPU type.
The `x86-64-v2` instruction set is required. For best compatibility CPU host passthrough is recommended.
2 changes: 1 addition & 1 deletion versioned_docs/version-1.6/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ ISO or disk images.

<ButtonGroup size="small">
<Button variant="contained" href="https://elemental.docs.rancher.com/release-notes">Latest Release:</Button>
<Button variant="outlined" href="https://elemental.docs.rancher.com/release-notes">v1.7.3</Button>
<Button variant="outlined" href="https://elemental.docs.rancher.com/release-notes">v1.8.0</Button>
</ButtonGroup>

## Welcome to Elemental
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-1.7/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ ISO or disk images.

<ButtonGroup size="small">
<Button variant="contained" href="https://elemental.docs.rancher.com/release-notes">Latest Release:</Button>
<Button variant="outlined" href="https://elemental.docs.rancher.com/release-notes">v1.7.3</Button>
<Button variant="outlined" href="https://elemental.docs.rancher.com/release-notes">v1.8.0</Button>
</ButtonGroup>

## Welcome to Elemental
Expand Down
243 changes: 243 additions & 0 deletions versioned_docs/version-1.8/airgap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,243 @@
---
sidebar_label: Air-Gapped Installation
title: ''
---

<head>
<link rel="canonical" href="https://elemental.docs.rancher.com/airgap"/>
</head>

## Install Elemental in an Air-Gapped Environment

### Assumptions
A Rancher air-gapped installation should be already configured as per the [official Rancher documentation](https://ranchermanager.docs.rancher.com/pages-for-subheaders/air-gapped-helm-cli-install).
In particular, a private registry should be available in the air-gapped infrastructure.

### Overview
In order to run Elemental in an air-gapped environment the following artifacts are needed:
- the Elemental Operator charts
- the container images referenced in the charts (the *elemental-operator* and *seedimage-builder* images)
- the containerized OS images

Moreover, it could be handy to create a *channel image* referencing the containerized OS images available.
The official channel image (the *elemental-channel* one) references absolute URLs of the OS images on the official suse registry, so it cannot be used as-is in an air-gapped scenario.

### Elemental Air-Gapped installation from the command line
All the required steps can be accomplished by executing the
[`elemental-airgap.sh` script](https://raw.githubusercontent.com/rancher/elemental-operator/main/scripts/elemental-airgap.sh)
from a host with Internet access.

The Elemental charts are a required parameter to the script and can be provided as downloaded archives, URLs or as one of
the `stable`, `staging` and `dev` keywords, to let the script retrieve the correct chart version for you.

`elemental-airgap.sh` inspects the Elemental Operator chart, identifies all the required container images, downloads and saves them in a single docker archive.
It also builds a new OS channel image with the OS image URLs pointing to the private registry passed as argument
(which is a mandatory argument too).

The latest version of the elemental script can be easily downloaded from the official github repo:
```shell showLineNumbers
wget https://raw.githubusercontent.com/rancher/elemental-operator/main/scripts/elemental-airgap.sh
chmod 755 elemental-airgap.sh
```

Let's now download all the artifacts and build a custom channel from the latest stable release of Elemental:

<Tabs>
<TabItem value="dockerArchive" label="Create a Docker archive" default>

```shell showLineNumbers
./elemental-airgap.sh stable -r <REGISTRY.YOURDOMAIN.COM:PORT>
```

once completed (the script may take a while) the following files will be available in the current dir:
- `elemental-operator-crds-chart-<*VERSION*>.tgz`
- `elemental-operator-chart-<*VERSION*>.tgz`
- `elemental-images.txt`
- `elemental-images.tar.gz`

</TabItem>
<TabItem value="haulerArchive" label="Create a Hauler archive" default>

```shell showLineNumbers
./elemental-airgap.sh -ha stable -r <REGISTRY.YOURDOMAIN.COM:PORT>
```
once completed (the script may take a while) both the charts and the container images will be packed in the
hauler archive named `elemental-haul.tar.zst` .

</TabItem>
</Tabs>

#### Elemental installation
The files and archives created by the script should be copied to a host which:
- Has access to the private registry.
- Has the kubectl binary installed and configured to access the air-gapped Rancher cluster.
- Has the helm binary installed.


<Tabs>
<TabItem value="dockerArchive" label="Install from a Docker archive" default>

If the private registry requires authentication you need to log with docker into it:
```shellnocolor showLineNumbers
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
```
Two steps are needed to perform the Elemental installation:
1. load the archive with all the required container images on the private registry:
this could be done using the `rancher-load-images.sh` script distributed with the Rancher release and already used for the Rancher air-gapped deployment:
```shellnocolor showLineNumbers
rancher-load-images.sh \
--image-list elemental-images.txt \
--images elemental-images.tar.gz \
--registry <REGISTRY.YOURDOMAIN.COM:PORT>
```
2. install the downloaded elemental charts configuring the local registry and the newly created channel:
```shellnocolor showLineNumbers
helm upgrade --create-namespace -n cattle-elemental-system \
--install elemental-operator-crds elemental-operator-crds-chart-<VERSION>.tgz

helm upgrade --create-namespace -n cattle-elemental-system \
--install elemental-operator elemental-operator-chart-<VERSION>.tgz \
--set registryUrl=<REGISTRY.YOURDOMAIN.COM:PORT> \
--set channel.repository=rancher/elemental-channel-<REGISTRY.YOURDOMAIN.COM>
```
</TabItem>
<TabItem value="haulerArchive" label="Install from a Hauler archive" default>
To install from a [Hauler](https://rancherfederal.github.io/hauler-docs/) archive (`-ha` option in `elemental-airgap.sh`)
Hauler installation is also a requirement on the host from where the installation is performed.

If the private registry requires authentication you need to log with Hauler into it:
```shellnocolor showLineNumbers
hauler login <REGISTRY.YOURDOMAIN.COM:PORT> -u $USERNAME -p $PASSWORD
```

Three steps are needed to perform the Elemental installation:
1. Load the 'elemental-haul.tar.zst' Haul archive in the Hauler instance in the airgapped infrastructure:
```shellnocolor
hauler store load 'elemental-haul.tar.zst'
```
2. If the local registry in the air-gapped environment is not server by Hauler,
load the Haul archive in the local registry:
```shellnocolor
hauler store copy registry://<REGISTRY.YOURDOMAIN.COM:PORT>
```
:::info Hauler can also serve as a registry
In case the air-gapped local registry is served by an Hauler instance, just load the Haul archive directly there
(as shown in step (1)) and skip step (2).
:::

3. Extract the elemental charts from the Hauler store and install them:
```shellnocolor
hauler store extract elemental-operator-crds-chart-<ELEMENTAL-VERSION>.tgz

hauler store extract elemental-operator-chart-<ELEMENTAL-VERSION>.tgz

helm upgrade --create-namespace -n cattle-elemental-system \
--install elemental-operator-crds elemental-operator-crds-chart-<ELEMENTAL-VERSION>.tgz

helm upgrade --create-namespace -n cattle-elemental-system \
--install elemental-operator elemental-operator-chart-<ELEMENTAL-VERSION>.tgz \
--set registryUrl=<REGISTRY.YOURDOMAIN.COM:PORT> \
--set channel.repository=rancher/elemental-channel-<REGISTRY.YOURDOMAIN.COM:PORT>
```
</TabItem>
</Tabs>

:::info The elemental airgap script outputs the required commands
The `elemental-airgap.sh` scripts prints out the required commands shown above but using the actual chart version and the provided registry URL to allow to easily copy and paste the exact commands.
:::

### Elemental Air-Gapped installation from the Rancher Marketplace
A Rancher air-gapped installation includes also the Elemental Operator charts and the operator and seedimage container
images.

To collect the missing OS images and to build an OS channel image for your private registry execute the
[`elemental-airgap.sh` script](https://raw.githubusercontent.com/rancher/elemental-operator/main/scripts/elemental-airgap.sh)
from an host with Internet access, using the `-co` option.

As an example, let's target the `elemental-channel` image from the latest stable release of Elemental.
The script will take care of downloading the Elemental operator chart (if needed), extract the OS channel image URL,
download it, inspect all the OS images referenced, download all of them and create a new OS channel with links to the
private registry of the air-gapped scenario.
<Tabs>
<TabItem value="dockerArchive" label="Create a Docker archive" default>
```shell showLineNumbers
wget https://raw.githubusercontent.com/rancher/elemental-operator/main/scripts/elemental-airgap.sh
chmod 755 elemental-airgap.sh
./elemental-airgap.sh stable -co -r <REGISTRY.YOURDOMAIN.COM:PORT>
```
once completed (the script may take a while) the following files will be available in the current dir:
- `elemental-operator-crds-chart-<*VERSION*>.tgz`
- `elemental-operator-chart-<*VERSION*>.tgz`
- `elemental-images.txt`
- `elemental-images.tar.gz`
</TabItem>
<TabItem value="haulerArchive" label="Create a Hauler archive" default>
```shell showLineNumbers
./elemental-airgap.sh -ha -co stable -r <REGISTRY.YOURDOMAIN.COM:PORT>
```
once completed (the script may take a while) the container images will be packed in the
hauler archive named `elemental-haul.tar.zst`.
</TabItem>
</Tabs>

#### Elemental installation
The generated archive should be loaded to the air-gapped private registry.

<Tabs>
<TabItem value="dockerArchive" label="Install from a Docker archive" default>

If the private registry requires authentication you need to log with docker into it:
```shellnocolor showLineNumbers
docker login <REGISTRY.YOURDOMAIN.COM:PORT>

The script will print out the commands required to load the images via the Rancher `rancher-load-images.sh` tool, used
for the Rancher air-gapped installations. It should be something like:

```shell showLineNumbers
NEXT STEPS:

1) Load the 'elemental-images.tar.gz' to the local registry (<REGISTRY.YOURDOMAIN.COM:PORT>)
available in the airgapped infrastructure:

./rancher-load-images.sh \
--image-list elemental-images.txt \
--images elemental-images.tar.gz \
--registry <REGISTRY.YOURDOMAIN.COM:PORT>
```
Once the OS and channel images are loaded, you should skip the point (2) from the script output
(which will install the Elemental charts from the downloaded archives)
and instead perform the Elemental Operator installation from the Rancher UI.
</TabItem>
<TabItem value="haulerArchive" label="Install from a Hauler archive" default>
If the private registry requires authentication you need to log with Hauler into it:
```shellnocolor showLineNumbers
hauler login <REGISTRY.YOURDOMAIN.COM:PORT> -u $USERNAME -p $PASSWORD
```

The script will print out the commands required to load the images. It should be something like:

```shell showLineNumbers
NEXT STEPS:

1. Load the 'elemental-haul.tar.zst' Haul archive in the Hauler instance in the airgapped infrastructure:

hauler store load 'elemental-haul.tar.zst'

2. If the local registry in the air-gapped environment is not server by Hauler,
load the Haul archive in the local registry:

hauler store copy registry://<REGISTRY.YOURDOMAIN.COM:PORT>
```
Once the OS and channel images are loaded, you should skip the point (3) from the script output
(which will install the Elemental charts from the downloaded archives)
and instead perform the Elemental Operator installation from the Rancher UI.
</TabItem>
</Tabs>

When requested, put the full path of the OS channel image just uploaded in your private registry:
![Elemental OS Channel](images/airgap-os-channel-image.png)

### Elemental UI Extension
Rancher 2.7.x doesn't support UI extensions plugin in air-gapped environments, and so the Elemental UI is not available in Rancher 2.7.x.

The Elemental UI plugin will be present in the available UI extensions in Rancher 2.8.0.
14 changes: 14 additions & 0 deletions versioned_docs/version-1.8/architecture-clusterdeployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
sidebar_label: Kubernetes cluster provisioning
title: ''
---

## Kubernetes cluster provisioning
The goal of the Kubernetes Cluster deployment phase is to create a new RKE2 or K3s cluster using the available [MachineInventories](machineinventory-reference.md), i.e., the hosts that have successfully completed the [Machine onboarding](architecture-machineonboarding.md) phase.

The Elemental Kubernetes cluster deployment involves the following steps:
* The user creates a [MachineInventorySelectorTemplate](machineinventoryselectortemplate-reference.md) resource: it allows to define a _selector_ to identify a subset of the available [MachineInventories](machineinventory-reference.md) based on the value of their labels.
* The user defines a [Rancher cluster](cluster-reference.md) and adds to the `machinePools` definition a reference to the [MachineInventorySelectorTemplate](machineinventoryselectortemplate-reference.md) created in the step before.
* The [Rancher RKE2/K3s Cluster provisioning](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-uuides/launch-kubernetes-with-rancher#rke2) reacts to the Rancher cluster resource creation by generating a number of [MachineInventorySelectors](machineinventoryselector-reference.md) resources equal to the _quantity_ specified in the _machinePools_.
* The Elemental Operator pairs each generated [MachineInventorySelector](machineinventoryselector-reference.md) resource with an available [MachineInventory](machineinventory-reference.md) and installs the [rancher-system-agent](https://github.com/rancher/system-agent) daemon on the host tracked by the [MachineInventory](machineinventory-reference.md).
The [Rancher RKE2/K3s Cluster provisioning](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-uuides/launch-kubernetes-with-rancher#rke2) takes over the K3s/RKE provisioning using [rancher-system-agent](https://github.com/rancher/system-agent) _plans_: it installs the required components (e.g., containerd, K3s, ...) and creates the configuration files till the successful deployment of the new Kubernetes cluster.
Loading