tutorial

Monitoring Apache CloudStack with Vigilmon

Apache CloudStack orchestrates your private cloud — but when the management server, system VMs, or hypervisor agents fail silently, your tenants hit walls. Here's how to monitor every critical CloudStack component with Vigilmon.

Apache CloudStack turns commodity hardware into a self-managed IaaS cloud. It's powerful, but its distributed architecture — management server, system VMs, hypervisor agents, MySQL, storage — means failures can cascade silently. A Console Proxy VM that crashes leaves users staring at blank consoles. A usage server that stops processing means billing data gaps you'll discover weeks later. Vigilmon gives you continuous eyes on every layer so you catch failures before your tenants do.

What You'll Set Up

  • HTTP availability monitor for the CloudStack management API
  • HTTPS management console availability
  • Hypervisor agent connectivity (XenServer/KVM/VMware) checks
  • MySQL database connectivity probe
  • NFS/storage backend health monitoring
  • Zone, pod, and cluster resource availability heartbeats
  • Network controller service health
  • System VM health monitors (Console Proxy, Secondary Storage)
  • Usage server and alert manager heartbeats
  • Alert channels with escalation policies

Prerequisites

  • Apache CloudStack management server running (default port 8080 HTTP / 8443 HTTPS)
  • At least one hypervisor zone configured
  • SSH access to the management server
  • A free Vigilmon account

Step 1: Monitor the Management Server API

The CloudStack management server exposes its API on port 8080 (HTTP) and 8443 (HTTPS). This is the nerve center — if it goes down, all VM operations, user portal access, and API integrations stop.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the management API URL: http://cloudstack-mgmt:8080/client/api?command=listApis&response=json
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

The listApis command requires no authentication and returns the full API list — a reliable signal that the management server is alive and serving requests.

For the HTTPS management console, add a second monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: https://cloudstack-mgmt:8443/client
  3. Enable Monitor SSL certificate → alert at 21 days.
  4. Set Expected status to 200.
  5. Click Save.

Step 2: Monitor Hypervisor Agent Connectivity

CloudStack agents run on each hypervisor host (XenServer, KVM, VMware vCenter) and communicate back to the management server over port 8250 (agent communication). When an agent loses connectivity, the management server marks the host as "Disconnected" and stops scheduling VMs to it.

Add TCP monitors for each hypervisor agent:

KVM hosts (agent port):

  1. Click Add Monitor → TCP Port.
  2. Enter the KVM host IP.
  3. Set Port to 22 (SSH, confirms host is alive) or probe the CloudStack agent port 8250 on the management server side.
  4. Set Check interval to 2 minutes.

XenServer hosts:

  1. Add TCP monitor for each XenServer host on port 443 (XAPI).

VMware (vCenter):

  1. Add TCP monitor for vCenter IP on port 443.
  2. Add TCP monitor for vCenter IP on port 902 (VMware host communication).

Label each monitor: Zone-1 / KVM-01 (10.0.0.10) — agent connectivity.

On the management server, you can also run a periodic check of host status via the API:

#!/bin/bash
# /usr/local/bin/cs-host-check.sh
HOSTS_UP=$(cloudstack-tool listHosts type=Routing state=Up | grep -c '"state":"Up"')
[ "$HOSTS_UP" -gt 0 ] && \
  curl -s https://vigilmon.online/heartbeat/HOST_HEARTBEAT_ID

Step 3: Monitor MySQL Database Connectivity

CloudStack stores all configuration, VM state, and usage data in MySQL. A database outage completely halts management operations.

Add a TCP monitor for MySQL:

  1. Click Add Monitor → TCP Port.
  2. Enter the MySQL host IP (often localhost / management server IP).
  3. Set Port to 3306.
  4. Set Check interval to 1 minute.
  5. Click Save.

For a deeper query-level check, add a heartbeat driven by a script that tests an actual CloudStack database query:

#!/bin/bash
# /usr/local/bin/cs-db-check.sh
mysql -u cloud -p"$CS_DB_PASSWORD" cloud -e \
  "SELECT COUNT(*) FROM vm_instance WHERE state='Running';" \
  > /dev/null 2>&1 && \
  curl -s https://vigilmon.online/heartbeat/DB_HEARTBEAT_ID

Run via cron every 5 minutes:

*/5 * * * * root /usr/local/bin/cs-db-check.sh

Set the Vigilmon heartbeat interval to 6 minutes to catch a missed ping.

Step 4: Monitor NFS and Storage Backend Health

CloudStack uses NFS for primary storage (VM disk images) and secondary storage (templates, snapshots, ISOs). If NFS mounts drop, VM disk operations fail and new VM deployments break.

NFS primary storage:

  1. Click Add Monitor → TCP Port.
  2. Enter the NFS server IP.
  3. Set Port to 2049.
  4. Set Check interval to 2 minutes.

NFS secondary storage:

  1. Add the same TCP monitor for the secondary storage NFS server (may be a different host).

For a mount-level check on the management server:

#!/bin/bash
# /usr/local/bin/cs-nfs-check.sh
# Verify NFS mounts are accessible
ls /mnt/primary/ > /dev/null 2>&1 && \
ls /mnt/secondary/ > /dev/null 2>&1 && \
  curl -s https://vigilmon.online/heartbeat/NFS_HEARTBEAT_ID

Run every 5 minutes. Alert immediately on missed heartbeat — NFS failures escalate fast.

