> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform

> Manage scaling.cloud on-call schedules, escalation policies, routing policies, and working hours as code with the scaling.cloud Cloud Terraform provider.

The scaling.cloud Cloud Terraform provider lets you manage your incident-response configuration as code. Define on-call schedules, escalation policies, routing policies, and working hours in HCL, review them in pull requests, and apply them through your existing Terraform workflow.

The provider talks to the same [public API](/api/overview) as everything else, authenticating with an organization API key.

<Card title="Full provider reference" icon="book" href="https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest/docs">
  Every argument and attribute for the provider and each resource — always matched to the released provider version — lives in the Terraform Registry documentation. The page below is a guided tour; the Registry is the complete, authoritative reference.
</Card>

## Install

Add the provider to your `required_providers` block and run `terraform init`:

```hcl theme={null}
terraform {
  required_providers {
    scaling = {
      source  = "scaling-cloud/scaling-cloud"
      version = "~> 0.2"
    }
  }
}

provider "scaling" {
  # api_key can also be supplied via the SCALING_CLOUD_API_KEY environment variable
}
```

## Authentication

The provider authenticates with a scaling.cloud **API key** (a `scl_live_…` token). Create one under **Settings → API keys**. You can supply it two ways:

* The `SCALING_CLOUD_API_KEY` environment variable (recommended — keeps the secret out of your configuration):

  ```bash theme={null}
  export SCALING_CLOUD_API_KEY="scl_live_your_api_key_here"
  terraform plan
  ```

* The `api_key` provider attribute (mark it sensitive and source it from a variable, never a literal):

  ```hcl theme={null}
  provider "scaling" {
    api_key = var.scaling_cloud_api_key
  }
  ```

The API base URL defaults to `https://api.scaling.cloud`. Override it with the `base_url` attribute or the `SCALING_CLOUD_BASE_URL` environment variable if you target a non-default environment.

<Warning>
  An API key is scoped to your organization and can create, modify, and delete on-call schedules, escalation policies, and routing policies. Store it in a secrets manager or CI secret — never commit it to version control.
</Warning>

## Resources

The provider manages four resources, which together cover your full incident-routing configuration. The examples below are illustrative — for the complete argument and attribute reference of each (including computed fields, defaults, and validation rules), follow its **Registry reference** link.

<Note>
  The provider does not yet support `terraform import`. Manage these resources in Terraform from creation; schedules, escalation policies, routing policies, and working hours created in the dashboard cannot currently be adopted into Terraform state.
</Note>

### `scaling_oncall_schedule`

Manages an [on-call schedule](/concepts/oncall-schedules) with one or more rotation layers. → [Registry reference](https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest/docs/resources/oncall_schedule)

```hcl theme={null}
resource "scaling_oncall_schedule" "primary" {
  name     = "Primary On-Call"
  timezone = "America/New_York"

  layer {
    name                 = "Engineers"
    rotation_type        = "weekly"
    rotation_length_days = 7
    handoff_time         = "09:00"
    effective_from       = "2025-01-01T00:00:00Z"
    participant_ids      = ["user_abc", "user_def"]
  }
}
```

### `scaling_working_hours`

Manages a [working hours set](/concepts/working-hours) — a named timezone plus weekly windows, referenced by escalation policy step conditions for follow-the-sun routing. The `timezone` lives on the set and is never inferred from a targeted schedule. → [Registry reference](https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest/docs/resources/working_hours)

