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.

resources.mddocs/reference/

Resource Organization

Organize infrastructure using domains, zones, resource pools, and tags for logical grouping and access control.

Capabilities

Domains

DNS domains for organizing machines and devices.

client.domains.list()
client.domains.get(id)
client.domains.create(name, authoritative=None, ttl=None)
domain.save()
domain.delete()
from maas.client import connect

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

# List domains
domains = client.domains.list()

# Get specific domain
domain = client.domains.get(0)

# Create domain
domain = await client.domains.create(
    name='example.com',
    authoritative=True,
    ttl=300
)

# Update domain
domain.name = 'newdomain.com'
domain.ttl = 600
await domain.save()

# Delete domain
await domain.delete()

Domain properties:

  • id (int): Domain ID
  • name (str): Domain name
  • authoritative (bool): Authoritative status
  • ttl (int): DNS TTL

Availability Zones

Physical or logical groupings of machines for high availability.

client.zones.list()
client.zones.get(name)
client.zones.create(name, description=None)
zone.save()
zone.delete()
# List zones
zones = client.zones.list()

# Get specific zone
zone = client.zones.get('default')

# Create zone
zone = await client.zones.create(
    name='zone1',
    description='Primary datacenter'
)

# Update zone
zone.description = 'Primary datacenter - Updated'
await zone.save()

# Delete zone
await zone.delete()

Zone properties:

  • id (int): Zone ID
  • name (str): Zone name
  • description (str): Zone description

Resource Pools

Group machines for access control and resource management.

client.resource_pools.list()
client.resource_pools.get(id)
client.resource_pools.create(name, description=None)
pool.save()
pool.delete()
# List resource pools
pools = client.resource_pools.list()

# Get specific pool
pool = client.resource_pools.get(0)

# Create resource pool
pool = await client.resource_pools.create(
    name='production',
    description='Production servers'
)

# Update resource pool
pool.name = 'production-primary'
pool.description = 'Primary production servers'
await pool.save()

# Delete resource pool
await pool.delete()

Resource pool properties:

  • id (int): Pool ID
  • name (str): Pool name
  • description (str): Pool description

Tags

Label and categorize machines for filtering and automation.

client.tags.list()
client.tags.get(name)
Tag.read(name)
client.tags.create(name, comment=None, definition=None, kernel_opts=None)
tag.save()
tag.delete()
# List tags
tags = client.tags.list()

# Get specific tag
tag = client.tags.get('ssd')

# Read tag by name
from maas.client.viscera import Tag
tag = await Tag.read('webserver')

# Create simple tag
tag = await client.tags.create(
    name='webserver',
    comment='Web server machines'
)

# Create tag with automatic assignment
tag = await client.tags.create(
    name='has-ssd',
    definition='//node[@id="storage"]/vendor[text()="Samsung"]',
    comment='Machines with Samsung SSDs'
)

# Create tag with kernel options
tag = await client.tags.create(
    name='gpu',
    kernel_opts='nouveau.modeset=0',
    comment='Machines with GPUs'
)

# Update tag
tag.comment = 'Updated description'
tag.kernel_opts = 'nouveau.modeset=1'
await tag.save()

# Delete tag
await tag.delete()

Tag properties:

  • name (str, readonly): Tag name (primary key)
  • comment (str): Tag description
  • definition (str): XPath definition for automatic tagging
  • kernel_opts (str): Kernel options applied to tagged machines

Managing Tags on Nodes

Nodes (machines and devices) have a special managed tags collection with add/remove methods.

# Via Node object
node.tags  # TagsForNode collection
node.tags.add(tag)
node.tags.remove(tag)
# Get machine and tags
machine = client.machines.get('system_id')
webserver_tag = client.tags.get('webserver')
database_tag = client.tags.get('database')

# Add tags to machine
await machine.tags.add(webserver_tag)
await machine.tags.add(database_tag)

# Remove tag from machine
await machine.tags.remove(database_tag)

# List machine's current tags
for tag_name in machine.tags:
    print(f"Machine has tag: {tag_name}")

The TagsForNode class is a specialized collection that provides:

  • add(tag): Add a tag to the node
  • remove(tag): Remove a tag from the node
  • Iteration over tag names currently assigned to the node

Automatic Tag Assignment with XPath

Tags can automatically be assigned to machines based on hardware characteristics using XPath expressions. During commissioning, MAAS collects detailed hardware information (lshw output) and evaluates tag definitions.

XPath Definition Examples:

# Tag machines with Intel CPUs
await client.tags.create(
    name='intel-cpu',
    definition='//node[@class="processor"]/vendor[contains(text(), "Intel")]',
    comment='Machines with Intel processors'
)

# Tag machines with Samsung SSDs
await client.tags.create(
    name='samsung-ssd',
    definition='//node[@class="storage"]/vendor[text()="Samsung"]',
    comment='Machines with Samsung storage devices'
)

# Tag machines with 10GbE network cards
await client.tags.create(
    name='10gbe',
    definition='//node[@class="network"]/capacity[@value="10000000000"]',
    comment='Machines with 10 Gigabit Ethernet'
)

# Tag machines with NVIDIA GPUs
await client.tags.create(
    name='nvidia-gpu',
    definition='//node[@class="display"]/vendor[contains(text(), "NVIDIA")]',
    comment='Machines with NVIDIA GPUs'
)

# Tag machines with specific memory size (64GB or more)
await client.tags.create(
    name='high-memory',
    definition='//node[@class="memory"]/size[@units="bytes"][number(text()) >= 68719476736]',
    comment='Machines with 64GB+ RAM'
)

How Automatic Tagging Works:

  1. During commissioning, MAAS runs hardware detection (lshw)
  2. Hardware data is stored as XML
  3. Tag definitions are evaluated as XPath queries against this XML
  4. Matching machines automatically receive the tag
  5. Tags are re-evaluated on each commissioning

Viewing Hardware XML:

To develop XPath expressions, examine the hardware data from a commissioned machine:

# Get detailed hardware information
machine = client.machines.get('system_id')
details = machine.get_details()

# The 'lshw' key contains the XML hardware data
# Use this to develop and test XPath expressions