tutorial

Monitoring Clusterpedia with Vigilmon: Keeping Your Multi-Cluster Resource Encyclopedia Available

How to monitor Clusterpedia with Vigilmon — tracking API server availability, cluster sync agents, storage backend health, and resource indexing freshness across your multi-cluster fleet.

Clusterpedia is a multi-cluster resource synchronization platform that creates a searchable, unified encyclopedia of Kubernetes resources across many clusters. Teams use it to query any resource across every cluster through a single kubectl-compatible API endpoint, without maintaining separate kubeconfigs or context-switching between clusters. When Clusterpedia's API server goes down, cross-cluster queries fail and developer tooling that depends on the unified API breaks silently. When cluster sync agents fall behind or lose connectivity to a spoke cluster, the encyclopedia becomes incomplete and queries return false-negative results. Vigilmon gives you external monitoring that validates Clusterpedia's API availability and confirms that its cluster sync agents are operating on schedule.

What You'll Build

  • Vigilmon HTTP monitors for the Clusterpedia API server
  • Resource query probes that validate index freshness for each registered cluster
  • Heartbeat monitors for the cluster sync agents
  • Alert channels for your platform team

Prerequisites

  • Clusterpedia deployed in your hub Kubernetes cluster
  • At least one cluster registered as a PediaCluster resource
  • A free account at vigilmon.online

Why Monitoring Clusterpedia Matters

Clusterpedia underpins cross-cluster developer workflows. Its failure modes are quiet and cumulative:

API server downtime breaks all kubectl commands that target the Clusterpedia aggregated API. If developers use kubectl --cluster clusterpedia get pods -A as their standard cross-cluster view, an unmonitored Clusterpedia outage instantly degrades their ability to triage incidents.

Cluster sync agent staleness is harder to detect. Clusterpedia runs a sync agent (clustersynchro-manager) per registered cluster. If the agent loses its watch on a spoke cluster, resources in that cluster stop updating in the encyclopedia. New pods, deployments, and config changes in the spoke cluster remain invisible in Clusterpedia queries — until someone notices the last-synced timestamps are old.

Storage backend saturation causes sync agents to queue writes indefinitely. A full or slow PostgreSQL backend results in the encyclopedia lagging hours behind reality. Developers querying resource state see a historical snapshot, not the live cluster.

PediaCluster sync disruption occurs when a spoke cluster's API server is temporarily unreachable. Clusterpedia marks the PediaCluster as unhealthy, but without external monitoring, this condition can persist for hours before anyone notices.

Step 1: Monitor the Clusterpedia API Server

Clusterpedia exposes a Kubernetes-aggregated API server. Monitor its readiness endpoint to confirm it is serving requests:

# Check the Clusterpedia API server health
curl -sk https://clusterpedia.yourdomain.com/readyz
# Expected: ok

# Or through the Kubernetes API aggregation layer
kubectl get --raw /apis/clusterpedia.io/v1beta1

In the Vigilmon dashboard:

  1. Go to Add Monitor → HTTP
  2. Configure:

| Field | Value | |---|---| | Name | Clusterpedia API /readyz | | URL | https://clusterpedia.yourdomain.com/readyz | | Method | GET | | Expected status | 200 | | Response body contains | ok | | Check interval | 1 minute | | Timeout | 10 seconds | | Alert after | 2 consecutive failures |

If Clusterpedia is not directly exposed externally, create a lightweight proxy or expose the readyz endpoint via an ingress for monitoring purposes. The probe should be reachable from outside the cluster.

Step 2: Monitor Cross-Cluster Resource Queries

Add a probe that performs an actual cross-cluster resource query to validate that the encyclopedia is returning results:

# Query all pods across all synced clusters
curl -sk https://clusterpedia.yourdomain.com/apis/clusterpedia.io/v1beta1/resources/api/v1/pods \
  -H "Authorization: Bearer $CLUSTERPEDIA_TOKEN" | python3 -c "
import sys, json
data = json.load(sys.stdin)
items = data.get('items', [])
print(f'{len(items)} pods returned across clusters')
"

In Vigilmon:

| Field | Value | |---|---| | Name | Clusterpedia cross-cluster pods query | | URL | https://clusterpedia.yourdomain.com/apis/clusterpedia.io/v1beta1/resources/api/v1/pods?limit=1 | | Method | GET | | Request headers | Authorization: Bearer YOUR_READ_TOKEN | | Expected status | 200 | | Response body contains | items | | Check interval | 2 minutes | | Timeout | 15 seconds | | Alert after | 2 consecutive failures |

This probe validates the full query path: API server → storage backend → indexed resources. A failure here while the /readyz probe passes indicates a storage or query-processing issue, not an API process crash.

Step 3: Heartbeat Monitor for Cluster Sync Agents

The clustersynchro-manager watches registered PediaClusters and syncs their resources into storage. Add a heartbeat that validates sync agents are making progress:

# clusterpedia-sync-probe.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: clusterpedia-sync-probe
  namespace: clusterpedia
