Terraform provider

Manage hostd Public Cloud projects, SSH keys, virtual machines, and firewalls with Terraform.

The hostd Terraform provider manages your Public Cloud as code: projects, SSH keys, virtual machines, and their firewalls. It uses the same API and the same API key.

Provider: hostdcloud/hostd in the Terraform Registry, where every resource and argument is documented.

Connect

Create an API key in the portal under Settings → API Keys and export it:

export HOSTD_API_KEY=<your-api-key>
terraform {
  required_providers {
    hostd = {
      source = "hostdcloud/hostd"
    }
  }
}

provider "hostd" {}

Terraform checks the key when it starts. An invalid key, or an api_url that is not an absolute http or https address without a path, fails the plan before any resource changes.

Access

The provider works with your API key, so it has the same access as the key (details):

  • hostd_ssh_key needs Write access to SSH keys.
  • hostd_project needs a key that is allowed to create projects; the key gets Full access to the projects it creates. To use an existing project, set its UUID as project_id.
  • hostd_vm needs Write access to the project; destroying a VM needs Full.
  • hostd_ip_set and hostd_ip_set_member need Write access to the project. Deleting a set also removes firewall rules that reference it.
  • hostd_security_group needs Write access to the project. Deleting a group detaches it from every VM.
  • hostd_vm_firewall needs Write access to the project. The firewall filters the VM's public interface. A rule with type = "group" and action set to the group's pve_group_name attaches a security group.
  • hostd_public_ips needs Read. hostd_public_ip_ptr needs Write and sets the PTR of an address the project already has. Removing it restores the default hostname and does not release the address.
  • hostd_private_networks and hostd_ip_addresses need Read. free_ips on a private network are the addresses lan_interfaces can use with mode = select.
  • Reading state and hostd_os_images need Read.

Use a separate key for each Terraform workspace. Export it as HOSTD_API_KEY (a CI secret) and do not put it in the configuration. Prefer a key that expires in 30 or 90 days: create the next key, point the secret at it, then delete the old one.

CommandMinimum access
terraform planRead on the project and on SSH keys
terraform applyWrite on the project, Write on SSH keys, and allowed to create projects
terraform destroyFull on the project

Example

resource "hostd_project" "main" {
  name         = "production"
  cluster_name = "waw-1"
}

resource "hostd_ssh_key" "admin" {
  name           = "admin"
  public_ssh_key = file("~/.ssh/id_ed25519.pub")
}

data "hostd_os_images" "available" {
  project_id = hostd_project.main.id
}

resource "hostd_vm" "web" {
  project_id  = hostd_project.main.id
  hostname    = "web-01"
  os_image    = "debian-12-amd64.qcow2"
  ssh_key_ids = [hostd_ssh_key.admin.id]
  cores       = 2
  ram_gb      = 4
  os_disk_gb  = 20
}

resource "hostd_security_group" "web" {
  project_id = hostd_project.main.id
  name       = "web"
  rules = [
    { type = "in", action = "ACCEPT", proto = "tcp", dport = "80,443" },
    { type = "in", action = "ACCEPT", proto = "tcp", dport = "22" },
  ]
}

resource "hostd_vm_firewall" "web" {
  project_id = hostd_vm.web.project_id
  vmid       = hostd_vm.web.vmid
  enable     = true
  policy_in  = "DROP"
  policy_out = "ACCEPT"
  rules = [
    { type = "group", action = hostd_security_group.web.pve_group_name },
  ]
}

output "web_ipv4" {
  value = hostd_vm.web.ipv4
}

Image names depend on the cluster: hostd_os_images returns the ones available in a project. You sign in to the VM with the SSH keys you attach; the provider sets a random password and does not expose it.

Resources

NameWhat it manages
hostd_projectA project in a cluster (zone)
hostd_ssh_keyAn SSH public key on your account
hostd_vmA VM: CPU, RAM, disk, CPU class, public and private networks
hostd_ip_setA named address list for firewall rules
hostd_ip_set_memberOne address or network in an IP set
hostd_security_groupA named, ordered list of firewall rules
hostd_vm_firewallA VM firewall: on or off, default policies, rules and attached security groups
hostd_os_images (data source)OS images available in a project
hostd_public_ips (data source)Public addresses reserved on a project
hostd_public_ip_ptrPTR hostname of a public address
hostd_private_networks (data source)Private networks in a project, with free addresses
hostd_ip_addresses (data source)Public addresses on the account

Limits

  • The provider follows the API limits: when a limit is reached it waits for the Retry-After time and retries. GET requests are also retried on HTTP 5xx and network errors, for up to two minutes. API errors are shown as the message text (detail, error, or field: message).
  • A VM's CPU or RAM can be lowered only with power_state set to stopped, and only 24 hours after it was created or last increased. timeouts overrides how long create, update, and delete may take.
  • Switching a VM's public network between ipv4, ipv6, and dual goes through off.
  • Private networks are attached with lan_interfaces (auto takes a free address, select uses a chosen one). Create them in the portal first. With public networking off and more than one network, mark exactly one is_gateway.
  • rules on hostd_security_group and hostd_vm_firewall is the complete ordered list, written in one request. Rules added to that group or VM in the portal are removed on the next apply. Destroying hostd_vm_firewall removes the rules and turns the VM firewall off.
  • Destroying a VM deletes its disks and every backup of that VM. Public addresses return to the pool unless retain_public_ips is true (a reserved IPv4 stays billed). wan_ip and wan_ipv6 attach a reserved address. Changing project_id, hostname, os_image, username, wan_ip, or wan_ipv6 replaces the VM. For a production VM set lifecycle { prevent_destroy = true }.
  • SSH keys are installed only when a VM is created. Changing ssh_key_ids or replacing a hostd_ssh_key does not touch the VM; update authorized_keys on the VM yourself.
  • An IP set cannot be renamed: a new name replaces the set.
  • If creating a VM or a project is interrupted, the provider keeps a VM with the same hostname, or a project with the same name in the same cluster, that appeared during that call, instead of creating another. A VM or project that existed before is never taken over.

On this page