or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/python-libmaas@0.6.x

docs

reference

bcache.mdblock-devices.mdbones.mdboot-resources.mdcli.mdconnection.mdcontrollers.mddevices.mdenums.mdevents.mdfiles.mdfilesystems.mdinterfaces.mdmachines.mdnetwork.mdpartitions.mdpods.mdraids.mdresources.mdsystem.mdusers.mdutilities.mdviscera.mdvolume-groups.md
index.md
tile.json

tessl/pypi-python-libmaas

tessl install tessl/pypi-python-libmaas@0.6.0

Python client library for MAAS 2.0+ with sync/async support, providing machine provisioning, network management, and storage configuration.

bcache.mddocs/reference/

Bcache Configuration

Configure Bcache to use fast SSD storage as a cache layer in front of slower HDD backing devices for improved I/O performance.

Overview

Bcache allows you to use a fast SSD as a cache in front of slower spinning disks, combining the performance of SSDs with the capacity of HDDs. It consists of:

  • Cache Device: Fast storage (typically SSD) organized into cache sets
  • Backing Device: Slower storage (typically HDD) that holds the actual data
  • Bcache Device: The combined virtual device presented to the system

Capabilities

Listing Cache Sets

Retrieve all Bcache cache sets configured on a machine.

# Via Machine object
machine.bcache_cache_sets
from maas.client import connect

client = connect('http://maas.example.com:5240/MAAS/', apikey='key')

# Get a machine
machine = client.machines.get('abc123')

# List all cache sets
cache_sets = machine.bcache_cache_sets
for cs in cache_sets:
    print(f"Cache set {cs.name}: {cs.cache_device}")

Creating Cache Sets

Create a new Bcache cache set from a block device or partition.

BcacheCacheSets.create(node, cache_device)
# Create cache set from SSD block device
nvme0 = machine.block_devices.get_by_name('nvme0n1')
cache_set = await machine.bcache_cache_sets.create(machine, nvme0)

# Create cache set from partition
ssd = machine.block_devices.get_by_name('sdb')
ssd_partition = await ssd.partitions.create(ssd, size=ssd.available_size)
cache_set = await machine.bcache_cache_sets.create(machine, ssd_partition)

Deleting Cache Sets

Remove a cache set from a machine.

cache_set.delete()
# Delete cache set
cache_set = machine.bcache_cache_sets[0]
await cache_set.delete()

Listing Bcache Devices

Retrieve all Bcache devices configured on a machine.

# Via Machine object
machine.bcaches
# List all Bcache devices
bcaches = machine.bcaches
for bcache in bcaches:
    print(f"{bcache.name}: {bcache.cache_mode} - {bcache.size} bytes")

# Access by name
bcache0 = machine.bcaches.by_name['bcache0']

Creating Bcache Devices

Create a new Bcache device combining a cache set with a backing device.

Bcaches.create(
    node,
    name,
    backing_device,
    cache_set,
    cache_mode,
    uuid=None
)
from maas.client.enum import CacheMode

# Get cache set and backing device
cache_set = machine.bcache_cache_sets[0]
hdd = machine.block_devices.get_by_name('sdc')

# Create Bcache device with writeback caching
bcache = await machine.bcaches.create(
    machine,
    name='bcache0',
    backing_device=hdd,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEBACK
)

# Create Bcache with writethrough caching
bcache_safe = await machine.bcaches.create(
    machine,
    name='bcache1',
    backing_device=hdd,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITETHROUGH
)

# Create Bcache with partition as backing device
partition = await hdd.partitions.create(hdd, size=hdd.available_size)
bcache_part = await machine.bcaches.create(
    machine,
    name='bcache2',
    backing_device=partition,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEBACK
)

Updating Bcache Properties

Modify Bcache device attributes and save changes.

bcache.save()
# Update Bcache properties
bcache = machine.bcaches.get_by_name('bcache0')
bcache.cache_mode = CacheMode.WRITETHROUGH
bcache.uuid = 'new-uuid-value'

# Save changes
await bcache.save()

Deleting Bcache Devices

Remove a Bcache device from a machine.

bcache.delete()
# Delete Bcache device
bcache = machine.bcaches.get_by_name('bcache0')
await bcache.delete()

Formatting and Mounting Bcache Devices

Bcache devices can be formatted and mounted like regular block devices.

# Create Bcache device
bcache = await machine.bcaches.create(
    machine,
    name='bcache0',
    backing_device=hdd,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEBACK
)

