{"id":10165,"library":"python-libmaas","title":"MAAS Client Library","description":"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.","status":"active","version":"0.6.8","language":"en","source_language":"en","source_url":"https://github.com/maas/python-libmaas","tags":["maas","cloud","infrastructure","api-client","ubuntu"],"install":[{"cmd":"pip install python-libmaas","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"HTTP client for API communication.","package":"requests"},{"reason":"Used for configuration parsing and data serialization (e.g., cloud-init user data).","package":"PyYAML"}],"imports":[{"note":"Pre-0.6.0 versions might have used direct 'maas.client' or other top-level imports before the API was reworked.","wrong":"from maas import client","symbol":"MaasClient","correct":"from maas.client import MaasClient"},{"note":"Used for specifying link types in network configuration or similar enumerations.","symbol":"LinkMode","correct":"from maas.client.enum import LinkMode"}],"quickstart":{"code":"import os\nfrom maas.client import MaasClient\nfrom maas.client.enum import LinkMode # Example: for network configuration\n\n# Configure MAAS connection from environment variables or provide directly\nMAAS_URL = os.environ.get(\"MAAS_URL\", \"https://your.maas.server:5240/MAAS\")\nMAAS_API_KEY = os.environ.get(\"MAAS_API_KEY\", \"your-maas-api-key\")\n\nif \"your-maas-api-key\" in MAAS_API_KEY:\n    print(\"Warning: Please set the MAAS_API_KEY environment variable or replace 'your-maas-api-key'.\")\nif \"your.maas.server\" in MAAS_URL:\n    print(\"Warning: Please set the MAAS_URL environment variable or replace 'your.maas.server'.\")\n\ntry:\n    # Initialize the client\n    client = MaasClient(MAAS_URL, api_key=MAAS_API_KEY)\n    \n    # Connect to the MAAS API\n    maas = client.connect()\n\n    # Example: List all machines\n    print(\"Fetching machines...\")\n    machines = maas.machines.list()\n    if machines:\n        print(f\"Found {len(machines)} machines:\")\n        for machine in machines[:3]: # Print details for up to 3 machines\n            print(f\"  - Hostname: {machine.hostname}, Status: {machine.status}, ID: {machine.system_id}\")\n            if machine.ip_addresses:\n                print(f\"    IPs: {[ip.ip for ip in machine.ip_addresses]}\")\n            else:\n                print(\"    No IP addresses found.\")\n    else:\n        print(\"No machines found in MAAS.\")\n\n    # Example: Get a specific machine (uncomment and replace with a known system_id)\n    # machine_id = \"your_machine_system_id\" \n    # if machine_id != \"your_machine_system_id\":\n    #     try:\n    #         specific_machine = maas.machines.get(system_id=machine_id)\n    #         print(f\"\\nDetails for machine {machine_id}: {specific_machine.hostname}, {specific_machine.status}\")\n    #     except Exception as e:\n    #         print(f\"\\nCould not fetch machine {machine_id}: {e}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.6.0 and later"},{"fix":"Always append `/MAAS` to the base URL when configuring the `MaasClient`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Generate a new API key from the MAAS UI if necessary, ensuring it has appropriate permissions for the operations you intend to perform.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `MaasClient(url=\"https://...\", api_key=\"...\")` receives both parameters. Check environment variables if using them.","cause":"The MaasClient was initialized without providing both the MAAS URL and a valid API key.","error":"maas.client.errors.APIMisconfigured: Missing required configuration parameters: url, api_key"},{"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.","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.","error":"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'))"},{"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.","cause":"The provided MAAS API key is invalid, expired, or does not have sufficient permissions for the requested operation.","error":"maas.client.errors.APICallError: Authentication required"},{"fix":"Double-check the resource identifier (e.g., `system_id` for a machine). Ensure the API key has permissions to view the resource.","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.","error":"maas.client.errors.APIResourceNotFound: Requested resource not found"}]}