tutorial

Monitoring Open Cluster Management with Vigilmon: Hub API Health, Klusterlet Status, Policy Engine & Placement Heartbeats

How to monitor Open Cluster Management (OCM) with Vigilmon — hub cluster API health checks, klusterlet connectivity, policy engine availability, SSL certificate monitoring, and placement controller heartbeats.

Open Cluster Management (OCM) is a CNCF project that provides a unified control plane for Kubernetes multi-cluster and multi-cloud environments. The hub cluster runs cluster-manager to handle ManagedCluster registration, ManifestWork propagation, and Placement scheduling, while each managed cluster runs klusterlet — a lightweight agent that maintains the tunnel to the hub and applies delegated work. When the hub API is unreachable, no policies can be enforced, no application manifests can propagate, and placement decisions are frozen. When a klusterlet loses connectivity, that cluster silently disappears from the federation without alerting operators. Vigilmon gives you external visibility into the OCM hub API, cluster registration status, policy engine availability, SSL certificates, and placement controller heartbeats so you catch federation failures before they create ungoverned clusters or stalled deployments.

What You'll Build

  • A monitor on the OCM hub API health endpoint
  • A managed cluster registration check via the OCM clusters API
  • A ManifestWork propagation endpoint check
  • SSL certificate monitoring for the OCM hub
  • A heartbeat monitor confirming placement reconciliation pipelines complete on schedule

Prerequisites

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

Step 1: Verify the OCM Hub Health Endpoint

The OCM hub cluster exposes the standard Kubernetes API health endpoint:

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

A healthy OCM hub returns:

ok

This confirms the hub API server is alive and OCM's custom resource controllers — cluster-manager, ManagedCluster registration webhook, and Placement scheduler — can process requests.

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

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

Set alerts to trigger after 1 consecutive failure — a hub outage blocks all cluster governance, policy enforcement, and application propagation across the entire OCM fleet.

Step 3: Monitor the OCM Cluster API Group

OCM registers its own API groups on the hub. Confirming the cluster.open-cluster-management.io group is available verifies that CRD installation is intact and the admission webhooks are alive:

curl https://ocm-hub.example.com/apis/cluster.open-cluster-management.io/v1 \
  -H "Authorization: Bearer your-token"

A healthy response lists the ManagedCluster resource. Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://ocm-hub.example.com/apis/cluster.open-cluster-management.io/v1.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: ManagedCluster.
  6. HTTP Headers: Authorization: Bearer your-token.
  7. Label: OCM Cluster API Group.
  8. Click Save.

Authentication: Extract a hub service account token using kubectl create token in the open-cluster-management namespace.

Step 4: Monitor Managed Cluster Registration

The ManagedCluster list confirms that klusterlet agents have registered and the hub's cluster admission controller is healthy. Missing clusters here means either the klusterlet lost connectivity or the hub's registration controller is down:

curl https://ocm-hub.example.com/apis/cluster.open-cluster-management.io/v1/managedclusters \
  -H "Authorization: Bearer your-token"

A healthy response includes:

{"kind":"ManagedClusterList","apiVersion":"cluster.open-cluster-management.io/v1","items":[...]}

Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://ocm-hub.example.com/apis/cluster.open-cluster-management.io/v1/managedclusters.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: ManagedClusterList.
  6. Label: OCM Managed Cluster Registry.
  7. Click Save.

Step 5: Monitor ManifestWork Propagation

ManifestWork is OCM's mechanism for pushing Kubernetes manifests from the hub to managed clusters. Monitoring the work.open-cluster-management.io API group confirms the work propagation controller is alive and the klusterlet agent API is healthy:

curl https://ocm-hub.example.com/apis/work.open-cluster-management.io/v1 \
  -H "Authorization: Bearer your-token"

A healthy response lists the ManifestWork resource. Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://ocm-hub.example.com/apis/work.open-cluster-management.io/v1.
  3. Check interval: 5 minutes.
  4. Expected status: 200.
  5. Keyword: ManifestWork.
  6. Label: OCM ManifestWork API.
  7. Click Save.

Step 6: Set Up Placement Reconciliation Heartbeat Monitoring

OCM Placement objects schedule workloads across managed clusters based on labels, taints, and resource availability. Automated placement pipelines can silently stall if the placement controller crashes after a hub upgrade. Use Vigilmon heartbeat monitoring to confirm placement reconciliation completes on schedule:

Step 6a — Create a Heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Name: OCM placement reconciliation pipeline.
  3. Expected interval: 1 hour (or match your reconciliation schedule).
  4. Grace period: 15 minutes.
  5. Copy the generated ping URL (e.g., https://vigilmon.online/ping/abc123).

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

#!/bin/bash
# OCM placement sync script

# Apply updated placement rules
kubectl --context hub-context apply -f placements/

# Verify placement decisions were made
kubectl --context hub-context wait placementdecision \
  -l cluster.open-cluster-management.io/placement=my-placement \
  --for=condition=PlacementSatisfied --timeout=300s

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

If the pipeline fails before reaching the ping step, Vigilmon fires an alert after the grace period expires, surfacing stalled placement decisions that leave clusters out of the workload rotation.

Step 7: Monitor SSL Certificates

The OCM hub API is consumed by klusterlet agents on every managed cluster — an expired certificate breaks klusterlet reconnections across the entire fleet and blocks all subsequent manifest propagation:

  1. Add Monitor → SSL Certificate.
  2. Domain: ocm-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 cluster-manager pod; kubectl get pods -n open-cluster-management | | Cluster API group | Non-200 or ManagedCluster absent | CRD registration lost; check hub webhooks | | Cluster registry | Non-200 or ManagedClusterList absent | Registration controller down; klusterlets cannot join | | ManifestWork API | Non-200 or ManifestWork absent | Work propagation controller down; no manifests pushed | | Placement heartbeat | No ping within window | Placement controller stalled; clusters miss workload scheduling | | SSL certificate | < 30 days | Renew; klusterlet reconnections will fail fleet-wide on expiry |

Common OCM Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Hub API server pod crash | Health endpoint unreachable; alert within 60 s | | Registration controller crash after upgrade | Cluster registry returns 500; new clusters cannot register | | CRD migration failure | API group monitors return 404; alert immediately | | Klusterlet network partition on member cluster | Registry shows stale cluster heartbeat; ManifestWork delivery stalls | | Work propagation controller OOM killed | ManifestWork API degrades; manifest pushes freeze | | Placement controller crash | Placement heartbeat times out; new clusters miss workload scheduling | | SSL certificate expiry | SSL monitor fires at 30 days; klusterlet reconnections fail fleet-wide | | Hub token rotation not propagated to klusterlets | API monitors return 401 from agents; alert fires |

OCM's hub-spoke architecture puts a single control plane in charge of governance, workload placement, and manifest propagation for an entire fleet of Kubernetes clusters. A silent hub failure means policies stop enforcing, new workloads go unscheduled, and klusterlet agents operate in isolation with no updates — often for hours before operators notice. Vigilmon's layered monitoring of the hub health, cluster API availability, managed cluster registry, ManifestWork propagation, placement heartbeats, and SSL certificates gives you external visibility across every component of the OCM control plane, so you catch failures before they create ungoverned clusters or leave your fleet in an inconsistent state.

Start monitoring Open Cluster Management 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