tutorial

Monitoring ClusterNet with Vigilmon: Hub API Health, Agent Connectivity, Multi-Cluster Service Discovery & Deployment Heartbeats

How to monitor ClusterNet (Kubernetes multi-cluster networking and management) with Vigilmon — hub API server health checks, agent cluster connectivity, service discovery availability, SSL certificate monitoring, and scheduler heartbeats.

ClusterNet is a Kubernetes multi-cluster networking and management platform that adopts a hub-spoke model: a central hub cluster acts as the control plane, while agent clusters connect to the hub and receive workloads via ClusterNet's CRD-based scheduling and overlay networking. The hub runs the clusternet-hub controller that serves the ClusterNet API, and each member cluster runs clusternet-agent to maintain the connection back to the hub. When the hub API is down, no multi-cluster scheduling decisions can be made and workload placements freeze. When an agent loses its tunnel to the hub, that member cluster silently falls out of the federation and no warnings reach cluster operators. Vigilmon gives you external visibility into the ClusterNet hub API, agent cluster availability, multi-cluster service endpoints, SSL certificates, and scheduler heartbeats so you catch federation failures before they block cross-cluster deployments.

What You'll Build

  • A monitor on the ClusterNet hub API health endpoint
  • An agent cluster connectivity check via the ClusterNet subscriptions API
  • A multi-cluster service discovery endpoint check
  • SSL certificate monitoring for the ClusterNet hub
  • A heartbeat monitor confirming scheduled multi-cluster sync jobs complete on time

Prerequisites

  • A running ClusterNet installation with clusternet-hub exposed at a URL
  • ClusterNet hub API accessible over HTTPS (via an Ingress or LoadBalancer)
  • A free account at vigilmon.online

Step 1: Verify the ClusterNet Hub Health Endpoint

The ClusterNet hub embeds the Kubernetes API server and exposes a standard readiness probe:

curl https://clusternet-hub.example.com/healthz

A healthy ClusterNet hub returns:

ok

This confirms the hub API server is alive and able to process CRD operations including ManagedCluster, Subscription, and Base resources.

Step 2: Create a Vigilmon HTTP Monitor for the ClusterNet Hub

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://clusternet-hub.example.com/healthz.
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: ok.
  7. Label: ClusterNet Hub Health.
  8. Click Save.

Set alerts to trigger after 1 consecutive failure — a hub outage blocks all multi-cluster scheduling, application propagation, and cluster registration operations across the entire federation.

Step 3: Monitor the ClusterNet API Discovery Endpoint

Beyond the health check, the API discovery endpoint confirms ClusterNet's custom resource groups are registered and the hub is serving federation objects:

curl https://clusternet-hub.example.com/apis/clusters.clusternet.io/v1beta1 \
  -H "Authorization: Bearer your-token"

A healthy response returns a resource list including ManagedCluster. Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://clusternet-hub.example.com/apis/clusters.clusternet.io/v1beta1.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: ManagedCluster.
  6. HTTP Headers: Authorization: Bearer your-token.
  7. Label: ClusterNet API Groups.
  8. Click Save.

Authentication: Use kubectl create token against your hub cluster's service account, or extract a long-lived token from the hub kubeconfig.

Step 4: Monitor Managed Cluster Registration

The ManagedCluster list endpoint confirms that agent clusters are registered and the hub's cluster registry is healthy. A degraded registry means newly provisioned clusters cannot join and existing clusters may lose their scheduling slot:

curl https://clusternet-hub.example.com/apis/clusters.clusternet.io/v1beta1/managedclusters \
  -H "Authorization: Bearer your-token"

A healthy response includes:

{"kind":"ManagedClusterList","apiVersion":"clusters.clusternet.io/v1beta1","items":[...]}

Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://clusternet-hub.example.com/apis/clusters.clusternet.io/v1beta1/managedclusters.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: ManagedClusterList.
  6. Label: ClusterNet Managed Cluster Registry.
  7. Click Save.

Step 5: Monitor Multi-Cluster Subscription Propagation

