Provider Terraform

Vue d’ensemble

Le provider Terraform officiel okstatus permet de gérer monitors, groupes de monitors, incidents, pages de statut, canaux d’alerte et fenêtres de maintenance as code — utile pour provisionner la surveillance en même temps que l’infrastructure qu’elle observe, ou pour garder une flotte de monitors versionnée plutôt que gérée à la souris dans le dashboard.

Le provider est publié sur le Terraform Registry où vit sa référence complète (ressources/data sources). Ce guide couvre uniquement la prise en main — consultez la doc du registry pour chaque champ.

Plan Max requis

Le provider a besoin d’une clé API Complète (oks_live_...), disponible sur le plan Max (Dashboard → Paramètres → Clés API). Une clé Lecture seule suffit pour terraform plan et les data sources ; voir les niveaux d’accès.

Installation

terraform {
  required_providers {
    okstatus = {
      source  = "clearcloud-fr/okstatus"
      version = "~> 1.6"
    }
  }
}

provider "okstatus" {
  # api_key peut aussi venir de la variable d'environnement OKSTATUS_API_KEY.
  # api_key = "oks_live_..."
}

Préférez la variable d’environnement plutôt que d’écrire la clé en dur dans vos fichiers .tf :

export OKSTATUS_API_KEY="oks_live_..."

Un premier monitor

resource "okstatus_monitor" "api" {
  name                  = "API Production"
  url                   = "https://api.example.com/health"
  type                  = "http"
  interval              = 60
  regions               = ["fr-dc3", "de-fra", "es-mad"]
  accepted_status_codes = ["200-299"]

  tags             = ["prod", "paiement"]
  keyword          = "\"status\":\"ok\""
  follow_redirects = false
}

Les valeurs de regions réellement autorisées dépendent de votre plan — une région non incluse dans votre plan est rejetée à l’apply avec une erreur 400, pas au plan. Voir Régions et intervalles pour la liste par plan.

Une vérification HTTP peut envoyer sa propre requête — méthode, corps et en-têtes :

resource "okstatus_monitor" "webhook" {
  name               = "Webhook des commandes"
  url                = "https://api.example.com/orders/ping"
  http_method        = "POST"
  http_body          = jsonencode({ ping = true })
  http_body_encoding = "json"
  http_headers       = { Authorization = "Bearer ${var.probe_token}" }
}

http_headers est sensible et en écriture seule : OKStatus ne renvoie jamais les en-têtes d’une requête, Terraform les envoie donc quand l’attribut change et ne peut pas voir un en-tête modifié dans le dashboard. ignore_tls = true accepte un certificat auto-signé.

Les autres types de vérification ont leurs propres réglages :

resource "okstatus_monitor" "spf" {
  name               = "Enregistrement SPF"
  url                = "example.com"
  type               = "dns"
  dns_record_type    = "TXT"
  dns_expected_value = "v=spf1"
}

resource "okstatus_monitor" "database" {
  name = "Port de la base"
  url  = "db.example.com"
  type = "tcp"
  port = 5432
}

Bases de données, heartbeats et autres types

type accepte tous les types de vérification d’OKStatus sauf les modèles IA (qui ont okstatus_llm_monitor) : grpc, push, group, postgres, mysql, mongodb, smtp, imap et redis.

resource "okstatus_monitor" "orders_db" {
  name                = "Base des commandes"
  url                 = "postgres://db.example.com:5432/orders"
  type                = "postgres"
  db_query            = "SELECT 1"
  basic_auth_user     = "okstatus_ro"
  basic_auth_password = var.orders_db_password
}

resource "okstatus_monitor" "backup" {
  name         = "Sauvegarde nocturne"
  url          = "nightly-backup"
  type         = "push"
  interval     = 86400
  grace_period = 3600
}

Un monitor push expose son push_token (sensible) — le jeton de l’URL de ping que votre tâche appelle. Changer type ou grace_period remplace le monitor.

S’authentifier auprès du point d’accès surveillé

resource "okstatus_monitor" "partner_api" {
  name = "API partenaire"
  url  = "https://partner.example.com/health"

  auth = {
    type          = "oauth2"
    token_url     = "https://login.example.com/oauth/token"
    client_id     = "okstatus-probe"
    client_secret = var.partner_client_secret
  }
}

auth.type vaut bearer, apikey, cookie, oauth2 ou mtls — voir Authentification pour le rôle de chacun. Le Basic auth, et le compte d’un monitor base de données, SMTP, IMAP ou Redis, vont dans basic_auth_user / basic_auth_password.

Les identifiants sont en écriture seule : OKStatus ne les renvoie jamais, Terraform les envoie donc quand ils changent et ne peut pas voir une modification faite dans le dashboard. Les retirer de la configuration les retire du monitor. N’écrivez jamais user:password@ dans url — le provider le refuse.

