Terraform provider

The SutramX Terraform provider lets you manage monitors, status pages and alert channels next to the rest of your infrastructure, and read maintenance windows and escalation policies. It talks to the SutramX API with a workspace API key, and every resource lives in the workspace that key belongs to.

The provider is published on the Terraform Registry as sutramx/sutramx. Add it to required_providers as shown below and terraform init downloads it.

At a glance#

Configure the provider#

Pin the provider to the 0.1 series, then run terraform init:

terraform {
  required_providers {
    sutramx = {
      source  = "sutramx/sutramx"
      version = "~> 0.1"
    }
  }
}

# The API key can also come from SUTRAMX_API_KEY.
provider "sutramx" {
  api_key = var.sutramx_api_key
}

variable "sutramx_api_key" {
  type      = string
  sensitive = true
}

The simplest setup is an empty provider "sutramx" {} block with SUTRAMX_API_KEY set in the environment.

Which API key you need#

Create a key in Account settings → API keys → Create API key. Whether you can create API keys, and how many, depends on your plan: see Plans & limits.

Every key has one of three access levels: Read-only (the dashboard default), Standard or Automation. The level is fixed when the key is created, so pick the one your configuration needs:

Example#

resource "sutramx_monitor" "website" {
  key              = "web/home"
  name             = "Website"
  url              = "https://www.example.com"
  interval_seconds = 60
  regions          = ["fra1", "usa-az-probe"]
  tags             = ["prod", "web"]
  config_json = jsonencode({
    timeout               = 10000
    expected_status_codes = [200]
    keyword               = "Example Domain"
  })
}

resource "sutramx_monitor" "postgres" {
  key  = "infra/postgres"
  name = "Postgres"
  type = "port"
  config_json = jsonencode({
    host = "db.example.com"
    port = 5432
  })
}

resource "sutramx_status_page" "public" {
  title               = "Example status"
  slug                = "example-status"
  description         = "Live status of Example's website and API."
  is_public           = true
  show_response_times = true
  accent_color        = "#0d9488"

  monitors = [
    { monitor_id = sutramx_monitor.website.id },
    { monitor_id = sutramx_monitor.postgres.id, section = "Infrastructure" },
  ]
}

resource "sutramx_alert_channel" "ops_slack" {
  type = "slack"
  name = "Ops alerts"
  config = {
    webhook_url = var.slack_webhook_url
  }
  routing_scope = "monitors"
  monitor_ids   = [sutramx_monitor.website.id]
}

variable "slack_webhook_url" {
  type      = string
  sensitive = true
}

sutramx_monitor#

An uptime monitor. Checks run from SutramX probe regions; see Regions & confirmation for how regions confirm an outage.

What goes in config_json depends on the type: cron monitors need cron_expression; ping monitors need host; port and UDP monitors need host and port; DNS monitors need hostname (plus optional settings such as record_type and expected_values); multi-step checks need steps. Multi-step secrets are write-only: Terraform keeps your value and doesn't detect changes made elsewhere. HTTP and API monitors accept settings such as timeout, expected_status_codes, keyword, method and headers. See HTTP & keyword, API & multi-step checks, Ping, TCP & UDP, DNS, Heartbeat & cron and MCP servers for every option.

How it behaves:

• Monitors are written with an idempotent create-or-update by key, so a retried apply never creates a duplicate.
• config_json and tags that you leave out are not managed: whatever is set in the dashboard stays. Once you set config_json, it is managed as a whole, so keys you remove are removed from the monitor.
• Unlike config_json and tags, leaving out regions means "use the plan's default locations".
• Stored credentials in config_json (secret headers, tokens, passwords) are read back as [REDACTED]; Terraform keeps your configured values for them.
• Per-monitor alert recipients (notification_emails in config_json) are ignored unless your configuration sets them. Setting them needs an Automation key; with any other key the apply fails with 403 ALERT_ROUTING_NOT_ALLOWED.
• Changing type destroys the monitor (with its check history) and creates a new one.
• Plan limits are enforced by the API exactly as in the dashboard. Errors such as ENTITLEMENT_LIMIT_REACHED appear as Terraform diagnostics.
• terraform destroy deletes the monitor and its history.

Use the heartbeat URL of a cron monitor in your job:

resource "sutramx_monitor" "nightly_job" {
  key  = "jobs/nightly"
  name = "Nightly job"
  type = "cron"
  config_json = jsonencode({
    cron_expression = "0 2 * * *"
  })
}

