Add Btrfs fallback for other Linux distros

docs/explanation/architecture/components.rst

@@ -258,8 +258,9 @@ used for temporary storage during workshop rebuild operations.
 Storage backends
 ~~~~~~~~~~~~~~~~
 
-|ws_markup| uses ZFS for storage on Linux,
-with automatic Btrfs fallback on Windows Subsystem for Linux (WSL).
+|ws_markup| uses ZFS for storage where it detects that ZFS is available,
+with automatic Btrfs fallback otherwise,
+for example on Windows Subsystem for Linux (WSL).
 Storage is managed via LXD and requires a minimum pool size of 5 GiB.
 
 The storage backend manages container root filesystems, workshop-specific data volumes,

docs/reference/workshops.rst

@@ -183,8 +183,9 @@ Storage pools and drivers
 -------------------------
 
 |ws_markup| stores its containers and data on a storage pool.
-On Linux, |ws_markup| uses ZFS,
-while on Windows Subsystem for Linux it automatically uses Btrfs.
+It uses ZFS on systems where |ws_markup| detects that ZFS is available,
+and otherwise falls back to Btrfs
+(for example on Windows Subsystem for Linux).
 This approach consolidates container images, :program:`apt` caches, SDKs
 and other workshop content under a single system.
 

docs/tutorial/part-1-get-started.rst

@@ -47,8 +47,9 @@ Prerequisites
 
 |ws_markup| is supported on Ubuntu
 and other :program:`snap`-enabled Linux distributions;
-it is also compatible with Windows Subsystem for Linux (WSL2),
-where it uses Btrfs instead of ZFS for storage.
+it is also compatible with Windows Subsystem for Linux (WSL2).
+For storage, it uses ZFS where |ws_markup| detects that ZFS is available,
+and otherwise falls back to Btrfs.
 
 |ws_markup| relies on
 `LXD 6.8+ <https://canonical.com/lxd>`_

internal/workshop/lxd/export_test.go

