Kubernetes Auto-Discovery

The UptimeHunt Kubernetes auto-discovery operator runs inside your cluster and automatically turns your Ingress resources into UptimeHunt monitoring checks. Deploy it once with an API token and every public endpoint your cluster exposes is monitored — no need to add each URL by hand, and new services are picked up as soon as their Ingress is created.

It is designed to be safe by default: it only ever adds and updates checks, and never deletes them automatically (a disappearing endpoint is often a misconfiguration you'd want to be alerted about, not silently un-monitored).

How It Works

For every Ingress it is allowed to see, the operator:

1. Reads the hostnames and paths from spec.rules.
2. Determines HTTP vs HTTPS from spec.tls (a host covered by TLS — including wildcard certificates — is monitored over HTTPS).
3. Creates one HTTP check per unique host + path combination.
4. Keeps those checks in sync as the Ingress changes (hosts/paths added, annotations updated).

Discovered checks appear in your UptimeHunt account grouped into a project named after the Kubernetes namespace (by default), tagged as Managed in the UI.

Ingress-Recreation Adoption

Each discovered check is stamped with an external_id of <ingress-uid>|<host>|<path> so the dashboard can upsert it idempotently. Because that id embeds the Ingress's Kubernetes UID, a naive implementation would break the moment an Ingress is deleted and re-applied — a GitOps sync, a Helm upgrade that recreates the object, or a CI reconcile all mint a new UID for the same logical host/path, which would otherwise look like a brand-new check to monitor and leave the old one behind as an orphan.

Instead, when a desired check's external_id matches no existing service, the operator looks for a managed service with the same <host>|<path> tail under a different UID and re-keys it in place — a PATCH of just the external_id field. The existing check keeps its:

• Service id
• Check history
• Incident links

No duplicate is created, and nothing needs to be manually re-linked.

Re-keying never resumes a paused check — a check you've paused stays paused across an adoption.

The required RBAC/API capability is covered by the same Automation service-token preset used for everything else this operator does (see Prerequisites): re-keying uses PATCH /services/{id} under the service.edit capability, so no additional token permission is needed.

Prerequisites

• A Kubernetes cluster (the operator is installed with Helm).
• An UptimeHunt organization service token, minted under Settings → Tokens → Service tokens with the automation preset. This determines which organization the discovered checks belong to.

Installation

Create a values file, then install with Helm. Store the token in a Kubernetes Secret and reference it with existingSecret to keep it out of version control (see Service Account Tokens — Kubernetes):

saas:
  url: https://app.uptimehunt.io/api/v1
  existingSecret: uptimehunt-token   # Kubernetes Secret name
  existingSecretKey: token           # key inside the Secret

discovery:
  mode: annotation-only            # or "all"

watch:
  scope: cluster                   # or "namespace"

helm install uptimehunt-kubediscovery \
  oci://ohcr.io/uptimehunt/autodiscovery/kubernetes/charts/uptimehunt-kubediscovery \
  --version 0.1.0 \
  --namespace uptimehunt-kubediscovery --create-namespace \
  -f values.yaml

Discovery Modes

Choose how the operator decides which Ingresses to monitor with discovery.mode:

kubectl annotate ingress my-app monitor.uptimehunt.io/enabled=true

kubectl annotate ingress internal-only monitor.uptimehunt.io/enabled=false

You can also restrict which ingress classes are considered, to keep internal-only ingresses out:

discovery:
  ingressClassAllow: ["public"]      # only these classes
  # or
  ingressClassDeny: ["internal"]     # everything except these

Annotations

Fine-tune individual checks with annotations under the monitor.uptimehunt.io/ prefix:

Example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    monitor.uptimehunt.io/enabled: "true"
    monitor.uptimehunt.io/name: "My App (production)"
    monitor.uptimehunt.io/interval: "1m"
    monitor.uptimehunt.io/path: "/healthz"

To monitor a webhook receiver the way the upstream provider hits it — a POST that's rejected with 403 when unsigned (meaning the endpoint is alive and verifying signatures) — probe it with POST and treat 403 as healthy:

metadata:
  annotations:
    monitor.uptimehunt.io/path: "/api/webhook/slack/interactivity"
    monitor.uptimehunt.io/method: "POST"
    monitor.uptimehunt.io/expect-status: "403"

Expect Status: Per-Path Codes

A single Ingress often exposes several paths that need different healthy-status rules — a webhook receiver that only accepts signed POST requests (403 = healthy) alongside a plain /health endpoint (200/204 = healthy). expect-status supports two forms, and stays backward compatible with every existing config:

• Legacy / bare list — a plain comma-separated list of codes, e.g. "403,404", applies to every path discovered on the Ingress. Existing configs using this form are unaffected.
• Per-path map — a ;-separated list of path=codes entries, e.g. "/hook=403;/health=200,204;500", sets the healthy codes independently per path (paths are normalized before matching). An entry with no = (like the trailing 500 above) is a bare default applied to any discovered path that isn't otherwise mapped.

metadata:
  annotations:
    monitor.uptimehunt.io/expect-status: "/hook=403;/health=200,204;500"

In this example: the /hook check treats 403 as healthy, /health treats 200 or 204 as healthy, and any other path on the Ingress falls back to treating 500 as healthy.

A malformed entry (bad path, non-numeric code, etc.) is logged and skipped — it never fails the whole reconcile; the rest of the annotation's entries still apply.

Namespace-Level Defaults

The same annotations can be set on a Namespace. Every Ingress in that namespace inherits them as defaults, which individual Ingress annotations override. This is handy for applying a setting across many services at once:

# Monitor everything in this namespace at a 5-minute interval
kubectl annotate namespace production \
  monitor.uptimehunt.io/enabled=true \
  monitor.uptimehunt.io/interval=5

An Ingress in production is then monitored every 5 minutes unless it sets its own monitor.uptimehunt.io/interval.

The precedence is:

Ingress annotation  →  Namespace annotation  →  operator default

Stopping Monitoring of a Check

To silence a discovered check — for example one of several produced by a single Ingress — use Stop monitoring (Ignore) on that check in the UptimeHunt UI. The operator will not re-enable or recreate an ignored check, so the change sticks across reconciles.

Check Removal

The operator never deletes checks automatically. If an Ingress (or one of its hosts/paths) disappears, its checks are left in place so a misconfiguration or outage keeps alerting rather than going quiet.

To let the operator prune an Ingress's checks when its paths change or it is opted out, set monitor.uptimehunt.io/allow-removal: "true". This can be set:

• Per-Ingress, affecting only that Ingress, or
• At the namespace level, where every Ingress in the namespace inherits it. An individual Ingress can opt back out with monitor.uptimehunt.io/allow-removal: "false".

To stop monitoring a single check without enabling deletion, use Stop monitoring in the UI instead.

Watch Scope

watch.scope controls the operator's RBAC and whether namespace-annotation inheritance is available. watch.namespaces is an independent filter that narrows which namespaces are watched — it applies in both scopes.

watch:
  scope: cluster
  namespaces: []          # or a subset to narrow the watch

watch:
  scope: namespace
  namespaces: ["team-a", "team-b"]

Continuous Reconciliation

Beyond reacting to Kubernetes events, the operator periodically re-applies the desired state on a timer (discovery.resyncInterval, default 10m), so any drift between the cluster and your UptimeHunt account is corrected even without new events.

Re-applies are idempotent and preserve user-controlled fields: a check's enabled state, its ignored (Stop monitoring) state, and an icon you set in the UI (when there is no icon annotation) all survive across reconciles.

Configuration Reference

Security

• The operator is read-only on your Ingresses — it never modifies them.
• It needs only get/list/watch on Ingresses (and, for cluster-wide installs, on Namespaces).
• Use a service account token with the automation preset (minted via Settings → Tokens → Service tokens), stored in a Kubernetes Secret. A service account token is preferred over a personal token because it is org-pinned, cannot gain SSO or member-management capabilities, and survives staff changes. Rotate it independently by creating a new token, updating the Secret, and revoking the old token.

Related Documentation

• Service Account / Organization Tokens — minting and managing org-pinned credentials for the operator
• Monitoring Capabilities
• Services
• HTTP Monitoring
• Settings