tutorial

Monitoring Cluster API (CAPI) with Vigilmon: Management Cluster Health, Provider Controllers, Machine Status & Provisioning Heartbeats

How to monitor Cluster API (CAPI) with Vigilmon — management cluster API health checks, infrastructure provider controller availability, machine provisioning status, SSL certificate monitoring, and cluster lifecycle heartbeats.

Cluster API (CAPI) brings declarative, Kubernetes-style APIs to cluster lifecycle management — provisioning, scaling, and upgrading clusters through CRD-driven controllers running in a management cluster. The management cluster hosts the CAPI core controllers alongside infrastructure provider controllers (for AWS, Azure, GCP, vSphere, and others) that translate Machine, Cluster, and MachineDeployment objects into real infrastructure. When the management cluster API is unreachable, no new clusters can be provisioned and no control plane upgrades can proceed. When an infrastructure provider controller crashes, Machine objects stay in Provisioning indefinitely without errors surfacing to operators. Vigilmon gives you external visibility into the CAPI management cluster API, provider controller health, machine provisioning pipelines, SSL certificates, and cluster lifecycle heartbeats so you catch infrastructure failures before they leave workload clusters in an unrecoverable state.

What You'll Build

  • A monitor on the CAPI management cluster health endpoint
  • A CAPI API group availability check for core and infrastructure provider CRDs
  • A machine and cluster object status endpoint check
  • SSL certificate monitoring for the management cluster
  • A heartbeat monitor confirming cluster provisioning pipelines complete on schedule

Prerequisites

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

Step 1: Verify the CAPI Management Cluster Health Endpoint

The CAPI management cluster is a standard Kubernetes cluster and exposes the standard API health endpoint:

curl https://capi-management.example.com/healthz

A healthy management cluster returns:

ok

This confirms the management cluster API server is alive and CAPI's reconciliation controllers — capi-controller-manager, capi-kubeadm-bootstrap-manager, capi-kubeadm-control-plane-manager, and your infrastructure provider manager — can process requests.

Step 2: Create a Vigilmon HTTP Monitor for the CAPI Management Cluster

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

Set alerts to trigger after 1 consecutive failure — a management cluster outage freezes all cluster provisioning, scaling, and upgrade operations. Workload clusters that lose their bootstrap tokens cannot replace failed nodes.

Step 3: Monitor CAPI Core API Groups

CAPI registers several custom resource groups on the management cluster. Confirming these groups are available verifies that CRD installation and the admission webhooks are intact after upgrades:

curl https://capi-management.example.com/apis/cluster.x-k8s.io/v1beta1 \
  -H "Authorization: Bearer your-token"

A healthy response lists resources including Cluster, Machine, and MachineDeployment. Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://capi-management.example.com/apis/cluster.x-k8s.io/v1beta1.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: MachineDeployment.
  6. HTTP Headers: Authorization: Bearer your-token.
  7. Label: CAPI Core API Group.
  8. Click Save.

Authentication: Use kubectl create token in the capi-system namespace to generate a short-lived bearer token.

Step 4: Monitor Infrastructure Provider API Groups

Each infrastructure provider (AWS, Azure, GCP, vSphere, etc.) registers its own API group. Monitoring your provider's group confirms the infrastructure provider controller is healthy and can translate CAPI Machine objects into real VMs:

# Example: AWS provider (CAPA)
curl https://capi-management.example.com/apis/infrastructure.cluster.x-k8s.io/v1beta2 \
  -H "Authorization: Bearer your-token"

A healthy AWS provider response lists AWSCluster and AWSMachine resources. Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://capi-management.example.com/apis/infrastructure.cluster.x-k8s.io/v1beta2.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: AWSCluster (replace with your provider's resource name).
  6. Label: CAPI Infrastructure Provider API.
  7. Click Save.

Repeat this monitor for the bootstrap provider (bootstrap.cluster.x-k8s.io) and the control-plane provider (controlplane.cluster.x-k8s.io) if you want coverage across all provider layers.

Step 5: Monitor Cluster Object Availability

The Cluster list endpoint confirms the CAPI core controller is reconciling cluster objects and the management cluster etcd backend is healthy. A healthy response lists all managed Cluster objects; an empty fleet returns an empty array:

