Monitor

Beta

Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.

Monitoring is being rolled out: until it is enabled on your tenant, sng apply rejects this manifest.

apiVersion	monitoring.stackngo.io/v1alpha1
kind	Monitor
Applied by	sng apply
Related commands	sng monitor create (generates and applies this manifest), sng monitor list, sng monitor delete, sng template gen Monitor

What it is for

A Monitor checks at a fixed interval that a public target responds: an HTTP(S) URL, a TCP port, or a DNS server. The platform probes it from its sites, computes its state (Up, Down, Unknown…), notifies the NotificationChannels it references when it goes down or comes back, and shows it on your StatusPages. The number of monitors and the minimum interval depend on the tenant's tier.

Minimal example

api.yml

apiVersion: monitoring.stackngo.io/v1alpha1
kind: Monitor
metadata:
  name: api
spec:
  type: HTTP
  target: https://api.example.com/health
  interval: 5m

sng apply api.yml

Equivalent: sng monitor create api --http https://api.example.com/health --interval 5m (the command also adds tls: {} for an https:// URL).

Complete annotated example

api.yml

apiVersion: monitoring.stackngo.io/v1alpha1
kind: Monitor
metadata:
  name: api                        # DNS label, at most 63 characters
spec:
  displayName: API publique        # public label (status pages, notifications), 63 chars max; default: the name
  type: HTTP                       # HTTP, TCP, DNS (ICMP: not available yet)
  target: https://api.example.com/health   # HTTP: URL; TCP: host:port; DNS: server queried
  interval: 1m                     # 30s, 1m (default), 2m, 5m, 10m — minimum depends on the tier
  timeout: 10s                     # 1s to 30s, lower than interval (default 10s)
  failureThreshold: 3              # consecutive failures before an outage, 1 to 5 (default 3)
  http:
    method: GET                    # GET (default), HEAD, POST
    expectedStatusCodes: [200, 204]  # empty: any 2xx
    bodyMustContain: '"status":"ok"' # literal text expected in the body (256 chars max)
    bodyMustNotContain: maintenance  # literal text that makes the check fail
    followRedirects: true          # default
    headers:                       # at most 10, plaintext values: never a secret
      - { name: Accept, value: application/json }
    insecureSkipVerify: false      # true: accepts an invalid certificate
    ipFamily: ip4                  # ip4 (default), ip6, auto
  tls:                             # expiry alerts for the target's certificate
    expiryWarningDays: 14          # 1 to 90 (default 14)
    expiryCriticalDays: 3          # 1 to 90, ≤ expiryWarningDays (default 3)
  notificationChannelRefs:         # tenant channels to notify, at most 10
    - name: ops
  paused: false                    # true: suspends checks without losing history

Other types:

# TCP, with TLS negotiation and certificate alerts
spec:
  type: TCP
  target: mail.example.com:465
  tcp: { tls: true }
  tls: {}
---
# DNS: asks ns1.example.com for the MX record of example.com
spec:
  type: DNS
  target: ns1.example.com
  dns:
    queryName: example.com
    queryType: MX                  # A (default), AAAA, CNAME, MX, NS, TXT, SOA
    expectedRcode: NOERROR         # NOERROR (default) or NXDOMAIN

Fields

Cross-field validation rules

The schema rejects, as early as sng apply:

• type: HTTP with a target that does not start with http:// or https://; conversely, a URL for any other type;
• type: TCP with a target other than host:port (or [ipv6]:port);
• http on a type other than HTTP, tcp on a type other than TCP;
• dns missing for type: DNS, or present for another type;
• tls on anything other than an HTTP check or a TCP check with tcp.tls: true;
• a timeout greater than or equal to interval;
• a quorum.minFailingSites greater than the number of quorum.sites given;
• a tls.expiryCriticalDays greater than tls.expiryWarningDays;
• a Host, X-Scope-OrgID, Authorization, or Cookie header in http.headers.

