Провайдер Terraform

Керуйте проєктами, SSH-ключами, віртуальними машинами та фаєрволом hostd Public Cloud через Terraform.

Провайдер Terraform hostd керує вашим Public Cloud як кодом: проєктами, SSH-ключами, віртуальними машинами та їхнім фаєрволом. Він використовує той самий API і той самий ключ API.

Провайдер: hostdcloud/hostd у Terraform Registry – там описано кожен ресурс і аргумент.

Підключення

Створіть ключ API в порталі в Налаштування → Ключі API і експортуйте його:

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

provider "hostd" {}

Terraform перевіряє ключ на старті. Недійсний ключ або api_url, що не є повною адресою http чи https без шляху, зупиняє план до будь-яких змін ресурсів.

Доступ

Провайдер працює з вашим ключем API, тож має такий самий доступ, як і ключ (докладніше):

  • hostd_ssh_key потребує доступу Write до ключів SSH.
  • hostd_project потребує ключа, який може створювати проєкти; ключ отримує Full до проєктів, які створить. Щоб використати наявний проєкт, вкажіть його UUID у project_id.
  • hostd_vm потребує доступу Write до проєкту; видалення VM потребує Full.
  • hostd_ip_set і hostd_ip_set_member потребують доступу Write до проєкту. Видалення набору також прибирає правила фаєрвола, які на нього посилаються.
  • hostd_security_group потребує доступу Write до проєкту. Видалення групи від’єднує її від кожної VM.
  • hostd_vm_firewall потребує доступу Write до проєкту. Фаєрвол фільтрує публічний інтерфейс VM. Правило з type = "group" і action, рівним pve_group_name групи, підключає security group.
  • hostd_public_ips потребує Read. hostd_public_ip_ptr потребує Write і задає PTR адреси, яку проєкт уже має. Видалення повертає типову назву і не звільняє адресу.
  • hostd_private_networks і hostd_ip_addresses потребують Read. free_ips у приватній мережі – це адреси, які lan_interfaces може взяти з mode = select.
  • Читання стану та hostd_os_images потребують Read.

Окремий ключ на кожен workspace Terraform. Задавайте його лише як HOSTD_API_KEY (секрет CI), не в конфігурації. Краще ключ на 30 або 90 днів: створіть наступний, замініть секрет, потім видаліть старий.

КомандаМінімальний доступ
terraform planRead до проєкту і до SSH-ключів
terraform applyWrite до проєкту, Write до SSH-ключів і право створювати проєкти
terraform destroyFull до проєкту

Приклад

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
}

Назви образів залежать від кластера: hostd_os_images повертає образи, доступні в проєкті. До VM ви підключаєтеся доданими SSH-ключами; провайдер встановлює випадковий пароль і не показує його.

Ресурси

НазваЧим керує
hostd_projectПроєкт у кластері (зоні)
hostd_ssh_keyПублічний SSH-ключ в акаунті
hostd_vmVM: CPU, RAM, диск, клас CPU, публічна та приватні мережі
hostd_ip_setІменований список адрес для правил фаєрвола
hostd_ip_set_memberОдна адреса або мережа в IP-наборі
hostd_security_groupІменований упорядкований список правил фаєрвола
hostd_vm_firewallФаєрвол VM: увімкнений чи ні, політики за замовчуванням, правила і підключені групи
hostd_os_images (джерело даних)Образи ОС, доступні в проєкті
hostd_public_ips (джерело даних)Публічні адреси, зарезервовані в проєкті
hostd_public_ip_ptrPTR-ім’я публічної адреси
hostd_private_networks (джерело даних)Приватні мережі в проєкті, з вільними адресами
hostd_ip_addresses (джерело даних)Публічні адреси на акаунті

Ліміти

  • Провайдер дотримується лімітів API: після досягнення ліміту чекає час із заголовка Retry-After і повторює запит. Запити GET також повторюються при HTTP 5xx і мережевих помилках, щонайбільше дві хвилини. Помилки API показуються текстом повідомлення (detail, error або поле: повідомлення).
  • CPU або RAM VM можна зменшити лише з power_state stopped і тільки через 24 години після створення або останнього збільшення. timeouts змінює, скільки можуть тривати створення, зміна і видалення.
  • Зміна публічної мережі VM між ipv4, ipv6 і dual відбувається через off.
  • Приватні мережі підключаються через lan_interfaces (auto бере вільну адресу, select використовує обрану). Спершу створіть їх у порталі. Коли публічна мережа вимкнена і мереж більше однієї, позначте рівно одну як is_gateway.
  • rules у hostd_security_group і hostd_vm_firewall – повний упорядкований список, що записується одним запитом. Правила, додані до цієї групи або VM у порталі, зникають під час наступного apply. Видалення hostd_vm_firewall прибирає правила і вимикає фаєрвол VM.
  • Видалення VM стирає її диски і всі її резервні копії. Публічні адреси повертаються в пул, якщо retain_public_ips не true (зарезервований IPv4 і далі тарифікується). wan_ip і wan_ipv6 підключають зарезервовану адресу. Зміна project_id, hostname, os_image, username, wan_ip або wan_ipv6 перестворює VM. Для продакшн-VM задайте lifecycle { prevent_destroy = true }.
  • SSH-ключі встановлюються лише під час створення VM. Зміна ssh_key_ids або заміна hostd_ssh_key не зачіпає VM; authorized_keys на VM оновлюйте самі.
  • IP set не можна перейменувати: нове name створює набір заново.
  • Якщо створення VM або проєкту перервалось, провайдер лишає VM з тим самим hostname або проєкт з тією самою назвою в тому самому кластері, що з’явилися під час цього виклику, замість створення другого. VM чи проєкт, що існували раніше, він не перебирає.

On this page