# Format and mount the virtual device
virtual_device = bcache.virtual_device
await virtual_device.format('xfs')
await virtual_device.mount('/data')

Cache Modes

Bcache supports three cache modes:

Writeback (WRITEBACK)

Write operations go to cache first, then to backing device asynchronously.

  • Performance: Highest write performance
  • Safety: Data loss risk if cache device fails before flush
  • Use case: Maximum performance when cache device is reliable
from maas.client.enum import CacheMode

bcache = await machine.bcaches.create(
    machine,
    name='bcache0',
    backing_device=hdd,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEBACK
)

Writethrough (WRITETHROUGH)

Write operations go to both cache and backing device simultaneously.

  • Performance: Better read performance, standard write performance
  • Safety: No data loss risk, writes confirmed when on backing device
  • Use case: Balanced performance and safety
bcache = await machine.bcaches.create(
    machine,
    name='bcache0',
    backing_device=hdd,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITETHROUGH
)

Writearound (WRITEAROUND)

Write operations bypass cache and go directly to backing device.

  • Performance: Fast for write-heavy workloads with infrequent reads
  • Safety: No data loss risk
  • Use case: Write-heavy workloads, sequential writes
bcache = await machine.bcaches.create(
    machine,
    name='bcache0',
    backing_device=hdd,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEAROUND
)

Complete Bcache Example

from maas.client import connect
from maas.client.enum import CacheMode

client = connect('http://maas.example.com:5240/MAAS/', apikey='key')
machine = client.machines.get('abc123')

# Step 1: Create cache set from SSD
nvme = machine.block_devices.get_by_name('nvme0n1')
cache_set = await machine.bcache_cache_sets.create(machine, nvme)
print(f"Created cache set: {cache_set.name}")

# Step 2: Create Bcache devices for HDDs
hdd1 = machine.block_devices.get_by_name('sdb')
hdd2 = machine.block_devices.get_by_name('sdc')

bcache0 = await machine.bcaches.create(
    machine,
    name='bcache0',
    backing_device=hdd1,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEBACK
)

bcache1 = await machine.bcaches.create(
    machine,
    name='bcache1',
    backing_device=hdd2,
    cache_set=cache_set,
    cache_mode=CacheMode.WRITEBACK
)

# Step 3: Format and mount Bcache devices
await bcache0.virtual_device.format('xfs')
await bcache0.virtual_device.mount('/data1')

await bcache1.virtual_device.format('xfs')
await bcache1.virtual_device.mount('/data2')

print(f"\nBcache devices created:")
print(f"  {bcache0.name}: {bcache0.size} bytes at /data1")
print(f"  {bcache1.name}: {bcache1.size} bytes at /data2")

Cache Set Properties

Cache sets have the following properties:

  • id (int, readonly): Unique cache set identifier
  • node (Node, readonly): Parent machine
  • name (str): Cache set name
  • cache_device (BlockDevice or Partition): Cache storage device

Bcache Device Properties

Bcache devices have the following properties:

  • id (int, readonly): Unique Bcache identifier
  • node (Node, readonly): Parent machine
  • name (str): Bcache device name
  • size (int, readonly): Total capacity in bytes (from backing device)
  • cache_mode (CacheMode): Current cache mode
  • uuid (str): Bcache UUID
  • backing_device (BlockDevice or Partition): Slow storage device
  • cache_set (BcacheCacheSet): Associated cache set
  • virtual_device (BlockDevice, readonly): Virtual block device representing the cached storage

Types

from maas.client.enum import CacheMode

class CacheMode:
    """Bcache cache mode enumeration."""
    WRITEBACK = "writeback"        # Write to cache first
    WRITETHROUGH = "writethrough"  # Write to both cache and backing
    WRITEAROUND = "writearound"    # Write directly to backing

Best Practices

  1. Use SSDs for cache sets: NVMe or SATA SSDs provide best performance
  2. Choose appropriate cache mode:
    • Use WRITEBACK for maximum performance with reliable SSDs
    • Use WRITETHROUGH for safety-critical data
    • Use WRITEAROUND for write-heavy workloads
  3. Size cache appropriately: Cache should be 10-20% of backing device size
  4. Monitor cache hit rates: Verify cache effectiveness in production
  5. Consider redundancy: Use RAID for cache sets in critical systems

Related Documentation

  • Block Device Management - Manage storage devices
  • Partition Management - Create partitions for cache
  • RAID Configuration - Combine Bcache with RAID
  • LVM Volume Groups - Use Bcache with LVM