The platform also rejects, after application (condition Accepted=False, state Unknown):

• an interval shorter than the tier's minimum (IntervalBelowTier);
• an internal target: private, loopback, link-local, multicast, CGNAT (100.64.0.0/10), 198.18.0.0/15, 192.0.0.0/24, 0.0.0.0/8, fc00::/7 address, name without a dot, localhost, or a name ending in .local, .localhost, .internal, .svc, .cluster.local (Invalid); a URL with credentials (user:pass@) is also rejected;
• an unknown site in quorum.sites (Invalid);
• a channel in notificationChannelRefs that does not exist or was rejected (ChannelNotFound);
• type: ICMP (NotSupported);
• a monitor beyond the number allowed by the tier: the most recent ones are rejected (QuotaExceeded).

Monitor

Monitor surveille la disponibilité d'un site, d'un service ou d'un serveur depuis plusieurs sites de sonde.

Champ	Description	Défaut	Validation
apiVersion string	monitoring.stackngo.io/v1alpha1
kind string	Monitor
metadata ObjectMeta	Seul metadata.name est à renseigner (nom de la ressource dans votre tenant).
spec MonitorSpec
status MonitorStatus

MonitorSpec

MonitorSpec décrit un check de disponibilité. Ne précisez pas de tenant : il est déduit de votre session.

Champ	Description	Défaut	Validation
displayName string	Libellé public (status pages, notifications). Défaut : metadata.name.		MaxLength: 63 Optional: {}
type MonitorType	Type de check : HTTP, TCP, ICMP ou DNS.		Enum: [HTTP TCP ICMP DNS]
target string	HTTP : URL http(s). TCP : host:port. ICMP : host. DNS : serveur DNS interrogé.		MaxLength: 2048 MinLength: 1
interval string	Intervalle entre deux checks : 30s, 1m, 2m, 5m ou 10m (selon votre offre).	1m	Enum: [30s 1m 2m 5m 10m]
timeout string	Délai maximal d'un check (secondes, 1s à 30s).	10s	Pattern: ^([1-9]|[12][0-9]|30)s$
failureThreshold integer	Nombre d'échecs consécutifs avant qu'un site soit déclaré en échec.	3	Maximum: 5 Minimum: 1
http HTTPCheck	Options du check HTTP.		Optional: {}
tcp TCPCheck	Options du check TCP.		Optional: {}
dns DNSCheck	Requête du check DNS (obligatoire pour le type DNS).		Optional: {}
tls TLSCheck	Alertes d'expiration du certificat présenté par la cible.		Optional: {}
quorum Quorum	Sites qui sondent la cible et nombre d'échecs requis pour déclarer le monitor Down.		Optional: {}
notificationChannelRefs LocalObjectReference array	Canaux notifiés quand le monitor tombe ou revient (NotificationChannel de votre tenant).		MaxItems: 10 Optional: {}
paused boolean	Suspend le check sans supprimer l'historique.		Optional: {}

MonitorStatus

MonitorStatus : mis à jour à chaque changement d'état ou de manifeste, pas à chaque check. L'historique détaillé est sur la page de statut.

Champ	Description	Défaut	Validation
state MonitorState	État courant du monitor.		Optional: {}
lastTransitionTime Time	Date du dernier changement d'état.		Optional: {}
reason string	Cause de la dernière transition.		Optional: {}
observedGeneration integer	Dernière version du manifeste prise en compte.		Optional: {}
conditions Condition array	Conditions : Accepted (manifeste valide et admis par votre offre).		Optional: {}

MonitorType

Type sous-jacent : string

