tutorial

Monitoring MAAS (Metal as a Service) with Vigilmon

MAAS is Canonical's bare metal cloud provisioning platform — but its web UI doesn't page you when region controllers go dark or machine commissioning stalls. Here's how to monitor every MAAS endpoint and service with Vigilmon.

MAAS (Metal as a Service) turns physical servers into an on-premises cloud: you enlist machines, commission them, and deploy OS images on demand — all through an API or web UI. But MAAS itself is a service that can fail, and when it does, your entire bare metal fleet becomes unmanageable. Vigilmon watches your MAAS region controllers, rack controllers, and API endpoints so you know the moment provisioning infrastructure goes offline.

What You'll Set Up

  • HTTP uptime monitor for the MAAS web UI and API
  • TCP port monitors for region and rack controller services
  • Cron heartbeat for MAAS image sync jobs
  • SSL certificate alerts for MAAS dashboard domains
  • Alert channels for on-call notification

Prerequisites

  • MAAS 3.x installed (region controller + at least one rack controller)
  • MAAS accessible via HTTP/HTTPS (default port 5240 or behind a reverse proxy)
  • A free Vigilmon account

Step 1: Monitor the MAAS API Endpoint

The MAAS REST API is the heart of the platform. Commission requests, deploy requests, and all automation flow through it. Add an HTTP monitor targeting the API health path:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your MAAS API URL: 
    http://your-maas-host:5240/MAAS/api/2.0/
    If MAAS is behind a reverse proxy on port 443: 
    https://maas.yourdomain.com/MAAS/api/2.0/
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

The API root returns a JSON response listing available endpoints — a 200 confirms the region controller and its Django application are healthy.

Step 2: Monitor the MAAS Web UI

The web dashboard is served by the same region controller process but on a separate path. Add a second monitor for the UI itself:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the UI URL: 
    http://your-maas-host:5240/MAAS/
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200.
  5. Enable Keyword check and set the expected keyword to MAAS.
  6. Click Save.

The keyword check ensures nginx or a proxy isn't returning a default page instead of the actual MAAS UI.

Step 3: Monitor Region Controller Services via TCP

MAAS region controllers expose several TCP services that rack controllers use for communication. Monitor these ports to catch partial failures where the web UI appears up but internal services have crashed:

| Service | Default Port | |---|---| | MAAS HTTP API | 5240 | | PostgreSQL (region DB) | 5432 | | MAAS internal RPC | 5250 |

For each critical port, add a TCP monitor in Vigilmon:

  1. Click Add Monitor → TCP Port.
  2. Set Host to your region controller IP or hostname.
  3. Set Port to the target port (e.g. 5240).
  4. Set Check interval to 1 minute.
  5. Click Save.

Repeat for each port. A TCP failure on port 5250 while port 5240 is up typically indicates the internal region controller daemon has crashed without taking the web server down — a situation the HTTP monitor alone would miss.

Step 4: Monitor Rack Controllers

Each rack controller handles DHCP, TFTP, and HTTP boot for its physical subnet. Add TCP monitors for rack controller services:

# Rack controller TFTP (for PXE boot)
Host: rack-controller-ip, Port: 69 (UDP — monitor with TCP ping to port 69 if supported)

# Rack controller HTTP (boot images)
Host: rack-controller-ip, Port: 5248

For the rack controller's image-serving endpoint, add an HTTP monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: 
    http://rack-controller-ip:5248/MAAS/
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200 or 301.
  5. Click Save.

If a rack controller goes offline, PXE boot for machines on its subnet will silently fail — this monitor surfaces that before you try to deploy a server and wonder why it stalls at network boot.

Step 5: Heartbeat for MAAS Image Sync

MAAS downloads Ubuntu images, kernels, and bootloaders on a schedule. If the sync process stalls, new machine deployments will fail with stale or missing images. Use Vigilmon's cron heartbeat to verify syncs complete:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to 24 hours (or match your configured sync schedule).
  3. Copy the heartbeat URL, e.g.: 
    https://vigilmon.online/heartbeat/abc123
  4. Create a wrapper script that runs the MAAS image sync and pings on success:
#!/bin/bash
# /usr/local/bin/maas-sync-check.sh

# Trigger image sync via MAAS CLI
maas admin boot-resources import

# Wait for sync to complete (adjust timeout as needed)
sleep 60

# Check that boot resources are available
RESOURCES=$(maas admin boot-resources read | python3 -c "import sys,json; r=json.load(sys.stdin); print(len(r))")

if [ "$RESOURCES" -gt 0 ]; then
    curl -s https://vigilmon.online/heartbeat/abc123
    echo "MAAS image sync OK: $RESOURCES resources available"
else
    echo "MAAS image sync FAILED: no boot resources found" >&2
    exit 1
fi
  1. Schedule the script with cron:
crontab -e
# Add:
0 3 * * * /usr/local/bin/maas-sync-check.sh >> /var/log/maas-sync.log 2>&1

If the sync stalls or the script exits with an error, Vigilmon alerts after 24 hours without a ping.

Step 6: SSL Certificate Alerts

If MAAS is behind a reverse proxy (nginx, HAProxy) with a TLS certificate, add SSL expiry monitoring:

  1. Open the HTTP monitor you created in Step 1 or 2.
  2. Enable Monitor SSL certificate.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

MAAS itself can be a critical infrastructure dependency for your entire lab or datacenter — a surprise certificate expiry that locks operators out of the web UI is a serious outage.

Step 7: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, PagerDuty, email, or a webhook.
  2. For the MAAS API monitor, set Consecutive failures before alert to 2 — a single transient HTTP timeout shouldn't page your on-call engineer at 3 AM.
  3. For the PostgreSQL TCP monitor (port 5432), set Consecutive failures to 1 — a database failure is immediately critical.

To integrate with a webhook endpoint for your ops tooling:

# Example: POST to a Slack incoming webhook
curl -X POST https://vigilmon.online/api/alert-channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "MAAS Ops Slack",
    "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  }'

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP API | :5240/MAAS/api/2.0/ | Region controller crash, Django failure | | HTTP UI | :5240/MAAS/ | UI unavailable, proxy misconfiguration | | TCP port 5250 | Region controller | Internal RPC daemon crash | | HTTP rack | :5248/MAAS/ | Rack controller offline, PXE boot broken | | Cron heartbeat | Image sync script | Stalled sync, missing boot resources | | SSL certificate | MAAS domain | Expired cert locks out operators |

MAAS transforms physical servers into on-demand cloud capacity — but only as long as MAAS itself stays healthy. With Vigilmon monitoring your region controllers, rack controllers, and sync jobs, you catch provisioning infrastructure failures before they cascade into failed deployments and helpless operators staring at machines stuck at PXE boot.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles