Skip to content

How to upgrade longhorn installed with helm controller in air-gapped cluster

Article Number: 000022162

Environment

SUSE Rancher longhorn 
RKE2 cluster

Procedure

Overview

This guide provides a step-by-step process for installing and upgrading Longhorn in an air-gapped RKE2 cluster using the Helm Controller and containerd local image store. The approach supports environments without access to external container registries.

It demonstrates:

  • Installation of Longhorn v1.8.0
  • Upgrade to Longhorn v1.8.1

Prerequisites

  • RKE2 cluster with sudo/root access to nodes
  • kubectl configured for the cluster
  • Staging machine with internet access for downloading images and charts

Part 1: Installing Longhorn v1.8.0

Step 1: Obtain Longhorn Image List

Download the official list of Longhorn v1.8.0 images:

wget https://github.com/longhorn/longhorn/releases/download/v1.8.0/longhorn-images.txt

Step 2: Load Images into RKE2 Containerd Store

RKE2 requires container images to be present locally in /var/lib/rancher/rke2/agent/images/ on all nodes in air-gapped environments.

Methods:

  1. Manual Pull and Export:
    Follow the RKE2 Offline Image Import Guide to pull and export images listed in longhorn-images.txt.
  2. Automated Script:
    A script can automate pulling and exporting all images:
#!/bin/bash

# === CONFIG ===
IMAGE_LIST="longhorn-images.txt"
WORK_DIR="./longhorn-tars"
IMAGE_DIR="/var/lib/rancher/rke2/agent/images"
CTR="/var/lib/rancher/rke2/bin/ctr"
CONTAINERD_SOCK="/run/k3s/containerd/containerd.sock"

# === SETUP ===
mkdir -p "$WORK_DIR"

# === PROCESS IMAGES ===
while read -r image; do
  [[ -z "$image" || "$image" =~ ^# ]] && continue

  echo "Pulling image: docker.io/${image}"
  sudo $CTR --address "$CONTAINERD_SOCK" -n k8s.io images pull "docker.io/${image}"

  safe_name=$(echo "$image" | tr '/:@' '_')
  tar_file="${WORK_DIR}/${safe_name}.tar"

  echo "Exporting to: $tar_file"
  sudo $CTR --address "$CONTAINERD_SOCK" -n k8s.io images export "$tar_file" "docker.io/${image}"

  echo "Compressing: $tar_file"
  zstd -f "$tar_file"
  rm -f "$tar_file"

done < "$IMAGE_LIST"

# === COPY TO RKE2 IMAGE DIR ===
echo "Copying compressed tars to: $IMAGE_DIR"
sudo cp "$WORK_DIR"/*.tar.zst "$IMAGE_DIR/"

echo "Done..."

This script reads longhorn-images.txt, pulls each image using ctr, and exports them to the containerd local store. Perform this steps on all nodes.

Step 3: Prepare Helm Chart for v1.8.0

Download and package the Helm chart for offline use:

wget https://github.com/longhorn/longhorn/releases/download/v1.8.0/charts.tar.gz
tar -xf charts.tar.gz
cd charts
tar czf longhorn-chart.tgz longhorn
base64 -w 0 longhorn-chart.tgz > longhorn-chart.tgz.b64
cd ..

Step 4: Create HelmChart Resource

Create a HelmChart manifest to install Longhorn:

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  annotations:
    helmcharts.cattle.io/managed-by: helm-controller
  name: longhorn-install
  namespace: kube-system
spec:
  chart: longhorn
  chartContent: $(cat longhorn-chart.tgz.b64)
  createNamespace: true
  failurePolicy: abort
  repo: https://charts.longhorn.io
  # This fields in spec.set can be set as per the requirements 
  set:
    global.clusterCIDR: 10.42.0.0/16 
    global.clusterCIDRv4: 10.42.0.0/16
    global.clusterDNS: 10.43.0.10
    global.clusterDomain: cluster.local
    global.rke2DataDir: /var/lib/rancher/rke2
    global.serviceCIDR: 10.43.0.0/16
    global.systemDefaultIngressClass: ingress-nginx
  targetNamespace: longhorn-system
  version: v1.8.0

Deployment options:

  • Apply the manifest directly:
kubectl apply -f longhorn-v1.8.0.yaml

Or place it in the RKE2 manifests directory for automatic management:

cp longhorn-v1.8.0.yaml /var/lib/rancher/rke2/server/manifests/

Step 5: Verify Installation

kubectl get helmchart -n kube-system longhorn-install -w
kubectl get pods -n longhorn-system -w
kubectl -n longhorn-system get deployment longhorn-manager -o jsonpath='{.spec.template.spec.containers[0].image}'

Part 2: Upgrading Longhorn to v1.8.1

Step 1: Obtain Longhorn v1.8.1 Image List

wget https://github.com/longhorn/longhorn/releases/download/v1.8.1/longhorn-images.txt

Step 2: Load v1.8.1 Images into RKE2 Containerd Store

Use the same script as for installation: (refer to part1, step2 for more context)

sudo bash lh-images-export.sh

Step 3: Prepare Helm Chart for v1.8.1

wget https://github.com/longhorn/longhorn/releases/download/v1.8.1/charts.tar.gz
tar -xf charts.tar.gz
cd charts
tar czf longhorn-chart.tgz longhorn
base64 -w 0 longhorn-chart.tgz > longhorn-chart.tgz.b64
cd ..

Step 4: Update HelmChart Resource

Patch the existing HelmChart resource to upgrade Longhorn:

spec:
  version: v1.8.1
  chart: longhorn
  repo: https://charts.longhorn.io
  chartContent: $(cat longhorn-chart.tgz.b64)

Apply the patch:

kubectl patch helmchart longhorn-install -n kube-system --type merge --patch-file longhorn-v1.8.1-patch.yaml

Or copy to the manifests directory for consistency:

cp longhorn-v1.8.1-patch.yaml /var/lib/rancher/rke2/server/manifests/

Step 5: Monitor Upgrade

kubectl -n longhorn-system get pods -w
kubectl -n longhorn-system rollout status deployment/longhorn-manager

Step 6: Post-Upgrade Validation

  • Verify all Longhorn components are running the correct version
  • Confirm volume health and accessibility

References