Skip to content

Terraform and OpenTofu

The You Up? provider keeps your Monitors and Notification rules in code, beside the rest of your infrastructure. It is uupdev/uup on the Terraform Registry and the OpenTofu Registry, which hold its full reference: every resource, data source and field.

Terraform and OpenTofu use the same provider and the same configuration. This page uses terraform in its commands. With OpenTofu, run tofu instead.

It manages:

  • Monitors, uup_monitor: Website (http), Port (tcp), Server (ping) and Heartbeat (heartbeat), with their Checks, whether they are paused, and the Notification rules they have.
  • Notification rules, uup_notification_rule.

It reads your Projects, Channels, Notification rules and locations with data sources. It calls the You Up? API, so it follows the dashboard’s rules and your Plan’s limits.

Name the provider in your configuration:

main.tf
terraform {
required_providers {
uup = {
source = "uupdev/uup"
}
}
}
provider "uup" {}

Then run terraform init, or tofu init with OpenTofu, which downloads it from that tool’s Registry.

The provider needs an API token of the Full kind, since it creates and changes things:

  1. In the sidebar, open API tokens.
  2. Press New token, and name it after what will use it, such as Terraform.
  3. Choose what it reaches: the Project your configuration manages, or every Project.
  4. Choose Full, and when it expires.
  5. Press Create token, copy the token, and set it in the UUP_API_TOKEN environment variable where Terraform or OpenTofu runs:
Terminal window
export UUP_API_TOKEN="uup_api_…"

The provider reads it from there. Keep it out of the files you commit.

A Monitor and a rule belong to a Project, and a rule sends to Channels. Look them up by name with data sources:

data "uup_project" "main" {
name = "My project"
}
data "uup_channel" "oncall" {
project_id = data.uup_project.main.id
name = "On-call Slack"
}
# The Project's Default rule.
data "uup_notification_rule" "default" {
project_id = data.uup_project.main.id
default = true
}

One example for each Monitor type. A Monitor that names no locations is checked from as many as the Project’s Default locations in its settings, and we choose which. location_count sets how many instead, and the uup_locations data source lists the ones you can name in locations.

resource "uup_monitor" "api" {
project_id = data.uup_project.main.id
type = "http"
name = "API health"
url = "https://api.example.com/health"
interval_sec = 60
expected_status = ["200"]
}
resource "uup_monitor" "database" {
project_id = data.uup_project.main.id
type = "tcp"
name = "Database"
host = "db.example.com"
port = 5432
interval_sec = 60
location_count = 3
}
resource "uup_monitor" "gateway" {
project_id = data.uup_project.main.id
type = "ping"
name = "Office gateway"
host = "gateway.example.com"
interval_sec = 120
}
resource "uup_monitor" "backup" {
project_id = data.uup_project.main.id
type = "heartbeat"
name = "Nightly backup"
cron = "0 3 * * *"
grace_sec = 900
}
output "backup_heartbeat_url" {
value = uup_monitor.backup.heartbeat_url
sensitive = true
}

heartbeat_url is the URL your job calls. Read it with terraform output -raw backup_heartbeat_url, and see Heartbeat examples for the call itself. Give the Monitor a cron Schedule or an expected_interval_sec, never both, as Heartbeat Monitors explains.

This rule sends outages and recoveries to one Channel, and sends an open Incident again as often as repeat says. One Monitor has it:

resource "uup_notification_rule" "outages" {
project_id = data.uup_project.main.id
name = "Outages to on-call"
event_types = ["uptime.failed", "uptime.recovered"]
channel_ids = [data.uup_channel.oncall.id]
repeat = "30m"
}
resource "uup_monitor" "checkout" {
project_id = data.uup_project.main.id
type = "http"
name = "Checkout"
url = "https://shop.example.com/checkout"
interval_sec = 60
rule_ids = [uup_notification_rule.outages.id]
}

A new Monitor that leaves rule_ids out gets the Project’s Default rule, as in the dashboard. See Notification rules for the events and the repeat choices.

Bring existing Monitors into your configuration

Section titled “Bring existing Monitors into your configuration”

A Monitor or a rule you made in the dashboard can be imported. Write its resource block first, then import it by its Project’s id and its own, joined by /:

Terminal window
terraform import uup_monitor.api prj_abc123/mon_def456
terraform import uup_notification_rule.outages prj_abc123/rul_def456

A Monitor’s page in the dashboard shows both in its address, after /projects/ and /monitors/. A rule’s id is in what the API’s list of rules answers. Run terraform plan afterwards, and change your block until it shows no changes.

The Default rule can be imported and changed, but never deleted.

  • Channels stay in the dashboard. Most Channels need a code or a link that a person confirms, so the provider cannot add one. Add it in the dashboard, then look it up with uup_channel.
  • Secrets are kept in your state. We never show a Monitor’s header values, request body or credentials again once they are saved. The provider keeps them in the state, so keep your state where only your team can read it. After an import they read as empty, until the next terraform apply sets them.
  • Some Monitors are tested before they are saved. A ping Monitor, and a Website Monitor with assertions, need one test from one location first, as the dashboard runs one. The provider runs it and waits for the answer, which can take a few seconds. See Creating Monitors by API.
  • A changed target replaces the Monitor. Changing type, url, host or port deletes the Monitor and creates a new one, with a history of its own. A new Heartbeat Monitor gets a new Heartbeat URL, so update your job.

Every field of every resource and data source is on the Terraform Registry and the OpenTofu Registry.