RareCloud Terraform provider: setup, resources and data sources

In one paragraph: the rarecloudio/rarecloud provider lets Terraform create and track RareCloud cloud servers, volumes, private networks, firewalls, load balancers, reserved IPs, reverse DNS, SSH keys, Object Storage buckets and keys, and domain registrations, all through the public API at https://api.rarecloud.io/v1. This page covers version 0.3.0, published on the Terraform Registry for macOS, Linux and Windows (amd64, and arm64 on macOS and Linux). The source is on GitHub.

Set up the provider

terraform {
  required_providers {
    rarecloud = {
      source  = "rarecloudio/rarecloud"
      version = "~> 0.3"
    }
  }
}

provider "rarecloud" {
  # token = "rc_pat_..."   # better: export RARECLOUD_TOKEN
}

Run terraform init and Terraform downloads the provider from the registry.

Authenticate

Create a token in the console under Account, then API tokens. For the resources below it needs services:read and services:write (Object Storage included); add account:read and account:write for rarecloud_ssh_key and rarecloud_account, billing:read for the billing attributes of rarecloud_account, and domains:read / domains:write for domains. Scopes match exactly, so :write does not include :read.

Give it to the provider in one of two ways:

The endpoint defaults to https://api.rarecloud.io and the provider adds /v1 itself. Keep the token out of your .tf files: the environment variable is enough.

Resources

rarecloud_server

A Cloud VM.

Exports id, ipv4, ipv6, private_ip, hostname, status and api_access. Create waits until the server is active (up to 10 minutes), so its addresses are in state when the apply ends. If it does not come up in time, the server stays in state marked tainted and the next apply replaces it. Destroy waits until the server is gone.

rarecloud_volume

A block storage volume, billed per GB while it exists.

Exports id, status and api_access.

rarecloud_network

A private network (VPC). The CIDR is allocated for you.

Exports id, cidr, is_default and api_access.

rarecloud_firewall

A stateful firewall (security group).

