Monitor

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.

La supervision est en cours de déploiement : tant qu'elle n'est pas activée sur votre tenant, sng apply refuse ce manifeste.


`apiVersion`	`monitoring.stackngo.io/v1alpha1`
`kind`	`Monitor`
Appliqué par	`sng apply`
Commandes liées	`sng monitor create` (génère et applique ce manifeste), `sng monitor list`, `sng monitor delete`, `sng template gen Monitor`

À quoi ça sert

Un Monitor vérifie à intervalle fixe qu'une cible publique répond : une URL HTTP(S), un port TCP ou un serveur DNS. La plateforme le sonde depuis ses sites, calcule son état (Up, Down, Unknown…), prévient les NotificationChannel qu'il référence quand il tombe ou revient, et l'affiche sur vos StatusPage. Le nombre de moniteurs et l'intervalle minimal dépendent du tier du tenant.

Exemple minimal

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

Équivalent : sng monitor create api --http https://api.example.com/health --interval 5m (la commande ajoute aussi tls: {} pour une URL https://).

Exemple complet commenté

api.yml
apiVersion: monitoring.stackngo.io/v1alpha1
kind: Monitor
metadata:
  name: api                        # label DNS, 63 caractères au plus
spec:
  displayName: API publique        # libellé public (pages de statut, notifications), 63 car. max ; défaut : le nom
  type: HTTP                       # HTTP, TCP, DNS (ICMP : pas encore disponible)
  target: https://api.example.com/health   # HTTP : URL ; TCP : host:port ; DNS : serveur interrogé
  interval: 1m                     # 30s, 1m (défaut), 2m, 5m, 10m — minimum selon le tier
  timeout: 10s                     # 1s à 30s, inférieur à interval (défaut 10s)
  failureThreshold: 3              # échecs consécutifs avant la panne, 1 à 5 (défaut 3)
  http:
    method: GET                    # GET (défaut), HEAD, POST
    expectedStatusCodes: [200, 204]  # vide : tout 2xx
    bodyMustContain: '"status":"ok"' # texte littéral attendu dans le corps (256 car. max)
    bodyMustNotContain: maintenance  # texte littéral qui fait échouer le check
    followRedirects: true          # défaut
    headers:                       # 10 au plus, valeurs en clair : jamais de secret
      - { name: Accept, value: application/json }
    insecureSkipVerify: false      # true : accepte un certificat invalide
    ipFamily: ip4                  # ip4 (défaut), ip6, auto
  tls:                             # alertes d'expiration du certificat de la cible
    expiryWarningDays: 14          # 1 à 90 (défaut 14)
    expiryCriticalDays: 3          # 1 à 90, ≤ expiryWarningDays (défaut 3)
  notificationChannelRefs:         # canaux du tenant à prévenir, 10 au plus
    - name: ops
  paused: false                    # true : suspend les checks sans perdre l'historique

Autres types :

# TCP, avec négociation TLS et alertes de certificat
spec:
  type: TCP
  target: mail.example.com:465
  tcp: { tls: true }
  tls: {}
---
# DNS : demande à ns1.example.com l'enregistrement MX de example.com
spec:
  type: DNS
  target: ns1.example.com
  dns:
    queryName: example.com
    queryType: MX                  # A (défaut), AAAA, CNAME, MX, NS, TXT, SOA
    expectedRcode: NOERROR         # NOERROR (défaut) ou NXDOMAIN

Champs

Règles de validation croisées

Le schéma refuse, dès sng apply :

type: HTTP avec une target qui ne commence pas par http:// ou https:// ; à l'inverse, une URL pour tout autre type ;
type: TCP avec une target autre que host:port (ou [ipv6]:port) ;
http sur un autre type que HTTP, tcp sur un autre type que TCP ;
dns absent pour type: DNS, ou présent pour un autre type ;
tls sur autre chose qu'un check HTTP ou un check TCP avec tcp.tls: true ;
timeout supérieur ou égal à interval ;
quorum.minFailingSites supérieur au nombre de quorum.sites donnés ;
tls.expiryCriticalDays supérieur à tls.expiryWarningDays ;
un en-tête Host, X-Scope-OrgID, Authorization ou Cookie dans http.headers.

La plateforme refuse en plus, après application (condition Accepted=False, état Unknown) :