Step 5: Monitor Zone, Pod, and Cluster Resource Availability

CloudStack organizes resources into zones, pods, and clusters. Each level can report resource exhaustion (no available hosts, IP pools exhausted, storage at capacity) before hard failures occur.

Add a heartbeat monitor driven by a resource availability check:

#!/bin/bash
# /usr/local/bin/cs-resources-check.sh
# Check that the zone has available capacity
ZONE_STATUS=$(curl -s "http://localhost:8080/client/api?command=listZones&available=true&response=json" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['listzonesresponse'].get('count', 0))")
[ "$ZONE_STATUS" -gt 0 ] && \
  curl -s https://vigilmon.online/heartbeat/ZONE_HEARTBEAT_ID

Set the heartbeat interval to 15 minutes. This catches zone-level resource exhaustion — a leading indicator before VM deployments start failing.

Step 6: Monitor Network Controller Service Health

CloudStack's virtual network stack (Virtual Router VMs, VPC routers, SDN controllers) is critical for tenant networking. A failed virtual router means a tenant's VMs lose internet connectivity.

Add TCP monitors for the virtual router management interface (typically accessible via the management network):

  1. For each Virtual Router VM, add a TCP monitor on the management IP (visible in CloudStack UI under Network → Virtual Routers) on port 3922 (CloudStack virtual router SSH).
  2. Set Check interval to 2 minutes.

For the network subsystem as a whole:

#!/bin/bash
# /usr/local/bin/cs-network-check.sh
VR_COUNT=$(curl -s "http://localhost:8080/client/api?command=listRouters&state=Running&response=json" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['listroutersresponse'].get('count', 0))")
[ "$VR_COUNT" -ge 0 ] && \
  curl -s https://vigilmon.online/heartbeat/NETWORK_HEARTBEAT_ID

Step 7: Monitor System VM Health

CloudStack runs two types of system VMs that are essential for operations:

  • Console Proxy VM (CPVM) — provides browser-based console access to VMs
  • Secondary Storage VM (SSVM) — handles template downloads, snapshot uploads, and ISO management

Both VMs must be in Running state. If they stop, console access breaks and template/snapshot operations queue indefinitely.

Add a heartbeat monitor for each system VM type:

#!/bin/bash
# /usr/local/bin/cs-systemvms-check.sh
CPVM_OK=$(curl -s "http://localhost:8080/client/api?command=listSystemVms&systemvmtype=consoleproxy&state=Running&response=json" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['listsystemvmsresponse'].get('count', 0))")
SSVM_OK=$(curl -s "http://localhost:8080/client/api?command=listSystemVms&systemvmtype=secondarystoragevm&state=Running&response=json" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['listsystemvmsresponse'].get('count', 0))")
[ "$CPVM_OK" -gt 0 ] && [ "$SSVM_OK" -gt 0 ] && \
  curl -s https://vigilmon.online/heartbeat/SYSTEMVM_HEARTBEAT_ID

Run every 5 minutes. Set the heartbeat interval to 6 minutes.

Additionally, add TCP monitors for the Console Proxy VM's public port to verify browser console connectivity works end-to-end:

  1. Get the CPVM public IP from CloudStack UI.
  2. Add TCP monitor for that IP on port 443 (CPVM serves consoles over HTTPS).

Step 8: Monitor Usage Server and Alert Manager

Usage Server — processes usage records for billing and quota enforcement. If it stops, usage data silently gaps out.

#!/bin/bash
# /usr/local/bin/cs-usage-check.sh
systemctl is-active --quiet cloudstack-usage && \
  curl -s https://vigilmon.online/heartbeat/USAGE_HEARTBEAT_ID

Set heartbeat interval to 10 minutes.

Alert Manager — processes CloudStack internal alerts and forwards them via configured alert methods. Monitor the cloudstack-management service process that includes alert management:

#!/bin/bash
# /usr/local/bin/cs-mgmt-check.sh
systemctl is-active --quiet cloudstack-management && \
  curl -s https://vigilmon.online/heartbeat/MGMT_HEARTBEAT_ID

Set heartbeat interval to 3 minutes — this is your primary management service.

Step 9: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add email, Slack, or PagerDuty.
  2. For the management API monitor, set Consecutive failures to 2 — brief GC pauses in the Java process can cause single probe timeouts.
  3. For system VM heartbeats, alert on the first miss (Consecutive failures = 1).
  4. For database and NFS heartbeats, alert on the first miss — these failures escalate instantly.
  5. Create a Maintenance window in Vigilmon before CloudStack version upgrades or hypervisor patching.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP :8080 | Management API listApis | Management server down | | HTTP :8443 | Management console | HTTPS portal unavailable | | TCP :3306 | MySQL host | Database connectivity loss | | TCP :2049 | NFS storage servers | Storage mount failure | | TCP :443 | Each hypervisor host | Agent connectivity loss | | Cron heartbeat | System VM check script | CPVM/SSVM crash | | Cron heartbeat | DB query check | Database query failure | | Cron heartbeat | NFS mount check | NFS mount gone stale | | Cron heartbeat | Usage server service | Billing data gap | | Cron heartbeat | Zone resource check | Capacity exhaustion |

Apache CloudStack's distributed architecture makes silent failures the norm without active monitoring. Vigilmon's combination of TCP probes, HTTP checks, and heartbeat monitors gives you a complete health picture — from the management API down to individual system VMs — so you can fix issues before tenants file support tickets.

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