Exports id and is_default (the account's default firewall cannot be deleted).

A new firewall starts with default rules: inbound ICMP and TCP 22, 80 and 443, outbound everything. Leave inbound_rule or outbound_rule unset and Terraform keeps whatever that direction has. Set it and that direction's rules are made to match your list exactly, so a default you do not list is removed. Rules are matched by protocol, port range and CIDR, so their order does not matter.

rarecloud_load_balancer

An L4 TCP load balancer.

Exports id, status, ipv4 (its public address), members (each with id, address, port, status) and api_access. Create waits up to 15 minutes for the load balancer to finish building and become active; destroy waits until it is gone. It costs €9 a month with its public IP included, billed hourly.

rarecloud_reserved_ip

A static public IPv4. Destroying it releases the address, and that cannot be undone.

Exports id, ip, region and attached.

rarecloud_reverse_dns

The PTR record for a server's primary public IPv4. Destroying it removes only the record.

rarecloud_ssh_key

An account-wide SSH key, offered when you deploy.

Exports id and fingerprint.

rarecloud_object_storage

Enables Object Storage for the account. There is nothing to configure, and it is optional: the first bucket enables the service too. Use it to make the account an explicit dependency or to read the price card and limits.

Destroying it disables Object Storage for good. The API refuses that while any bucket or active key exists, so give your buckets and keys depends_on = [rarecloud_object_storage.this]. Exports id, handle, status, plan, quota_tb, max_buckets, max_keys, regions, pricing and created_at.

rarecloud_object_storage_bucket

A bucket. Its real name, the one S3 clients use, is <handle>-<name>, exported as full_name.

Exports id, full_name, endpoint, bucket_url, public_url (empty until public delivery launches), status and created_at.

rarecloud_object_storage_key

An S3 access key. Keys cannot be edited, so any change replaces the key and its secret. Destroying it revokes the key.

Exports id, access_key_id, secret_access_key (sensitive), secret_preview, status and created_at. The API returns the secret once, so Terraform keeps it in state in plain text, even though it is marked sensitive: protect your state file.

rarecloud_domain

A domain registration. Creating it places an order and an invoice; the domain is registered once the order is paid, so status starts as Pending and fills in on a later refresh. Destroying it only removes it from the Terraform state. It does not cancel the domain.

Data sources

Managed Kubernetes clusters are not a Terraform resource in 0.3.0. Create them in the console or through the MCP server, and fetch kubeconfigs with the CLI.

Recipes

Deploy a VM with your SSH key

data "rarecloud_image" "ubuntu" {
  slug = "ubuntu-24.04"
}

resource "rarecloud_ssh_key" "me" {
  name       = "laptop"
  public_key = file("~/.ssh/id_ed25519.pub")
}

resource "rarecloud_network" "app" {
  name = "app-vpc"
}

resource "rarecloud_server" "web" {
  name           = "web-01"
  plan           = "g-2vcpu-8gb"
  region         = "bucharest-ro"
  image          = data.rarecloud_image.ubuntu.slug
  ssh_public_key = rarecloud_ssh_key.me.public_key
  vpc_id         = rarecloud_network.app.id
}

Add a volume and a fixed IP

resource "rarecloud_volume" "data" {
  name      = "web-01-data"
  size_gb   = 50
  server_id = rarecloud_server.web.id
}

resource "rarecloud_reserved_ip" "web" {
  server_id = rarecloud_server.web.id
}

output "web_ip" {
  value = rarecloud_reserved_ip.web.ip
}

Open SSH and HTTPS only

resource "rarecloud_firewall" "web" {
  name = "web"

  inbound_rule = [
    { protocol = "tcp", port_range_min = 22,  port_range_max = 22,  remote_cidr = "203.0.113.10/32" }, # ssh from the office
    { protocol = "tcp", port_range_min = 443, port_range_max = 443, remote_cidr = "0.0.0.0/0" },       # https
  ]

  attached_server_ids = [rarecloud_server.web.id]
}

Balance two servers

resource "rarecloud_load_balancer" "web" {
  name              = "web-lb"
  port              = 443
  member_server_ids = [rarecloud_server.web.id, rarecloud_server.web2.id]
  health_check      = true
}

A bucket and a key for CI

resource "rarecloud_object_storage_bucket" "assets" {
  name       = "assets"
  region     = "eu-central-1"
  handle     = "acme"   # first bucket only; the bucket becomes acme-assets
  versioning = true
}

resource "rarecloud_object_storage_key" "ci" {
  name    = "ci"
  buckets = [rarecloud_object_storage_bucket.assets.id]
  access  = "readwrite"
}

output "s3_endpoint" { value = rarecloud_object_storage_bucket.assets.endpoint }
output "ci_secret" {
  value     = rarecloud_object_storage_key.ci.secret_access_key
  sensitive = true
}

The first bucket starts the monthly base fee. Point any S3 tool at the endpoint with the key's access_key_id and secret.

Check the bill before you apply

data "rarecloud_account" "me" {}

output "spendable_cents" { value = data.rarecloud_account.me.billing_available_cents }
output "open_invoice"    { value = data.rarecloud_account.me.open_invoice_id }

The billing attributes need a token with billing:read; without it they stay empty and Terraform shows a warning.

Destroy

terraform destroy -target=rarecloud_volume.data   # one resource
terraform destroy                                 # everything in this configuration

Destroying a server, volume, bucket or reserved IP deletes it for good. A rarecloud_domain is the exception: destroy leaves the domain registered.

Safe retries

Every resource create sends an Idempotency-Key. If the API's answer is lost to a timeout or a dropped connection, the provider retries up to 3 times with the same key and the API runs the create once, so a server created while the answer was in flight lands in state instead of being left behind as an untracked duplicate.

Troubleshooting

Links

• Registry: registry.terraform.io/providers/rarecloudio/rarecloud
• Source: github.com/RareCloudio/terraform-provider-rarecloud
• API reference: console.rarecloud.io/docs/api
• Step-by-step tutorial: Terraform on RareCloud
• The same API from a terminal or an agent: CLI docs and MCP docs