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_keyneeds Write access to SSH keys.hostd_projectneeds 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 asproject_id.hostd_vmneeds Write access to the project; destroying a VM needs Full.hostd_ip_setandhostd_ip_set_memberneed Write access to the project. Deleting a set also removes firewall rules that reference it.hostd_security_groupneeds Write access to the project. Deleting a group detaches it from every VM.hostd_vm_firewallneeds Write access to the project. The firewall filters the VM's public interface. A rule withtype = "group"andactionset to the group'spve_group_nameattaches a security group.hostd_public_ipsneeds Read.hostd_public_ip_ptrneeds 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_networksandhostd_ip_addressesneed Read.free_ipson a private network are the addresseslan_interfacescan use withmode = select.- Reading state and
hostd_os_imagesneed 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.
| Command | Minimum access |
|---|---|
terraform plan | Read on the project and on SSH keys |
terraform apply | Write on the project, Write on SSH keys, and allowed to create projects |
terraform destroy | Full 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
| Name | What it manages |
|---|---|
hostd_project | A project in a cluster (zone) |
hostd_ssh_key | An SSH public key on your account |
hostd_vm | A VM: CPU, RAM, disk, CPU class, public and private networks |
hostd_ip_set | A named address list for firewall rules |
hostd_ip_set_member | One address or network in an IP set |
hostd_security_group | A named, ordered list of firewall rules |
hostd_vm_firewall | A 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_ptr | PTR 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-Aftertime 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, orfield: message). - A VM's CPU or RAM can be lowered only with
power_stateset tostopped, and only 24 hours after it was created or last increased.timeoutsoverrides how long create, update, and delete may take. - Switching a VM's public network between
ipv4,ipv6, anddualgoes throughoff. - Private networks are attached with
lan_interfaces(autotakes a free address,selectuses a chosen one). Create them in the portal first. With public networking off and more than one network, mark exactly oneis_gateway. rulesonhostd_security_groupandhostd_vm_firewallis the complete ordered list, written in one request. Rules added to that group or VM in the portal are removed on the next apply. Destroyinghostd_vm_firewallremoves 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_ipsis true (a reserved IPv4 stays billed).wan_ipandwan_ipv6attach a reserved address. Changingproject_id,hostname,os_image,username,wan_ip, orwan_ipv6replaces the VM. For a production VM setlifecycle { prevent_destroy = true }. - SSH keys are installed only when a VM is created. Changing
ssh_key_idsor replacing ahostd_ssh_keydoes not touch the VM; updateauthorized_keyson the VM yourself. - An IP set cannot be renamed: a new
namereplaces 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.