output "nightly_job_heartbeat_url" {
  value     = sutramx_monitor.nightly_job.heartbeat_url
  sensitive = true
}

sutramx_status_page#

A status page showing the state of selected monitors. It counts against your plan's status page limit.

In each monitors entry, monitor_id is required (usually sutramx_monitor.<name>.id) and section is an optional heading the monitor is grouped under.

The only attribute is id. Custom domains, private access and subscribers are managed in the dashboard: see Branding & custom domains. terraform destroy deletes the page.

sutramx_alert_channel#

An alert channel (integration connection) such as Slack, Discord, Microsoft Teams, a webhook, PagerDuty or Opsgenie. Creating, changing and deleting it requires an API key with the Automation access level. Which channel types you can use depends on your plan.

resource "sutramx_alert_channel" "incident_webhook" {
  type   = "webhook"
  name   = "Incident pipeline"
  config = { webhook_url = "https://hooks.example.com/sutramx" }
}

output "webhook_signing_secret" {
  value     = sutramx_alert_channel.incident_webhook.signing_secret
  sensitive = true
}

The fields each channel type needs are described in Slack, Teams & chat apps, Webhooks and PagerDuty & Opsgenie.

Data sources#

sutramx_regions#

SutramX probe locations. Use code in sutramx_monitor.regions. Doesn't need an API key. Which codes a monitor may use depends on your plan and billing market.

data "sutramx_regions" "online" {
  online_only = true
}

output "region_codes" {
  value = data.sutramx_regions.online.codes
}

sutramx_plans#

The current SutramX plans with prices and main limits, as listed on the pricing page. Doesn't need an API key.

data "sutramx_plans" "all" {}

output "plan_prices_usd" {
  value = { for plan in data.sutramx_plans.all.plans : plan.id => plan.price_monthly_usd }
}

Each entry in plans has id, name, description, markets (global for USD and/or india for INR), price_monthly_usd, price_annual_usd, price_monthly_inr, price_annual_inr, monitors, min_interval_seconds, probe_locations (null means every active location), status_pages (null means unlimited), api_keys (null means unlimited), popular and sort_order.

sutramx_maintenance_windows#

The workspace's maintenance windows, newest start first. Needs an API key; any access level works, including read-only. Terraform can only read windows: creating, changing and deleting them is done by the workspace owner in the dashboard, see Maintenance windows.

data "sutramx_maintenance_windows" "ongoing" {
  effective_status = "ongoing"
}

output "in_maintenance" {
  value = length(data.sutramx_maintenance_windows.ongoing.windows) > 0
}

Each entry in windows has:

sutramx_escalation_policies#

The workspace's escalation policies, newest first. Needs an API key; any access level works, including read-only. Terraform can only read policies: the workspace owner creates and changes them in the dashboard, see Escalation & on-call.

data "sutramx_escalation_policies" "primary" {
  name = "Primary on-call"
}

output "primary_policy_id" {
  value = one(data.sutramx_escalation_policies.primary.policies[*].id)
}

Each entry in policies has id, name, enabled, max_depth (how many steps an incident escalates through at most) and steps, in escalation order. Each step has:

Import existing resources#

Monitors can be imported by id (UUID) or by key:

# A monitor made in the dashboard: it gets a key on the next apply
terraform import sutramx_monitor.website 6f1c8f7e-6f2a-4a71-9d0b-0b8c1d2e3f40

# A monitor created by sutramx.yml or Terraform
terraform import sutramx_monitor.website web/home

Importing also fills in config_json, so a configuration that matches the monitor plans no changes. A dashboard monitor without a key gets one on the next apply: the key you set in HCL, or a generated tf-... key.

Status pages and alert channels are imported by id:

terraform import sutramx_status_page.public 0b6f1c2a-9e4d-4f7a-8c3b-2d1e0f9a8b7c
terraform import sutramx_alert_channel.ops_slack 7d1e0f9a-8b7c-4c3b-9e4d-0b6f1c2a2d1e

Alert channel secrets aren't read back: set config in HCL and the next apply writes it.

Using Terraform with sutramx.yml#

The provider and the CLI use the same monitor keys. Pick one tool per monitor. If you use both in one workspace, don't turn on pruning in sutramx.yml: pruning deletes every keyed monitor that isn't in the file, including monitors created by Terraform.

Troubleshooting#