Pod Management

Manage virtual machine hosts (KVM, LXD) and compose virtual machines dynamically for flexible resource allocation.

Capabilities

Listing Pods

client.pods.list()

from maas.client import connect

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

# List all pods
pods = client.pods.list()
for pod in pods:
    print(f"Pod: {pod.name}, Type: {pod.type}")

Getting Specific Pod

client.pods.get(id)

# Get specific pod
pod = client.pods.get(1)
print(f"Available cores: {pod.available.cores}")
print(f"Available memory: {pod.available.memory} MB")

Creating Pods

Register KVM or LXD hosts as pods.

client.pods.create(**params)

Parameters:

• type (str): Pod type ('virsh' for KVM, 'lxd' for LXD)
• power_address (str): Connection address
• power_user (str, optional): Username for connection
• power_pass (str, optional): Password for connection
• name (str, optional): Pod name
• zone (str, optional): Availability zone
• pool (str, optional): Resource pool
• tags (list, optional): Tags to apply

# Create KVM pod
pod = client.pods.create(
    type='virsh',
    power_address='qemu+ssh://user@192.168.1.10/system',
    name='kvm-host-1',
    zone='default'
)

# Create LXD pod
pod = client.pods.create(
    type='lxd',
    power_address='https://192.168.1.20:8443',
    power_user='admin',
    power_pass='password',
    name='lxd-host-1'
)

Pod Properties

• id (int): Pod ID
• name (str): Pod name
• type (str): Pod type (virsh, lxd, rsd)
• architectures (list): Supported architectures
• capabilities (list): Pod capabilities
• zone (Zone): Availability zone
• tags (list): Applied tags
• cpu_over_commit_ratio (float): CPU overcommit ratio
• memory_over_commit_ratio (float): Memory overcommit ratio
• default_macvlan_mode (str): Default macvlan mode
• host (Node): Host node if pod is managed by MAAS
• available (dict): Available resources with structure:
  • cores (int): Available CPU cores
  • memory (int): Available memory in MB
  • local_storage (int): Available local storage in bytes
• used (dict): Used resources with same structure as available
• total (dict): Total resources with same structure as available

Composing Machines

Dynamically create virtual machines from pod resources with specified constraints.

pod.compose(
    cores=None,
    memory=None,
    cpu_speed=None,
    architecture=None,
    storage=None,
    hostname=None,
    domain=None,
    zone=None,
    interfaces=None
)

Parameters:

• cores (int, optional): Minimum number of CPU cores
• memory (int, optional): Minimum amount of memory in MiB
• cpu_speed (int, optional): Minimum CPU speed in MHz
• architecture (str, optional): Architecture (must be supported by pod)
• storage (str or list, optional): Storage constraint identifiers in format <label>:<size>(<tag>[,<tag>])[,<label>:...]
• hostname (str, optional): Hostname for the composed machine
• domain (int or str, optional): Domain ID or name for the machine
• zone (int, str, or Zone, optional): Zone ID, name, or Zone object
• interfaces (str or list, optional): Labeled constraint map for interface matching in format <label>:<key>=<value>[,<key2>=<value2>]

Interface Constraint Keys:

• id: Match interface with specific ID
• fabric: Match interface on specified fabric
• fabric_class: Match interface on fabric with specified class
• ip: Match interface with specified IP address
• mode: Match interface with specified mode (e.g., "unconfigured")
• name: Match interface name (e.g., "eth0")
• hostname: Match interface on node with specified hostname
• subnet: Match interface on specified subnet
• space: Match interface in specified space
• subnet_cidr: Match interface on subnet CIDR (e.g., "192.168.0.0/24")
• type: Match interface type ("physical", "vlan", "bond", "bridge", "unknown")
• vlan: Match interface on specified VLAN
• vid: Match interface on VLAN with specified VID
• tag: Match interface tagged with specified tag

Returns: Machine object

from maas.client import connect

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

# Get a pod
pod = client.pods.get(1)

# Simple composition with basic constraints
machine = pod.compose(
    cores=4,
    memory=8192,  # 8GB in MiB
    hostname='vm-web-01'
)

# Advanced composition with storage and network constraints
machine = pod.compose(
    cores=8,
    memory=16384,
    cpu_speed=2000,
    architecture='amd64/generic',
    storage=['root:50(ssd)', 'data:100(hdd)'],
    hostname='vm-db-01',
    zone='production',
    interfaces=['eth0:space=dmz,ip=10.0.1.50']
)

print(f"Composed machine: {machine.hostname} ({machine.system_id})")

Getting Pod Parameters

Retrieve power parameters for a pod.

pod.parameters()

# Get power parameters
params = pod.parameters()
print(f"Power parameters: {params}")

Updating and Deleting Pods

pod.save()
pod.refresh()
pod.delete()

# Update pod tags
pod.tags = ['production', 'kvm']
pod.save()

# Update overcommit ratios
pod.cpu_over_commit_ratio = 2.0
pod.memory_over_commit_ratio = 1.5
pod.save()

# Refresh pod data to get latest resource usage
pod.refresh()

# Delete pod
pod.delete()

Types

class Pod:
    """A pod (VM host) in MAAS."""

    id: int
    type: str
    name: str
    architectures: list
    capabilities: list
    zone: Zone
    tags: list
    cpu_over_commit_ratio: float
    memory_over_commit_ratio: float
    available: dict
    used: dict
    total: dict
    default_macvlan_mode: str
    host: Node

    def save(self) -> None: ...
    def refresh(self) -> dict: ...
    def parameters(self) -> dict: ...
    def compose(self, **kwargs) -> Machine: ...
    def delete(self) -> None: ...