Monitoring Helmsman-Managed Kubernetes with Vigilmon: Service Health, TCP Ports, SSL Certificates & DSF Alerts

Helmsman is a Helm charts-as-code tool that reads a Desired State File (DSF) — a TOML or YAML file that describes which Helm charts should be installed in which Kubernetes namespaces — and reconciles the cluster to match that state. When Helmsman runs in CI and silently fails to apply an update, when a chart upgrade behind a Helmsman deployment leaves a service degraded, or when an ingress TLS certificate expires unnoticed, users see errors that helmsman plan shows as already-applied. Vigilmon gives you external visibility into every HTTP endpoint, TCP port, and SSL certificate across your Helmsman-managed cluster.

What You'll Build

• HTTP health monitors for services managed by Helmsman's DSF
• TCP port checks to verify ingress and LoadBalancer reachability
• SSL certificate monitoring for Helmsman-deployed TLS ingresses
• An alerting setup that traces fired alerts back to specific DSF app entries
• CI pipeline availability monitoring for Helmsman runs

Prerequisites

• A running Kubernetes cluster with Helmsman managing Helm chart state
• At least one service exposed through an Ingress or LoadBalancer with a health endpoint
• HTTPS configured for your externally reachable domains
• A free account at vigilmon.online

Step 1: Understand What Helmsman Manages and Where Failures Hide

Helmsman's DSF defines your desired cluster state:

# helmsman.toml excerpt
[apps]

  [apps.ingress-nginx]
    namespace  = "ingress-nginx"
    enabled    = true
    chart      = "ingress-nginx/ingress-nginx"
    version    = "4.8.3"

  [apps.api]
    namespace  = "production"
    enabled    = true
    chart      = "./charts/api"
    valuesFile = "environments/production.yaml"

Helmsman applies these entries as Helm releases, then exits. It does not run continuously. The gap between Helmsman runs is where failures accumulate invisibly:

• Chart upgrade causes pod crash-loop: Helmsman exit code is 0 but the new pods never become ready
• DSF entry disabled for maintenance, never re-enabled: service removed from cluster, users affected
• Values file references an image tag that does not exist: Helm release fails; Helmsman reports failure in CI logs nobody reads
• Ingress annotation changed in chart default values: routing breaks after chart version bump
• cert-manager app entry removed from DSF: certificates stop renewing

Vigilmon monitors the external user-facing surface of everything Helmsman deploys, catching these failures whether or not the Helmsman run itself reported an error.

Step 2: Create Health Monitors for Helmsman-Deployed Services

Map each [apps.<name>] DSF entry that exposes an external endpoint to a Vigilmon HTTP monitor.

API service:

curl https://api.example.com/health
# Expected: 200 {"status":"ok"}

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://api.example.com/health.
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: ok.
7. Label: helmsman/api production.
8. Click Save.

Use the naming convention helmsman/<app-name> <environment> so that when an alert fires you can immediately look up the corresponding DSF entry, check the Helmsman run log, and run helm status api -n production to inspect the Helm release state.

Alert sensitivity: 1 consecutive failure for production apps. Helmsman-managed services are reconciled from a stable DSF — transient 30-second blips do not occur in a healthy cluster.

Step 3: Monitor TCP Ports for Ingress Controller Availability

Helmsman typically manages the ingress controller itself as a DSF entry (e.g., [apps.ingress-nginx] or [apps.traefik]). An upgrade to that entry can break TCP-level connectivity for every downstream service monitor simultaneously:

# Verify the ingress LoadBalancer is accepting connections at the TCP level
nc -zv ingress.example.com 443

1. Add Monitor → TCP.
2. Host: your ingress controller's external hostname or IP.
3. Port: 443.
4. Check interval: 2 minutes.
5. Label: helmsman/ingress-nginx LoadBalancer.
6. Click Save.

Reading the alert pattern: When the TCP ingress monitor fires at the same time as all your HTTP service monitors, the failure is in the ingress controller DSF entry or the cloud load balancer — not in the individual application releases. Check helm status ingress-nginx -n ingress-nginx and kubectl get events -n ingress-nginx first.

