CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-python-libmaas

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Python LibMAAS

A comprehensive Python client library for MAAS (Metal as a Service) 2.0+ servers, providing machine provisioning, network management, and storage configuration with both synchronous and asynchronous support.

Package Information

  • Package: python-libmaas
  • Type: PyPI
  • Installation: pip install python-libmaas
  • Python: 3.6+

Quick Start

from maas.client import connect

# Connect to MAAS
client = connect('http://maas.example.com:5240/MAAS/', apikey='key:token:secret')

# Allocate and deploy a machine
machine = client.machines.allocate(cpu_count=4, mem=8192)
machine.deploy(distro_series='jammy')

→ Complete Quick Start Guide

Core Concepts

API Layers

  1. Facade API (High-Level) - Simple interface via Client object from connect() or login()
  2. Viscera API (Mid-Level) - Object-oriented access via Origin for fine-grained control
  3. Bones API (Low-Level) - Direct HTTP session via SessionAPI for advanced use cases

All layers support both sync and async operation, automatically adapting to execution context.

Authentication

from maas.client import connect, login

# API key authentication
client = connect(url, apikey='consumer:token:secret')

# Username/password authentication  
client = login(url, username='admin', password='pass')

→ Authentication Details

Capabilities Overview

CapabilityDescriptionReference
MachinesAllocate, deploy, commission, power controlmachines.md
DevicesTrack non-deployable network infrastructuredevices.md
ControllersManage rack and region controllerscontrollers.md
NetworkConfigure fabrics, VLANs, subnets, spacesnetwork.md
InterfacesManage physical, bond, bridge, VLAN interfacesinterfaces.md
StorageBlock devices, partitions, filesystemsblock-devices.md
RAIDSoftware RAID arrays (0, 1, 5, 6, 10)raids.md
LVMVolume groups and logical volumesvolume-groups.md
BcacheSSD caching for HDDsbcache.md
UsersAccount and SSH key managementusers.md
Boot ResourcesOS images and boot sourcesboot-resources.md
OrganizationDomains, zones, pools, tagsresources.md
PodsVM host management (KVM, LXD)pods.md
EventsSystem event monitoringevents.md
SystemConfiguration and version infosystem.md

Quick Reference

Common Operations

# Machine lifecycle
machines = client.machines.list()
machine = client.machines.get(system_id)
machine = client.machines.allocate(cpu_count=4, mem=8192, tags=['ssd'])
machine.deploy(distro_series='jammy', wait=True)
machine.release(comment='Done')

# Power management
machine.power_on()
machine.power_off(stop_mode=PowerStopMode.SOFT)
state = machine.query_power_state()

# Network configuration
interface = machine.interfaces.get_by_name('eth0')
link = interface.links.create(interface, LinkMode.STATIC, 
                              subnet=subnet, ip_address='10.0.0.100')

# Storage configuration
sda = machine.block_devices.get_by_name('sda')
partition = sda.partitions.create(sda, size=107374182400)  # 100GB
partition.format('ext4')
partition.mount('/data')

Key Enumerations

from maas.client.enum import (
    NodeStatus,      # NEW, READY, ALLOCATED, DEPLOYED, etc.
    PowerState,      # ON, OFF, UNKNOWN, ERROR
    InterfaceType,   # PHYSICAL, BOND, BRIDGE, VLAN
    LinkMode,        # AUTO, DHCP, STATIC, LINK_UP
    RaidLevel,       # RAID_0, RAID_1, RAID_5, RAID_6, RAID_10
    CacheMode,       # WRITEBACK, WRITETHROUGH, WRITEAROUND
)

Error Handling

from maas.client.errors import (
    MAASException,           # Base exception
    PowerError,              # Power operation failures
    OperationNotAllowed,     # Invalid state for operation
)
from maas.client.bones.helpers import (
    ConnectError,            # Connection failures
    LoginError,              # Authentication failures
)
from maas.client.viscera.machines import (
    MachineNotFound,         # No matching machine
    FailedDeployment,        # Deployment failed
    FailedCommissioning,     # Commissioning failed
)

Async/Sync Usage

The library automatically adapts to execution context:

# Synchronous (default)
client = connect(url, apikey='key')
machines = client.machines.list()

# Asynchronous
import asyncio

async def main():
    client = await connect(url, apikey='key')
    machines = await client.machines.list()
    
asyncio.run(main())

Architecture

Client Object Structure

from maas.client.facade import Client

class Client:
    machines: Machines
    devices: Devices
    rack_controllers: RackControllers
    region_controllers: RegionControllers
    users: Users
    account: Account
    ssh_keys: SSHKeys
    fabrics: Fabrics
    vlans: Vlans
    subnets: Subnets
    spaces: Spaces
    ip_ranges: IPRanges
    static_routes: StaticRoutes
    domains: Domains
    zones: Zones
    resource_pools: ResourcePools
    tags: Tags
    pods: Pods
    boot_resources: BootResources
    boot_sources: BootSources
    events: Events
    files: Files
    maas: Type[MAAS]
    version: Version

Documentation Structure

Guides

API Reference

CLI Tool

# Profile management
maas login <profile> <url> [apikey]
maas logout <profile>

# Machine operations
maas <profile> machines list
maas <profile> machine allocate --cpu-count 4 --mem 8192
maas <profile> machine deploy <system-id> --distro-series jammy
maas <profile> machine power-on <system-id>

# Interactive shell
maas <profile> shell

→ CLI Reference

Common Patterns

Complete Deployment Workflow

from maas.client import connect
from maas.client.enum import NodeStatus

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

# Allocate with requirements
machine = client.machines.allocate(
    cpu_count=4,
    mem=8192,
    tags=['ssd', 'production']
)

# Deploy and wait
machine.deploy(distro_series='jammy', wait=True)

# Verify
if machine.status == NodeStatus.DEPLOYED:
    print(f"Deployed: {machine.hostname} at {machine.ip_addresses}")

Error Handling Pattern

from maas.client.errors import PowerError, OperationNotAllowed
from maas.client.viscera.machines import MachineNotFound, FailedDeployment

try:
    machine = client.machines.allocate(cpu_count=8, mem=16384)
    machine.power_on(wait=True)
    machine.deploy(distro_series='jammy', wait=True)
except MachineNotFound:
    print("No matching machine available")
except PowerError as e:
    print(f"Power management failed: {e}")
except FailedDeployment as e:
    print(f"Deployment failed: {e}")
    e.obj.release()  # Release for retry

→ More Examples

Troubleshooting

Connection Issues

  • Verify URL ends with /MAAS/
  • Check network connectivity
  • For HTTPS with self-signed certs, use insecure=True

Authentication Issues

  • Verify API key format: consumer_key:token_key:token_secret
  • Check credentials are valid
  • Some installations require API key only (not username/password)

Async/Sync Confusion

  • In async functions, always use await for API calls
  • In sync functions, calls work without await
  • Use asyncio.run() to run async from sync code

→ Complete Troubleshooting Guide

Additional Resources

docs

index.md

tile.json