Pause et sourdine

resource "okstatus_monitor" "staging" {
  name   = "Préproduction"
  url    = "https://staging.example.com"
  paused = true # aucune vérification
  muted  = true # des vérifications, mais aucune alerte
}

Ce que vous n’écrivez pas reste en l’état

tags, paused, muted, keyword, follow_redirects, port, les options de requête HTTP et les réglages DNS n’ont pas de valeur par défaut. Un attribut que vous n’écrivez pas garde la valeur que le monitor a déjà, y compris celle posée dans le dashboard — brancher le provider sur des monitors existants, ou le mettre à jour, ne les réinitialise donc jamais. Pour retirer une valeur, dites-le : tags = [], keyword = "", paused = false.

Attacher des canaux d’alerte

Le config d’un canal d’alerte utilise les noms de champs du backend (camelCase), pas la convention snake_case habituelle de Terraform — voir la référence okstatus_alert_channel pour la forme exacte de chaque type de canal.

resource "okstatus_alert_channel" "team_discord" {
  type = "discord"
  config = {
    webhookUrl = "https://discord.com/api/webhooks/..."
  }
}

resource "okstatus_monitor" "checkout" {
  name              = "Commande"
  url               = "https://shop.example.com/checkout/health"
  alert_channel_ids = [okstatus_alert_channel.team_discord.id]
}

alert_channel_ids est la liste complète des canaux du monitor ; [] les détache tous. Sans cet attribut, Terraform ne gère pas du tout les canaux du monitor. Pour rattacher un canal créé dans le dashboard, retrouvez-le avec data.okstatus_alert_channels.

Regrouper des monitors

resource "okstatus_monitor_group" "payments" {
  name        = "Paiement"
  description = "Tout le parcours de commande"

  monitor_ids = [
    okstatus_monitor.api.id,
    okstatus_monitor.checkout.id,
  ]
}

Un monitor appartient à un seul groupe au plus, et monitor_ids est la composition complète du groupe. Détruire le groupe conserve ses monitors.

Un groupe peut porter ses propres alert_channel_ids : un monitor qui rejoint le groupe les reçoit. Si vous renseignez aussi alert_channel_ids sur ce monitor, répétez-y les canaux du groupe — sinon le prochain apply les détache du monitor.

Exécuter un monitor sur un agent privé

Les agents privés s’enrôlent depuis le dashboard. Terraform les lit et vous donne la valeur region qui exécute un monitor sur l’un d’eux :

data "okstatus_private_agents" "all" {}

locals {
  paris_agent = one([for a in data.okstatus_private_agents.all.agents : a if a.name == "dc-paris"])
}

resource "okstatus_monitor" "intranet" {
  name    = "Intranet"
  url     = "https://intranet.example.com"
  regions = [local.paris_agent.region]
}

regions = ["private"] laisse n’importe lequel de vos agents exécuter la vérification.

Ce qui est couvert

Ressource / data source	Gère
okstatus_monitor	Tous les types de monitor sauf les modèles IA, avec identifiants et canaux d’alerte
okstatus_llm_monitor	Monitors de modèles IA (LLM) (Max et au-delà)
okstatus_monitor_group	Groupes de monitors (les dossiers de la page Monitors)
okstatus_alert_channel	Email, Discord, webhook, Slack, Telegram, et plus
okstatus_incident	Incidents et leurs mises à jour horodatées
okstatus_maintenance	Fenêtres de maintenance planifiées
okstatus_status_page	Pages de statut publiques
data.okstatus_monitors	Rechercher des monitors existants (ex. pour les référencer par nom)
data.okstatus_monitor_groups	Rechercher des groupes existants et leurs monitors
data.okstatus_alert_channels	Rechercher des canaux d’alerte existants
data.okstatus_private_agents	Vos agents privés et la valeur region de chacun
data.okstatus_org	Lire le plan et les paramètres de l’organisation courante

slo_target sur okstatus_monitor et okstatus_monitor_group fixe un SLO (Max et Enterprise). Terraform gère l’objectif ; le budget se lit par l’API (GET /api/v1/slos) ou le connecteur MCP (list_slos).

Non gérés par Terraform : l’enrôlement d’un agent privé et les rapports SLA.

Schéma complet, tous les champs, valeurs par défaut : registry.terraform.io/providers/clearcloud-fr/okstatus.

Importer des ressources existantes

Les ressources créées depuis le dashboard peuvent être reprises sous gestion Terraform avec terraform import, en utilisant l’ID de la ressource (visible dans l’URL du dashboard ou via l’API REST) :

terraform import okstatus_monitor.api <monitor-id>
terraform import okstatus_monitor_group.payments <group-id>

Un monitor importé garde ses tags, son mot-clé et son état de pause tant que vous n’écrivez pas ces attributs.