Step 4: Monitor SSL Certificates for Helmsman-Managed Ingresses

Helmsman DSF entries often include cert-manager and the associated ClusterIssuer configuration. A DSF refactor that removes the cert-manager entry, changes the ClusterIssuer name, or updates the cert-manager chart to a version with a different CRD format can silently break certificate issuance:

# Inspect certificate expiry
openssl s_client -connect api.example.com:443 2>/dev/null | openssl x509 -noout -dates

For each Helmsman-managed domain:

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

DSF drift and cert-manager: When teams refactor the DSF to consolidate namespaces, cert-manager is sometimes accidentally disabled by setting enabled = false on its entry. The existing certificates continue to work until they expire — typically 90 days with Let's Encrypt. A 30-day alert window gives you two full weeks of lead time after the issue is spotted before any service goes dark.

Step 5: Monitor Your Helmsman CI Run

Helmsman is almost always run from CI. If the CI job fails, Helmsman never reconciles the cluster and the intended state is never applied. Some CI systems allow you to expose a status endpoint or trigger a webhook on job completion:

Verify the CI system's status page is reachable:

curl https://ci.example.com/health
# Or for GitHub Actions: check the repo's Actions tab is reachable

1. Add Monitor → HTTP.
2. URL: your CI status endpoint or deployment-receiver webhook URL.
3. Check interval: 5 minutes.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Label: helmsman CI runner.
7. Click Save.

If your CI does not expose a status URL, rely on the service health monitors — they catch the downstream impact of a skipped Helmsman run.

Step 6: Configure Alerting

In Vigilmon under Settings → Notifications, configure alert channels and runbooks:

| Monitor | Trigger | Action | |---|---|---| | helmsman/<app> production HTTP | Non-200 or keyword missing | Run helm status <app> -n production; inspect pod logs; review Helmsman CI run | | TCP ingress port 443 | Connection refused | Check ingress DSF entry: helm status ingress-nginx -n ingress-nginx; check cloud LB | | SSL certificate | < 30 days expiry | Check cert-manager DSF entry is enabled = true; run kubectl get certificate | | CI runner | Non-200 | Check CI logs for Helmsman exit code and error; review DSF TOML/YAML for syntax errors |

Notification routing: Route HTTP app monitors to per-team Slack channels matching your DSF namespace structure. Route TCP ingress and SSL monitors to the platform team. When a Helmsman run changes multiple DSF entries at once and causes cascading failures, the distinct alert channels help isolate which layer changed last.

Common Helmsman Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Chart upgrade causes pod crash-loop; Helmsman exits 0 | HTTP service monitor returns 502; alert within 60 s | | DSF entry accidentally disabled during refactor | HTTP service monitor fires; helm list shows release absent | | Ingress controller DSF entry upgrade breaks routing | TCP ingress monitor + all HTTP monitors fire simultaneously | | cert-manager DSF entry removed; renewals stop | SSL monitor alerts at 30-day threshold | | Helmsman CI run fails silently; stale chart version in cluster | HTTP monitor catches degraded service from outdated image | | Wrong values file applied; service misconfigured | HTTP monitor catches non-200 or missing keyword | | Cloud LoadBalancer IP changes after node pool replacement | TCP monitor and HTTP monitors fire; LB-level failure confirmed | | helmsman plan --dry-run run instead of helmsman apply in CI | No change applied; service health monitors catch any existing degradation |

Helmsman enforces your Kubernetes desired state at sync time but has no ongoing runtime visibility into whether that state remains healthy between runs. Vigilmon fills that gap with external HTTP health checks, TCP port monitoring, SSL certificate alerts, and CI pipeline availability checks — giving you continuous coverage of everything Helmsman deploys, regardless of when the next DSF reconciliation runs.

Start monitoring your Helmsman cluster in under 5 minutes — register free at vigilmon.online.