curl "https://capi-management.example.com/apis/cluster.x-k8s.io/v1beta1/clusters" \
  -H "Authorization: Bearer your-token"

A healthy response includes:

{"kind":"ClusterList","apiVersion":"cluster.x-k8s.io/v1beta1","items":[...]}

Add a monitor:

  1. Add Monitor → HTTP.
  2. URL: https://capi-management.example.com/apis/cluster.x-k8s.io/v1beta1/clusters.
  3. Check interval: 5 minutes.
  4. Expected status: 200.
  5. Keyword: ClusterList.
  6. Label: CAPI Cluster Object Registry.
  7. Click Save.

Step 6: Set Up Cluster Provisioning Heartbeat Monitoring

CAPI cluster provisioning pipelines create management manifests, apply them to the management cluster, and wait for the workload cluster control plane to become ready. These pipelines can silently time out if the infrastructure provider throttles API calls or the bootstrap token rotation fails. Use Vigilmon heartbeat monitoring to confirm provisioning pipelines complete on schedule:

Step 6a — Create a Heartbeat monitor in Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Name: CAPI cluster provisioning pipeline.
  3. Expected interval: 24 hours (or match your cluster creation cadence).
  4. Grace period: 60 minutes.
  5. Copy the generated ping URL (e.g., https://vigilmon.online/ping/abc123).

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

#!/bin/bash
# CAPI cluster provisioning script

# Apply cluster manifests to management cluster
kubectl --context management apply -f clusters/production-cluster/

# Wait for control plane to be ready
kubectl --context management wait cluster/production-cluster \
  --for=condition=ControlPlaneReady --timeout=1800s

# Wait for all machines to be running
kubectl --context management wait machinedeployment/production-cluster-workers \
  --for=condition=Available --timeout=600s

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

If the provisioning pipeline times out or fails before reaching the ping step, Vigilmon fires an alert after the grace period expires, surfacing stuck provisioning runs before they consume cloud quota indefinitely.

Step 7: Monitor SSL Certificates

The CAPI management cluster API is consumed by CI/CD pipelines, GitOps controllers, and developer tooling. An expired certificate breaks all automated cluster lifecycle operations:

  1. Add Monitor → SSL Certificate.
  2. Domain: capi-management.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 | |---|---|---| | Management cluster health | Non-200 or ok missing | Check management cluster nodes; kubectl get nodes | | CAPI core API group | Non-200 or MachineDeployment absent | CRD missing; check capi-controller-manager pod | | Infrastructure provider API | Non-200 or provider resource absent | Provider controller crashed; new machine provisioning blocked | | Cluster registry | Non-200 or ClusterList absent | Core controller down; no cluster reconciliation | | Provisioning heartbeat | No ping within window | Provisioning pipeline stalled; check infrastructure provider logs | | SSL certificate | < 30 days | Renew; automated tooling will fail on expiry |

Common CAPI Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Management cluster API server crash | Health endpoint unreachable; alert within 60 s | | CAPI controller CrashLoopBackOff after upgrade | Core API group monitor returns 503; alert immediately | | CRD version migration failure | API group returns 404 for new version; alert fires | | Infrastructure provider throttled by cloud API | Provider controller backs off; machines stuck Provisioning | | Bootstrap token expiry during slow provisioning | Provisioning heartbeat times out; alert after grace period | | Machine deployment rollout stalls | Cluster registry shows degraded MachineDeployment count | | SSL certificate expiry | SSL monitor fires at 30 days; CI/CD tooling breaks | | Cloud credentials expired in provider secret | Infrastructure provider returns auth errors; alert fires |

Cluster API's declarative approach to infrastructure lifecycle management creates a powerful abstraction — but that abstraction depends entirely on the management cluster API server, CAPI core controllers, and infrastructure provider controllers working together. A silent failure in any component leaves workload clusters unable to scale, recover from node failures, or receive control plane upgrades. Vigilmon's layered monitoring of the management cluster health, CAPI API group availability, infrastructure provider controller status, provisioning heartbeats, and SSL certificates gives you external visibility across every layer of the CAPI stack, so you catch failures before they stall cluster lifecycle operations or leave infrastructure in a partially provisioned state.

Start monitoring Cluster API 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