@@ -23,6 +23,8 @@ var (
 	HandleImageUpdate  = handleImageUpdate
 	CheckServerVersion = checkVersion
 	GenerateCNAME      = generateCNAME
+	PreferredDriver    = preferredDriver
+	DriverSupported    = driverSupported
 )
 
 func MockFirewallChecker(f func(string) string) func() {

internal/workshop/lxd/lxd_backend.go

@@ -31,6 +31,7 @@ import (
 	"slices"
 	"strconv"
 	"strings"
+	"sync"
 	"text/template"
 	"time"
 
@@ -69,7 +70,6 @@ const (
 
 var (
 	startCommandTimeout = 1 * time.Minute
-	storagePoolDriver   = "zfs"
 
 	workshopFormatsChecked = false
 )
@@ -78,10 +78,6 @@ var (
 var startCommand string
 
 func init() {
-	if osutil.IsWSL() {
-		storagePoolDriver = "btrfs"
-	}
-
 	// Order matters: capabilities (version and storage) must be validated
 	// before ensureBackendReady attempts to create the storage pool and
 	// network. Registering it as a check also lets the daemon recover after
@@ -164,19 +160,77 @@ func checkVersion(version string) error {
 	return nil
 }
 
-func checkStorageDriver(drivers []api.ServerStorageDriverInfo) error {
-	hasDriver := func(driver api.ServerStorageDriverInfo) bool {
-		return driver.Name == storagePoolDriver
+// driverSupported reports whether LXD lists the named storage driver as
+// supported. LXD builds this list by attempting to load each driver's kernel
+// module (e.g. modprobe zfs), so it reflects what the host can actually back.
+func driverSupported(supported []api.ServerStorageDriverInfo, name string) bool {
+	return slices.ContainsFunc(supported, func(d api.ServerStorageDriverInfo) bool {
+		return d.Name == name
+	})
+}
+
+// preferredDriver picks the driver for a new workshop pool: ZFS when LXD
+// reports it as supported, otherwise Btrfs.
+func preferredDriver(supported []api.ServerStorageDriverInfo) string {
+	if driverSupported(supported, "zfs") {
+		return "zfs"
+	}
+	return "btrfs"
+}
+
+// poolDriverCache stores the driver of the workshop storage pool once known.
+// ensureBackendReady records it, and pool operations reuse it instead of
+// re-querying LXD (which reloads the driver's module). The pool's driver is
+// fixed at creation, so the cached value stays accurate for the daemon's run.
+var poolDriverCache struct {
+	sync.RWMutex
+	value string
+}
+
+func setPoolDriver(driver string) {
+	poolDriverCache.Lock()
+	poolDriverCache.value = driver
+	poolDriverCache.Unlock()
+}
+
+func getPoolDriver() string {
+	poolDriverCache.RLock()
+	defer poolDriverCache.RUnlock()
+	return poolDriverCache.value
+}
+
+// poolUsesZFS reports whether the workshop storage pool is backed by ZFS. It
+// reuses the driver recorded by ensureBackendReady, falling back to querying
+// LXD if it hasn't been recorded yet.
+func poolUsesZFS(conn lxd.InstanceServer) (bool, error) {
+	driver := getPoolDriver()
+	if driver == "" {
+		pool, _, err := conn.GetStoragePool(storagePool)
+		if err != nil {
+			return false, err
+		}
+		driver = pool.Driver
+		setPoolDriver(driver)
 	}
-	if slices.ContainsFunc(drivers, hasDriver) {
+	return driver == "zfs", nil
+}
+
+// checkStoragePool verifies the workshop storage pool is usable. When the pool
+// exists but cannot be loaded, most likely because its storage driver's kernel
+// module is gone (e.g. a ZFS pool after booting a kernel without the ZFS
+// module), it returns an actionable error that puts the daemon into degraded
+// mode. A missing pool is not an error here: ensureBackendReady creates it.
+func checkStoragePool(conn lxd.InstanceServer) error {
+	_, _, err := conn.GetStoragePool(storagePool)
+	if err == nil {
 		return nil
 	}
+	if !api.StatusErrorCheck(err, http.StatusNotFound) {
+		return fmt.Errorf(`cannot use the %q storage pool, its storage driver may be unavailable (for example a ZFS pool after booting a kernel without the ZFS module): %w
+Boot into a kernel that provides the pool's storage driver, or reinstall Workshop to recreate the pool on an available driver`, storagePool, err)
+	}
 
-	// The LXD error message when creating a pool is:
-	//  Error: Error loading "zfs" module: Failed to run: modprobe -b zfs:
-	//  exit status 1 (modprobe: FATAL: Module zfs not found ...)
-	// We keep the first part for consistency, the rest doesn't add much.
-	return fmt.Errorf(`suitable storage backend not found: error loading %q module`, storagePoolDriver)
+	return nil
 }
 
 // checkStorageSpace puts the daemon into degraded mode when the workshop
@@ -238,7 +292,7 @@ func checkServerCapabilities() error {
 		return err
 	}
 
-	return checkStorageDriver(info.Environment.StorageSupportedDrivers)
+	return checkStoragePool(conn)
 }
 
 func checkWorkshopFormats() error {
@@ -296,15 +350,20 @@ func ensureBackendReady() error {
 	}
 	defer conn.Disconnect()
 
-	// Create LXD storage pool if it doesn't exist.
-	pools, err := conn.GetStoragePools()
-	if err != nil {
-		return err
-	}
-	if idx := slices.IndexFunc(pools, func(p api.StoragePool) bool { return p.Name == storagePool }); idx < 0 {
+	// Create the LXD storage pool if it doesn't exist, and record its driver so
+	// pool operations can reuse it. A missing pool returns a 404; any other
+	// error (e.g. a ZFS pool whose module is gone) is left for checkStoragePool
+	// to report as a degraded state.
+	existingPool, _, err := conn.GetStoragePool(storagePool)
+	if api.StatusErrorCheck(err, http.StatusNotFound) {
+		info, _, err := conn.GetServer()
+		if err != nil {
+			return err
+		}
+		driver := preferredDriver(info.Environment.StorageSupportedDrivers)
 		req := api.StoragePoolsPost{
 			Name:   storagePool,
-			Driver: storagePoolDriver,
+			Driver: driver,
 		}
 		op, err := conn.CreateStoragePool(req)
 		if err != nil {
@@ -313,6 +372,7 @@ func ensureBackendReady() error {
 		if err := op.Wait(); err != nil {
 			return err
 		}
+		setPoolDriver(driver)
 
 		// Ensure the new pool has enough total space available.
 		pool, etag, err := conn.GetStoragePool(storagePool)
@@ -343,8 +403,10 @@ func ensureBackendReady() error {
 
 			logger.Noticef("On ensureBackendReady: set storage pool to the minimal size: %dGiB", storagePoolMinimalGiB)
 		}
-	} else if pools[idx].Driver != storagePoolDriver {
-		return fmt.Errorf("storage pool %q already exists with a different driver: %q (expected %q)", storagePool, pools[idx].Driver, storagePoolDriver)
+	} else if err != nil {
+		return err
+	} else {
+		setPoolDriver(existingPool.Driver)
 	}
 
 	network, etag, err := conn.GetNetwork(networkName)

internal/workshop/lxd/lxd_backend_snapshots.go

@@ -346,7 +346,11 @@ func (s *Backend) TakeSnapshot(ctx context.Context, name string, snapshot worksh
 	if inst.Devices == nil {
 		inst.Devices = map[string]map[string]string{}
 	}
-	if err := mergeDevices(inst.Devices, snapshot.Sdks, name); err != nil {
+	usesZFS, err := poolUsesZFS(conn)
+	if err != nil {
+		return err
+	}
+	if err := mergeDevices(inst.Devices, snapshot.Sdks, name, usesZFS); err != nil {
 		return err
 	}
 
@@ -598,12 +602,12 @@ func mergeConfig(source, target, config map[string]string) {
 	maps.Copy(source, config)
 }
 
-func mergeDevices(source map[string]map[string]string, sdks []sdk.ContentID, w string) error {
+func mergeDevices(source map[string]map[string]string, sdks []sdk.ContentID, w string, usesZFS bool) error {
 	maps.DeleteFunc(source, func(k string, v map[string]string) bool {
 		return k != "root"
 	})
 
-	if storagePoolDriver == "zfs" {
+	if usesZFS {
 		root := maps.Clone(source["root"])
 		if source == nil || root == nil {
 			return fmt.Errorf("internal error: %q workshop has no rootfs", w)
@@ -734,7 +738,11 @@ func (s *Backend) copyInstance(src, dst lxd.InstanceServer, srcName, dstName str
 
 	req := *srcInst
 
-	if storagePoolDriver == "zfs" {
+	usesZFS, err := poolUsesZFS(dst)
+	if err != nil {
+		return err
+	}
+	if usesZFS {
 		req.Devices = maps.Clone(req.Devices)
 		root := maps.Clone(req.Devices["root"])
 		if req.Devices == nil || root == nil {

internal/workshop/lxd/lxd_backend_test.go

@@ -17,6 +17,7 @@ package lxdbackend_test
 import (
 	"testing"
 
+	"github.com/canonical/lxd/shared/api"
 	"gopkg.in/check.v1"
 
 	"github.com/canonical/workshop/internal/testutil"
@@ -134,3 +135,31 @@ func (f *LxdBeTests) TestCheckLxdVersion(c *check.C) {
 	err = lxdbackend.CheckServerVersion("6.7.9")
 	c.Assert(err, check.ErrorMatches, `(?s).*LXD server version.*is not supported.*`)
 }
+
+func driverInfo(names ...string) []api.ServerStorageDriverInfo {
+	infos := make([]api.ServerStorageDriverInfo, 0, len(names))
+	for _, n := range names {
+		infos = append(infos, api.ServerStorageDriverInfo{Name: n})
+	}
+	return infos
+}
+
+// preferredDriver keeps ZFS whenever LXD reports it, and falls back to Btrfs
+// otherwise. Detection now trusts LXD's supported-drivers list (which LXD
+// builds by trying to load each driver's module) rather than probing modules.
+func (f *LxdBeTests) TestPreferredDriver(c *check.C) {
+	c.Check(lxdbackend.PreferredDriver(driverInfo("zfs", "btrfs", "dir")), check.Equals, "zfs")
+	c.Check(lxdbackend.PreferredDriver(driverInfo("btrfs", "zfs")), check.Equals, "zfs")
+
+	c.Check(lxdbackend.PreferredDriver(driverInfo("btrfs", "dir")), check.Equals, "btrfs")
+	c.Check(lxdbackend.PreferredDriver(driverInfo("dir")), check.Equals, "btrfs")
+	c.Check(lxdbackend.PreferredDriver(nil), check.Equals, "btrfs")
+}
+
+func (f *LxdBeTests) TestDriverSupported(c *check.C) {
+	supported := driverInfo("zfs", "btrfs")
+	c.Check(lxdbackend.DriverSupported(supported, "zfs"), check.Equals, true)
+	c.Check(lxdbackend.DriverSupported(supported, "btrfs"), check.Equals, true)
+	c.Check(lxdbackend.DriverSupported(supported, "lvm"), check.Equals, false)
+	c.Check(lxdbackend.DriverSupported(nil, "zfs"), check.Equals, false)
+}