Controller Management

Manage MAAS rack and region controllers that provide infrastructure services like DHCP, DNS, power control, and image management.

Important: Controllers are MAAS infrastructure components and cannot be created via the API. They must be deployed and registered through MAAS installation processes. The API provides read-only access to controller information and status.

Capabilities

Rack Controllers

Rack controllers provide services like DHCP, TFTP, PXE boot, and power management to physical machines in the data center.

Rack Controller Roles:

• DHCP Server: Provides IP addresses to machines during PXE boot
• TFTP Server: Serves boot images and configuration files
• Power Management: Controls machine power states via BMC/IPMI
• Image Management: Caches boot images for fast deployment
• DNS Resolution: Can provide DNS services for managed subnets

client.rack_controllers.list()
client.rack_controllers.get(system_id)
RackController.read(system_id)

from maas.client import connect

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

# List all rack controllers
rack_controllers = client.rack_controllers.list()
for rc in rack_controllers:
    print(f"Rack: {rc.hostname}")
    print(f"  Status: {rc.status}")
    print(f"  FQDN: {rc.fqdn}")
    print(f"  Zone: {rc.zone.name}")

# Get specific rack controller
rack = client.rack_controllers.get('system_id')

# Or use RackController.read()
from maas.client.viscera import RackController
rack = await RackController.read('system_id')

Region Controllers

Region controllers provide the web UI, REST API, and coordinate rack controllers. They are the "brain" of MAAS.

Region Controller Roles:

• Web Interface: Serves the MAAS web UI
• API Server: Provides REST API for automation
• Database Management: Manages PostgreSQL database
• Coordination: Orchestrates rack controllers
• Image Import: Manages operating system image downloads
• Metadata Service: Provides cloud-init metadata to deployed machines

client.region_controllers.list()
client.region_controllers.get(system_id)
RegionController.read(system_id)

# List all region controllers
region_controllers = client.region_controllers.list()
for rc in region_controllers:
    print(f"Region: {rc.hostname}")
    print(f"  Version: {rc.version if hasattr(rc, 'version') else 'N/A'}")
    print(f"  Power State: {rc.power_state}")

# Get specific region controller
region = client.region_controllers.get('system_id')

# Or use RegionController.read()
from maas.client.viscera import RegionController
region = await RegionController.read('system_id')

Combined Region+Rack Controllers

A single MAAS node can function as both a region and rack controller (common in small deployments).

Controller Properties

Controllers inherit from Node and have these key properties:

• system_id (str, readonly): Unique system identifier
• hostname (str): Controller hostname
• fqdn (str, readonly): Fully qualified domain name
• status (NodeStatus, readonly): Current status (typically DEPLOYED for active controllers)
• architecture (str): System architecture (e.g., 'amd64/generic')
• cpus (int): Number of CPU cores
• memory (int): RAM in megabytes
• distro_series (str, readonly): Ubuntu release (e.g., 'jammy', 'focal')
• osystem (str, readonly): Operating system (typically 'ubuntu')
• power_state (PowerState, readonly): Power state (ON, OFF, UNKNOWN, ERROR)
• interface_set (list, readonly): Network interfaces
• zone (Zone, readonly): Availability zone
• service_set (list, readonly): Services running on controller (rack controllers only)

Refreshing Controller Information

controller.refresh()

# Refresh controller data from server
controller.refresh()
print(f"Updated status: {controller.status}")

Node Type Conversion

Convert generic Node objects to controller types.

node.as_rack_controller()
node.as_region_controller()

When working with nodes from generic listings, convert them to specific controller types:

from maas.client.viscera import Nodes
from maas.client.enum import NodeType

# List all nodes
nodes = Nodes.read()

for node in nodes:
    # Convert to controller types
    if node.node_type == NodeType.RACK_CONTROLLER:
        rack = node.as_rack_controller()
        print(f"Rack Controller: {rack.hostname}")
        # Access rack-specific properties
        if hasattr(rack, 'service_set'):
            print(f"  Services: {[s.name for s in rack.service_set]}")

    elif node.node_type == NodeType.REGION_CONTROLLER:
        region = node.as_region_controller()
        print(f"Region Controller: {region.hostname}")

    elif node.node_type == NodeType.REGION_AND_RACK_CONTROLLER:
        # Can convert to either type
        rack = node.as_rack_controller()
        region = node.as_region_controller()
        print(f"Combined Controller: {rack.hostname}")

Deployment Architecture

Single-Node Setup:

• One node acts as both region and rack controller
• Suitable for small environments or testing

Multi-Node Setup:

• Separate region controller(s) for management
• Multiple rack controllers distributed across network segments
• Provides high availability and better performance
• Each rack controller serves machines in its network segment