un interval plus court que le minimum du tier (IntervalBelowTier) ;
une cible interne : adresse privée, de bouclage, lien-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, nom sans point, localhost ou nom en .local, .localhost, .internal, .svc, .cluster.local (Invalid) ; une URL avec identifiants (user:pass@) est aussi refusée ;
un site de quorum.sites inconnu (Invalid) ;
type: ICMP (NotSupported) ;
un moniteur au-delà du nombre autorisé par le tier : les plus récents sont refusés (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	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

Statut et conditions

status.state donne l'état agrégé, status.lastTransitionTime la date du dernier changement et status.reason sa cause. Le status n'est réécrit que sur un changement d'état, jamais à chaque check.

`state`	Signification
`Pending`	admis, en attente des premières mesures
`Up`	les checks réussissent (raison « rétabli : check réussi »)
`Down`	assez de sites sont en échec (raison du type « 1/1 site(s) en échec (quorum 1) »)
`Unknown`	refusé par la plateforme (la raison reprend le refus), ou aucune mesure depuis `(failureThreshold + 1) × interval + 2 min` (« aucune mesure récente »)
`Paused`	`paused: true`
`Maintenance`	réservé aux fenêtres de maintenance, pas encore actives

Condition	`True` quand	`False` quand
`Accepted`	la spec est admise (raison `Accepted`, message « admis »)	un refus de la plateforme (raisons ci-dessous) ; le moniteur n'est pas sondé

`reason`	Explication	Action
`Accepted`	Moniteur admis	—
`Invalid`	Cible interne ou invalide, intervalle hors liste, site de quorum inconnu ; le message cite le champ	Corriger la cible ou le champ
`IntervalBelowTier`	`interval` sous le minimum du tier (5 min en `3XS`, 2 min en `2XS`, 1 min en `XS`/`S`, 30 s à partir de `M`)	Allonger `interval`, ou changer de tier
`QuotaExceeded`	Nombre de moniteurs du tier atteint ; les plus anciens sont gardés	Supprimer des moniteurs, ou changer de tier
`WaitingForChannel`	Canal référencé inexistant ou lui-même refusé : le moniteur reste admis et sondé, `Ready=False` pour la seule alerte	Créer ou corriger le canal ; l'alerte part dès qu'il existe
`NotSupported`	Check `ICMP`, pas encore disponible	Utiliser un check `TCP` ou `HTTP`

Dans cette version, sng kind get Monitor api affiche le manifeste enregistré sans l'état du moniteur (# status: not observed yet) : l'état se lit sur la page de statut.

Ce qui se passe à l'application

Création. Le moniteur est admis (tier, cible, références : condition Accepted), passe Pending, puis est sondé depuis chaque site (gra aujourd'hui). Un site est en échec quand ses failureThreshold dernières mesures ont toutes échoué ; le moniteur passe Down quand au moins quorum.minFailingSites sites (par défaut la majorité des sites qui le sondent) sont en échec. Deux changements d'état sont séparés d'au moins 30 secondes.

Mise à jour. Un nouveau sng apply (ou sng monitor create sur le même nom) remplace la spec ; les sondes et les alertes suivent. paused: true arrête les checks et passe l'état à Paused ; l'historique est conservé.

Ce qui se passe quand vous supprimez

sng monitor delete api ou sng kind delete Monitor api : le moniteur cesse d'être sondé, ses alertes cessent, et une StatusPage qui le liste encore l'affiche en attente (WaitingForMonitor). Les mesures déjà collectées restent conservées selon la durée de rétention de la plateforme.

Erreurs fréquentes

Symptôme	Cause	Correction
`sng apply` refuse : `type HTTP : target doit être une URL http(s)://`	URL sans schéma	`https://…`
`sng apply` refuse : `type TCP : target attendu host:port`	Port manquant	`host:5432`
`sng apply` refuse : `dns : requis pour le type DNS, interdit sinon`	Bloc `dns` absent pour un check DNS, ou présent ailleurs	Ajouter ou retirer `dns`
`sng apply` refuse : `headers : Host, X-Scope-OrgID, Authorization et Cookie sont réservés`	En-tête interdit	Le retirer ; surveiller une route publique
`sng apply` refuse : `tls : réservé à HTTP ou TCP avec tcp.tls`	`tls` sur un check DNS, ou TCP sans `tcp.tls: true`	Retirer `tls` ou ajouter `tcp: {tls: true}`
État `Unknown`, raison « interval 1m inférieur au minimum 5m0s du tier 3XS »	Tenant `3XS` et intervalle de `1m`	`interval: 5m`
État `Unknown`, raison « target … : adresse privée ou réservée, interdit »	Cible interne	URL publique de l'App (`https://<service>-<app>.<tenant>.dev.stackngo.app/`)
`Down` alors que la cible répond dans un navigateur	Code hors `expectedStatusCodes`, texte attendu absent, cible sans IPv4 (`ipFamily: ip4` par défaut)	Vérifier avec `curl -i` ; ajuster `expectedStatusCodes` ou `ipFamily: auto`

Voir aussi

Guides : Moniteurs d'uptime, Canaux de notification, Page de statut, Tiers et quotas
CLI : sng monitor, sng kind
Autres kinds : NotificationChannel, StatusPage, MaintenanceWindow

À quoi ça sert​

Exemple minimal​

Exemple complet commenté​

Champs​

Règles de validation croisées​

Monitor​

MonitorSpec​

MonitorStatus​

MonitorType​

HTTPCheck​

TCPCheck​

DNSCheck​

TLSCheck​

Quorum​

LocalObjectReference​

MonitorState​

HTTPHeader​

Statut et conditions​

Ce qui se passe à l'application​

Ce qui se passe quand vous supprimez​

Erreurs fréquentes​

Voir aussi​

À quoi ça sert

Exemple minimal

Exemple complet commenté

Champs

Règles de validation croisées

Monitor

MonitorSpec

MonitorStatus

MonitorType

HTTPCheck

TCPCheck

DNSCheck

TLSCheck

Quorum

LocalObjectReference

MonitorState

HTTPHeader

Statut et conditions

Ce qui se passe à l'application

Ce qui se passe quand vous supprimez

Erreurs fréquentes

Voir aussi