MAAS Client Library

0.6.8 · active · verified Fri Apr 17

A client API library for interacting with MAAS (Metal as a Service). It provides a programmatic interface to manage MAAS resources like machines, networks, and storage. Currently at version 0.6.8, it has a release cadence of a few releases per year, primarily for bug fixes and minor enhancements.

Common errors

```
maas.client.errors.APIMisconfigured: Missing required configuration parameters: url, api_key
```
cause The MaasClient was initialized without providing both the MAAS URL and a valid API key.

fix Ensure `MaasClient(url="https://...", api_key="...")` receives both parameters. Check environment variables if using them.
```
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='your.maas.server', port=5240): Max retries exceeded with url: /MAAS/api/2.0/ (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at ...>: Failed to establish a new connection: [Errno 111] Connection refused'))
```
cause The MAAS server could not be reached. This often indicates an incorrect URL, firewall issues, the MAAS server being down, or an invalid port.

fix Verify the MAAS URL (including port 5240 and '/MAAS' suffix) is correct, check network connectivity to the MAAS server, and ensure the MAAS services are running.
```
maas.client.errors.APICallError: Authentication required
```
cause The provided MAAS API key is invalid, expired, or does not have sufficient permissions for the requested operation.

fix Check the MAAS API key for typos, ensure it is still active, and verify its permissions in the MAAS dashboard. Generate a new key if necessary.
```
maas.client.errors.APIResourceNotFound: Requested resource not found
```
cause An attempt was made to access a MAAS resource (e.g., machine by ID, network) that does not exist or is inaccessible to the current API key.

fix Double-check the resource identifier (e.g., `system_id` for a machine). Ensure the API key has permissions to view the resource.

Warnings

breaking The client API was completely reworked in version 0.6.0. Code written for versions prior to 0.6.0 will likely require significant updates to import paths, class names, and method calls.
Fix: Refer to the official documentation and examples for versions 0.6.0+ to update your codebase. Key changes include how `MaasClient` is initialized and how MAAS resources (like machines, networks) are accessed via the `client.connect()` object.
gotcha Ensure your MAAS URL includes the `/MAAS` suffix (e.g., `https://your.maas.server:5240/MAAS`). Omitting this suffix is a common mistake and will lead to connection errors or incorrect API endpoints.
Fix: Always append `/MAAS` to the base URL when configuring the `MaasClient`.
gotcha API keys for MAAS can have varying permissions and may expire. If you encounter authentication errors (e.g., 'Authentication required'), verify the API key's validity and permissions in your MAAS dashboard.
Fix: Generate a new API key from the MAAS UI if necessary, ensuring it has appropriate permissions for the operations you intend to perform.

Install

pip install python-libmaas Install stable version

Imports

MaasClient
wrong:
```
from maas import client
```
correct:
```
from maas.client import MaasClient
```
Pre-0.6.0 versions might have used direct 'maas.client' or other top-level imports before the API was reworked.
LinkMode
```
from maas.client.enum import LinkMode
```
Used for specifying link types in network configuration or similar enumerations.

Quickstart

Demonstrates connecting to a MAAS server using an API key and listing available machines. Uses environment variables for sensitive connection details and provides basic error handling.

import os
from maas.client import MaasClient
from maas.client.enum import LinkMode # Example: for network configuration

# Configure MAAS connection from environment variables or provide directly
MAAS_URL = os.environ.get("MAAS_URL", "https://your.maas.server:5240/MAAS")
MAAS_API_KEY = os.environ.get("MAAS_API_KEY", "your-maas-api-key")

if "your-maas-api-key" in MAAS_API_KEY:
    print("Warning: Please set the MAAS_API_KEY environment variable or replace 'your-maas-api-key'.")
if "your.maas.server" in MAAS_URL:
    print("Warning: Please set the MAAS_URL environment variable or replace 'your.maas.server'.")

try:
    # Initialize the client
    client = MaasClient(MAAS_URL, api_key=MAAS_API_KEY)
    
    # Connect to the MAAS API
    maas = client.connect()

    # Example: List all machines
    print("Fetching machines...")
    machines = maas.machines.list()
    if machines:
        print(f"Found {len(machines)} machines:")
        for machine in machines[:3]: # Print details for up to 3 machines
            print(f"  - Hostname: {machine.hostname}, Status: {machine.status}, ID: {machine.system_id}")
            if machine.ip_addresses:
                print(f"    IPs: {[ip.ip for ip in machine.ip_addresses]}")
            else:
                print("    No IP addresses found.")
    else:
        print("No machines found in MAAS.")

    # Example: Get a specific machine (uncomment and replace with a known system_id)
    # machine_id = "your_machine_system_id" 
    # if machine_id != "your_machine_system_id":
    #     try:
    #         specific_machine = maas.machines.get(system_id=machine_id)
    #         print(f"\nDetails for machine {machine_id}: {specific_machine.hostname}, {specific_machine.status}")
    #     except Exception as e:
    #         print(f"\nCould not fetch machine {machine_id}: {e}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →