Monitoring Flux CD with Vigilmon

Flux CD is a GitOps continuous delivery tool that keeps your Kubernetes cluster in sync with Git repositories. When Flux is healthy, infrastructure changes flow from commits to the cluster automatically. When a Flux component crashes or loses connectivity to Git or your image registry, reconciliation stops — and your cluster drifts silently from the desired state while deployments queue up undelivered. Vigilmon provides continuous monitoring across every Flux CD component so you catch failures before they block your entire delivery pipeline.

What You'll Set Up

Health endpoint monitors for core Flux components
Git repository connectivity check
Image registry connectivity monitor
SSL certificate alerts for webhook receivers
Heartbeat to confirm reconciliation is running

Prerequisites

Flux CD installed in your Kubernetes cluster (flux-system namespace)
Git source configured (GitHub, GitLab, or Gitea)
A free Vigilmon account

Step 1: Monitor Flux Component Health Endpoints

Flux CD deploys several controllers in the flux-system namespace, each exposing /healthz and /readyz endpoints. The key controllers to monitor are:

source-controller — pulls from Git and Helm repositories
kustomize-controller — applies kustomizations to the cluster
helm-controller — manages Helm releases
notification-controller — handles alerts and webhook receivers

Expose health endpoints for monitoring:

# Expose source-controller health check
kubectl port-forward svc/source-controller 9090:80 -n flux-system

For persistent monitoring, create ClusterIP services and expose them via Ingress or use kubectl proxy. Then add a Vigilmon monitor for each controller:

Log in to vigilmon.online and click Add Monitor.
Set Type to HTTP / HTTPS.
Enter the health URL: http://source-controller.flux-system.svc.cluster.local/healthz.
Set Expected HTTP status to 200.
Set interval to 1 minute.
Click Save.

Repeat for each controller. A readyz failure on source-controller means Git polling has stopped; a kustomize-controller failure means cluster state is no longer being reconciled.

Step 2: Check the Flux Notification API

The Flux notification-controller handles incoming webhooks (GitHub push events, GitLab webhooks) that trigger immediate reconciliation. If it goes down, you lose push-triggered syncs and fall back to polling intervals only.

Check its availability:

# Get notification-controller service
kubectl get svc notification-controller -n flux-system

# Test health
kubectl exec -n flux-system deploy/source-controller -- \
  wget -qO- http://notification-controller/healthz

Add a dedicated Vigilmon monitor for the notification controller if you expose it externally via a webhook receiver:

Click Add Monitor → HTTP / HTTPS.
URL: https://flux-webhook.yourdomain.com/hook/YOUR_RECEIVER_TOKEN.
Set Expected HTTP status to 200 or 404 — a 404 confirms the service is alive even without a matching event.
Enable Monitor SSL certificate.
Set interval to 2 minutes.
Click Save.

Step 3: Monitor Git Repository Connectivity

Flux's source-controller polls your Git repositories on a defined interval (default: 1 minute). If the Git host becomes unreachable or credentials expire, reconciliation silently stops at the source level.

Check source status from the CLI:

flux get sources git --all-namespaces
# NAME          REVISION              SUSPENDED  READY   MESSAGE
# flux-system   main/abc123           False      True    stored artifact

A Ready: False status with an auth error means the Git source has stopped syncing. Add a Vigilmon TCP monitor to catch connectivity issues proactively:

Click Add Monitor → TCP Port.
For GitHub over SSH: github.com:22. For HTTPS: use an HTTP monitor on https://github.com.
For self-hosted Gitea: gitea.yourdomain.com:22 or :3000.
Set interval to 2 minutes.
Click Save.

A TCP failure on your Git host port immediately explains why Flux sources are failing to update.

Step 4: Heartbeat for Reconciliation Compliance

Knowing Flux components are healthy is different from knowing reconciliation is actually running. Add a Vigilmon cron heartbeat that confirms Flux is successfully reconciling on schedule:

In Vigilmon, click Add Monitor → Cron Heartbeat.
Set the interval to 10 minutes (slightly longer than your Flux sync interval).
Copy the heartbeat URL.
Create a Kubernetes CronJob that checks reconciliation status and pings Vigilmon:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: flux-reconcile-heartbeat
  namespace: flux-system
spec:
  schedule: "*/10 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: flux-heartbeat
          containers:
          - name: check
            image: fluxcd/flux-cli:latest
            command:
            - /bin/sh
            - -c
            - |
              STATUS=$(flux get kustomizations --all-namespaces \
                -o json | jq -r '[.[] | .status.conditions[] | 
                select(.type=="Ready") | .status] | 
                all(. == "True")')
              if [ "$STATUS" = "true" ]; then
                wget -q https://vigilmon.online/heartbeat/YOUR_ID -O /dev/null
              fi
          restartPolicy: OnFailure

If any kustomization stops reconciling successfully, the heartbeat stops and Vigilmon alerts within the next interval.

Step 5: Image Registry Connectivity

If you use Flux's image automation controllers to update container image tags automatically, monitor connectivity to your image registry:

Click Add Monitor → TCP Port.
For Docker Hub: registry-1.docker.io:443.
For a self-hosted registry: registry.yourdomain.com:5000.
Set interval to 5 minutes.
Click Save.

Check image repository status:

flux get images repository --all-namespaces

A registry TCP failure explains image update failures before they cascade into stalled automation.

Step 6: SSL Certificate Alerts for Webhook Receivers

Flux webhook receivers accept push events from Git providers over HTTPS. If the TLS certificate on your receiver endpoint expires, GitHub or GitLab will reject the webhook delivery and Flux falls back to polling-only mode.

Open the notification-controller HTTP monitor from Step 2.
Enable Monitor SSL certificate.
Set Alert when certificate expires in less than 21 days.
Click Save.

Check your webhook receiver's TLS configuration:

kubectl get receiver -n flux-system
kubectl describe receiver github-receiver -n flux-system

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP / healthz | Each Flux controller | Controller crash, pod restart loop | | HTTP / notification API | Webhook receiver endpoint | Push-triggered sync disabled | | TCP / Git host | :22 or :443 | Git unreachable, auth expired | | TCP / Image registry | Registry :443 | Image automation stalled | | SSL certificate | Webhook receiver | Provider rejects webhook delivery | | Cron heartbeat | Heartbeat URL | Reconciliation stopped or failing |

Flux CD's GitOps model works seamlessly when everything is healthy — but its failure modes are quiet. A controller crash, a lost Git credential, or an expired webhook certificate all stop delivery silently. With Vigilmon monitoring each Flux controller's health endpoints, Git and registry connectivity, SSL certificates, and reconciliation heartbeats, you get immediate visibility into the health of your entire GitOps pipeline.