spec:
  schedule: "*/5 * * * *"
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: clusterpedia-monitor
          restartPolicy: OnFailure
          containers:
            - name: sync-probe
              image: bitnami/kubectl:latest
              env:
                - name: HEARTBEAT_URL
                  valueFrom:
                    secretKeyRef:
                      name: vigilmon-secrets
                      key: clusterpedia-sync-heartbeat-url
              command:
                - /bin/sh
                - -c
                - |
                  set -e

                  # Check that all PediaClusters are in a healthy sync state
                  UNHEALTHY=$(kubectl get pediacluster -o json | \
                    python3 -c "
import sys, json
data = json.load(sys.stdin)
unhealthy = [
    item['metadata']['name']
    for item in data.get('items', [])
    if item.get('status', {}).get('syncResources', []) == []
    or item.get('status', {}).get('conditions', [{}])[0].get('status') == 'False'
]
print('\n'.join(unhealthy))
")

                  if [ -z "$UNHEALTHY" ]; then
                    echo "All PediaClusters syncing normally"
                    wget -qO- "$HEARTBEAT_URL"
                    echo "Sync heartbeat sent"
                  else
                    echo "ERROR: Unhealthy PediaClusters detected:" >&2
                    echo "$UNHEALTHY" >&2
                    exit 1
                  fi

Create a ServiceAccount with read access to PediaClusters:

# clusterpedia-monitor-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: clusterpedia-monitor
  namespace: clusterpedia
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: clusterpedia-monitor
rules:
  - apiGroups: ["cluster.clusterpedia.io"]
    resources: ["pediacluster"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: clusterpedia-monitor
subjects:
  - kind: ServiceAccount
    name: clusterpedia-monitor
    namespace: clusterpedia
roleRef:
  kind: ClusterRole
  name: clusterpedia-monitor
  apiGroup: rbac.authorization.k8s.io

Create the heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat
  2. Name: Clusterpedia cluster sync
  3. Expected interval: 5 minutes
  4. Grace period: 5 minutes

Store secrets:

kubectl create secret generic vigilmon-secrets \
  --from-literal=clusterpedia-sync-heartbeat-url='https://vigilmon.online/heartbeat/YOUR_SYNC_TOKEN' \
  -n clusterpedia

Step 4: Monitor Per-Cluster Sync Freshness

For clusters where resource freshness is critical (production workloads), add a per-cluster probe that verifies the last-sync timestamp is recent:

# clusterpedia-freshness-probe.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: clusterpedia-freshness-probe
  namespace: clusterpedia
spec:
  schedule: "*/15 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: freshness-probe
              image: curlimages/curl:latest
              env:
                - name: CLUSTERPEDIA_URL
                  value: "https://clusterpedia.yourdomain.com"
                - name: CLUSTERPEDIA_TOKEN
                  valueFrom:
                    secretKeyRef:
                      name: clusterpedia-monitoring
                      key: token
                - name: TARGET_CLUSTER
                  value: "production"
                - name: HEARTBEAT_URL
                  valueFrom:
                    secretKeyRef:
                      name: vigilmon-secrets
                      key: clusterpedia-freshness-heartbeat-url
              command:
                - /bin/sh
                - -c
                - |
                  set -e

                  # Query resources for a specific cluster and check response
                  RESULT=$(curl -sf --max-time 30 \
                    -H "Authorization: Bearer $CLUSTERPEDIA_TOKEN" \
                    "$CLUSTERPEDIA_URL/apis/clusterpedia.io/v1beta1/resources/clusters/$TARGET_CLUSTER/api/v1/nodes" \
                    2>&1)

                  if echo "$RESULT" | grep -q '"items"'; then
                    echo "Production cluster resources found in encyclopedia"
                    wget -qO- "$HEARTBEAT_URL"
                    echo "Freshness heartbeat sent"
                  else
                    echo "ERROR: No resources found for cluster $TARGET_CLUSTER" >&2
                    exit 1
                  fi

Create the heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat
  2. Name: Clusterpedia production freshness
  3. Expected interval: 15 minutes
  4. Grace period: 10 minutes

Step 5: Configure Alert Channels

Route Clusterpedia alerts to your platform engineering team:

  1. In Vigilmon: Alert Channels → Add Channel → Slack Webhook
  2. Add your #platform-engineering webhook URL
  3. Assign to all Clusterpedia monitors

For sync agent failures that affect production clusters:

  1. Alert Channels → Add Channel → PagerDuty or email
  2. Add your on-call rotation
  3. Assign to the per-cluster freshness heartbeat for production clusters

What You're Now Monitoring

| Component | Monitor Type | What It Detects | |---|---|---| | Clusterpedia API /readyz | HTTP GET | API server process down, ingress unreachable | | Cross-cluster resource query | HTTP GET | Storage backend failure, query path broken | | Cluster sync agents | Heartbeat (5 min) | PediaCluster sync stalled, connectivity lost | | Production cluster freshness | Heartbeat (15 min) | Per-cluster index lag for critical workloads |

Conclusion

Clusterpedia's encyclopedia model means its failure impact is proportional to how much your team relies on unified cross-cluster queries. A stale or unavailable Clusterpedia during an incident is the worst possible time for it to fail — operators reach for cross-cluster views precisely when investigating production problems. External monitoring with Vigilmon validates the API surface and sync pipeline from outside the cluster, so you know the encyclopedia is current before your team depends on it.

Get started free at vigilmon.online. The API readyz probe and sync agent heartbeat give you Clusterpedia's two most critical signals in under ten minutes: is the API accepting queries, and are spoke cluster resources staying current?

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