ClusterNet uses Subscription objects to schedule workloads across member clusters. Monitoring the subscriptions endpoint verifies the scheduler controller is alive and the hub etcd backend is healthy:

curl https://clusternet-hub.example.com/apis/apps.clusternet.io/v1alpha1/subscriptions \
  -H "Authorization: Bearer your-token"

A healthy response returns a SubscriptionList. Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://clusternet-hub.example.com/apis/apps.clusternet.io/v1alpha1/subscriptions.
  3. Check interval: 5 minutes.
  4. Expected status: 200.
  5. Keyword: SubscriptionList.
  6. Label: ClusterNet Subscription Scheduler.
  7. Click Save.

Step 6: Set Up Multi-Cluster Sync Heartbeat Monitoring

Automated jobs that push application updates across clusters can silently stall if the ClusterNet scheduler reconciles but a downstream cluster agent fails to apply the manifest. Use Vigilmon heartbeat monitoring to confirm sync pipelines complete on schedule:

Step 6a — Create a Heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Name: ClusterNet multi-cluster sync pipeline.
  3. Expected interval: 30 minutes (or match your sync schedule).
  4. Grace period: 10 minutes.
  5. Copy the generated ping URL (e.g., https://vigilmon.online/ping/abc123).

Step 6b — Add a ping step to your sync pipeline:

#!/bin/bash
# Multi-cluster rollout script

# Push subscription update to hub
kubectl --context hub-context apply -f subscriptions/

# Wait for propagation to all clusters
kubectl --context hub-context wait subscription/my-app \
  --for=condition=Synced --timeout=600s

# Notify Vigilmon on success
curl -fsS -m 10 https://vigilmon.online/ping/abc123

If the sync job fails before reaching the ping step, Vigilmon fires an alert after the grace period expires, surfacing stalled multi-cluster rollouts before they cause version skew across your federation.

Step 7: Monitor SSL Certificates

ClusterNet hub API is consumed by clusternet-agent processes on every member cluster and by CI/CD pipelines pushing subscriptions. An expired certificate breaks agent tunnel reconnections and blocks all automation:

  1. Add Monitor → SSL Certificate.
  2. Domain: clusternet-hub.example.com.
  3. Alert when expiry is within: 30 days.
  4. Alert again at: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

Step 8: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Hub health | Non-200 or ok missing | Check clusternet-hub pod; kubectl get pods -n clusternet-system | | API groups | Non-200 or ManagedCluster absent | CRD registration failed; restart hub controller | | Cluster registry | Non-200 or ManagedClusterList absent | Hub etcd issue; no new clusters can register | | Subscription scheduler | Non-200 or SubscriptionList absent | Scheduler controller down; workload propagation frozen | | Sync heartbeat | No ping within window | Sync pipeline stalled; check agent logs on member clusters | | SSL certificate | < 30 days | Renew; agent reconnections will fail on expiry |

Common ClusterNet Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Hub pod crash | Health endpoint unreachable; alert within 60 s | | Hub etcd backend failure | API returns 503; all monitors fire immediately | | CRD registration lost after upgrade | API groups endpoint missing ManagedCluster; alert fires | | Agent cluster network partition | Cluster registry shows stale heartbeat; subscription health degrades | | Subscription scheduler controller crash | Subscription endpoint returns 500; alert immediately | | Multi-cluster sync pipeline stalls | Heartbeat monitor alerts after grace period | | SSL certificate expiry | SSL monitor alerts at 30-day threshold; agent reconnects fail | | Token rotation breaks CI pipelines | API monitors return 401; alert fires |

ClusterNet's hub-spoke architecture creates a single control plane dependency: every workload placement, cluster registration, and overlay network configuration flows through the hub. A silent hub failure leaves member clusters operating in isolation with no new workloads scheduled and no cross-cluster service discovery updates. Vigilmon's layered monitoring of the hub health, API group availability, managed cluster registry, subscription scheduler, sync heartbeats, and SSL certificates gives you external visibility across every component of the ClusterNet federation, so you catch failures before they cause cross-cluster version skew or deployment blackouts.

Start monitoring ClusterNet in under 5 minutes — register free at vigilmon.online.

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