Each `window` block sets `days` (ISO weekday numbers, `1` = Monday through `7` = Sunday), `start`, and `end` (24-hour `HH:MM` in the set's timezone). At least one `window` is required.

```hcl theme={null}
resource "scaling_working_hours" "uk_office" {
  name     = "UK office hours"
  timezone = "Europe/London"

  window {
    days  = [1, 2, 3, 4, 5]
    start = "09:00"
    end   = "17:00"
  }
}

resource "scaling_working_hours" "us_office" {
  name     = "US office hours"
  timezone = "America/New_York"

  window {
    days  = [1, 2, 3, 4, 5]
    start = "08:00"
    end   = "18:00"
  }
}
```

### `scaling_escalation_policy`

Manages an [escalation policy](/concepts/escalation-policies) as an ordered list of steps. Position is determined by the order of the `step` blocks. → [Registry reference](https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest/docs/resources/escalation_policy)

A step may carry an optional `condition` block — a [working hours condition](/concepts/working-hours#layer-conditions-follow-the-sun-escalation) of the form `{ working_hours_id, when }`, where `when` is `during` or `outside`. The step participates only while the firing instant is during/outside the referenced set's windows; an ineligible step is skipped (never held). If every step's condition fails, the last step is paged unconditionally. A step with no `condition` block is unconditional.

```hcl theme={null}
resource "scaling_escalation_policy" "follow_the_sun" {
  name        = "Follow the sun"
  description = "Page the UK rotation during UK hours, the US rotation otherwise"

  step {
    target_type            = "schedule"
    target_id              = scaling_oncall_schedule.uk_primary.id
    escalate_after_seconds = 300

    condition {
      working_hours_id = scaling_working_hours.uk_office.id
      when             = "during"
    }
  }

  step {
    target_type            = "schedule"
    target_id              = scaling_oncall_schedule.us_primary.id
    escalate_after_seconds = 600

    condition {
      working_hours_id = scaling_working_hours.us_office.id
      when             = "during"
    }
  }
}
```

<Warning>
  Omitting the `condition` block on a step that previously had one **surfaces a diff and clears the condition** on apply — it is not silently preserved. Because the condition gates who gets paged, keep it in your configuration as long as you want it enforced; a config without it is the source of truth and wins.
</Warning>

### `scaling_routing_policy`

Manages a [routing policy](/concepts/routing-policies) that maps each alert severity to an outcome. A complete policy always carries exactly four `rule` blocks — one per severity (`critical`, `high`, `medium`, `low`). → [Registry reference](https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest/docs/resources/routing_policy)

Each rule's `outcome` is one of `incident`, `provisional_page`, `notification`, or `drop`. For paging outcomes, set `escalation_policy_id` to the escalation policy that should handle the page; omit it to fall back to the alert's component default.

```hcl theme={null}
resource "scaling_routing_policy" "payments" {
  name        = "Payments Routing"
  description = "Stricter routing for payment incidents"

  rule {
    severity             = "critical"
    outcome              = "incident"
    escalation_policy_id = scaling_escalation_policy.default.id
  }

  rule {
    severity = "high"
    outcome  = "provisional_page"
  }

  rule {
    severity = "medium"
    outcome  = "notification"
  }

  rule {
    severity = "low"
    outcome  = "drop"
  }
}
```

<Note>
  Renaming a routing policy or editing a rule updates it in place — no resource replacement. Your organization's seeded default routing policy cannot be deleted.
</Note>

<Note>
  The **organization default working hours** designation — the set the [out-of-hours paging insight](/concepts/insights#out-of-hours-paging) classifies against — is intentionally **not** managed by Terraform. It is an internal organization setting; set it from organization settings in the dashboard. Terraform manages the working hours sets and the step conditions that consume them, not which set is the org default.
</Note>

## Learn more

* [Complete provider reference on the Terraform Registry](https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest/docs)
* [Provider on the Terraform Registry](https://registry.terraform.io/providers/scaling-cloud/scaling-cloud/latest)
* [Provider source and examples on GitHub](https://github.com/scaling-cloud/terraform-provider-scaling-cloud)
* [Working hours concept](/concepts/working-hours) and [Follow-the-sun escalation](/guides/follow-the-sun-escalation)
* [Routing policies concept](/concepts/routing-policies) and [Configure a routing policy](/guides/configure-routing-policy)