MonitorType : nature du check : HTTP (requête sur une URL), TCP (connexion à host:port), ICMP (ping d'un hôte) ou DNS (requête à un serveur DNS).

Règles de validation :

• Enum: [HTTP TCP ICMP DNS]

Valeur	Description
HTTP	Requête HTTP(S) sur une adresse, avec contrôle du code de réponse.
TCP	Ouverture d'une connexion TCP sur un hôte et un port.
ICMP	Ping ICMP d'un hôte.
DNS	Résolution DNS d'un nom.

HTTPCheck

HTTPCheck : attentes d'un check HTTP.

Champ	Description	Défaut	Validation
method string	Méthode HTTP : GET (défaut), HEAD ou POST.	GET	Enum: [GET HEAD POST]
expectedStatusCodes integer array	Codes acceptés. Vide : tout 2xx.		MaxItems: 20 items:Maximum: 599 items:Minimum: 100 Optional: {}
bodyMustContain string	Texte littéral attendu dans le corps.		MaxLength: 256 Optional: {}
bodyMustNotContain string	Texte littéral dont la présence fait échouer le check.		MaxLength: 256 Optional: {}
followRedirects boolean	Suit les redirections (défaut : true).	true
headers HTTPHeader array	En-têtes ajoutés à la requête (10 au plus).		MaxItems: 10 Optional: {}
insecureSkipVerify boolean	Accepte un certificat invalide ou auto-signé.		Optional: {}
ipFamily string	Famille d'adresses utilisée : ip4 (défaut), ip6 ou auto.	ip4	Enum: [ip4 ip6 auto]

TCPCheck

TCPCheck : options d'un check TCP.

Champ	Description	Défaut	Validation
tls boolean	Négocie TLS après connexion.		Optional: {}

DNSCheck

DNSCheck : requête envoyée au serveur DNS désigné par target.

Champ	Description	Défaut	Validation
queryName string	Nom de domaine demandé.		MaxLength: 253 Pattern: ^([a-zA-Z0-9]([-a-zA-Z0-9]\{0,61\}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([-a-zA-Z0-9]\{0,61\}[a-zA-Z0-9])?\.?$
queryType string	Type d'enregistrement demandé (défaut : A).	A	Enum: [A AAAA CNAME MX NS TXT SOA]
expectedRcode string	Code de réponse attendu : NOERROR (défaut) ou NXDOMAIN.	NOERROR	Enum: [NOERROR NXDOMAIN]

TLSCheck

TLSCheck : seuils d'alerte d'expiration du certificat.

Champ	Description	Défaut	Validation
expiryWarningDays integer	Alerte d'avertissement quand le certificat expire dans moins de N jours (défaut : 14).	14	Maximum: 90 Minimum: 1
expiryCriticalDays integer	Alerte critique quand le certificat expire dans moins de N jours (défaut : 3).	3	Maximum: 90 Minimum: 1

Quorum

Quorum : un monitor n'est Down que si au moins minFailingSites sites échouent.

Champ	Description	Défaut	Validation
sites string array	Sites qui sondent ce monitor. Vide : tous les sites.		MaxItems: 16 Optional: {}
minFailingSites integer	Nombre de sites en échec requis pour déclarer le monitor Down. Défaut : la majorité des sites qui sondent.		Minimum: 1 Optional: {}

LocalObjectReference

LocalObjectReference désigne par son nom une ressource de votre tenant. Une référence ne peut pas viser un autre tenant.

Champ	Description	Défaut	Validation
name string	Name est le nom de la ressource.		Pattern: ^[a-z0-9]([-a-z0-9]\{0,61\}[a-z0-9])?$

MonitorState

Type sous-jacent : string

MonitorState : état du monitor, après application du quorum de sites.

Valeur	Description
Pending	Accepté, pas encore de mesure.
Up	La cible répond comme attendu.
Down	La cible est en échec sur au moins le quorum de sites.
Unknown	Trop peu de sites ont mesuré la cible pour conclure, ou plus aucune mesure n'arrive.
Paused	Check suspendu (spec.paused).
Maintenance	Fenêtre de maintenance en cours (pas encore disponible).

HTTPHeader

HTTPHeader : en-tête envoyé avec la requête. La valeur est en clair : n'y mettez jamais de secret.

Champ	Description	Défaut	Validation
name string	Nom de l'en-tête.		Pattern: ^[A-Za-z0-9][-A-Za-z0-9]\{0,63\}$
value string	Valeur de l'en-tête (256 caractères au plus).		MaxLength: 256

Status and conditions

status.state gives the aggregated state, status.lastTransitionTime the date of the last change, and status.reason its cause. The status is only rewritten on a state change, never on every check.

state	Meaning
Pending	admitted, waiting for the first measurements
Up	the checks succeed (reason « rétabli : check réussi »)
Down	enough sites are failing (reason like « 1/1 site(s) en échec (quorum 1) »)
Unknown	rejected by the platform (the reason repeats the rejection), or no measurement for (failureThreshold + 1) × interval + 2 min (« aucune mesure récente »)
Paused	paused: true
Maintenance	reserved for maintenance windows, not active yet

Condition	True when	False when
Accepted	the spec is admitted (reason Accepted, message « admis »)	a rejection by the platform (reasons below); the monitor is not probed

reason	Explanation	Action
Accepted	Monitor admitted	—
Invalid	Internal or invalid target, interval not in the list, unknown quorum site; the message names the field	Fix the target or the field
IntervalBelowTier	interval below the tier's minimum (5 min on 3XS, 2 min on 2XS, 1 min on XS/S, 30 s from M up)	Lengthen interval, or change tier
QuotaExceeded	The tier's number of monitors is reached; the oldest ones are kept	Delete monitors, or change tier
ChannelNotFound	Referenced channel does not exist or was itself rejected	Create or fix the channel
NotSupported	ICMP check, not available yet	Use a TCP or HTTP check

In this version, sng kind get Monitor api shows the saved manifest without the monitor's state (# status: not observed yet): the state can be read on the status page.

What happens when you apply

Creation. The monitor is admitted (tier, target, references: condition Accepted), goes to Pending, then is probed from each site (gra today). A site is failing when its last failureThreshold measurements have all failed; the monitor goes Down when at least quorum.minFailingSites sites (by default the majority of the sites probing it) are failing. Two state changes are at least 30 seconds apart.

Update. A new sng apply (or sng monitor create on the same name) replaces the spec; probes and alerts follow. paused: true stops the checks and sets the state to Paused; the history is kept.

What happens when you delete

sng monitor delete api or sng kind delete Monitor api: the monitor is no longer probed, its alerts stop, and a StatusPage that still lists it is rejected (MonitorNotFound). Measurements already collected are kept according to the platform's retention period.

Common errors

Symptom	Cause	Fix
sng apply rejects: type HTTP : target doit être une URL http(s)://	URL without a scheme	https://…
sng apply rejects: type TCP : target attendu host:port	Missing port	host:5432
sng apply rejects: dns : requis pour le type DNS, interdit sinon	dns block missing for a DNS check, or present elsewhere	Add or remove dns
sng apply rejects: headers : Host, X-Scope-OrgID, Authorization et Cookie sont réservés	Forbidden header	Remove it; monitor a public route
sng apply rejects: tls : réservé à HTTP ou TCP avec tcp.tls	tls on a DNS check, or TCP without tcp.tls: true	Remove tls or add tcp: {tls: true}
State Unknown, reason « interval 1m inférieur au minimum 5m0s du tier 3XS »	3XS tenant and a 1m interval	interval: 5m
State Unknown, reason « target … : adresse privée ou réservée, interdit »	Internal target	Public URL of the App (https://<service>-<app>.<tenant>.dev.stackngo.app/)
Down even though the target responds in a browser	Code not in expectedStatusCodes, expected text missing, target without IPv4 (ipFamily: ip4 by default)	Check with curl -i; adjust expectedStatusCodes or ipFamily: auto

See also

• Guides: Uptime monitors, Notification channels, Status page, Tiers and quotas
• CLI: sng monitor, sng kind
• Other kinds: NotificationChannel, StatusPage, MaintenanceWindow