Провайдер 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 plan | Read до проєкту і до SSH-ключів |
terraform apply | Write до проєкту, Write до SSH-ключів і право створювати проєкти |
terraform destroy | Full до проєкту |
Приклад
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_vm | VM: 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_ptr | PTR-ім’я публічної адреси |
hostd_private_networks (джерело даних) | Приватні мережі в проєкті, з вільними адресами |
hostd_ip_addresses (джерело даних) | Публічні адреси на акаунті |
Ліміти
- Провайдер дотримується лімітів API: після досягнення ліміту чекає час із заголовка
Retry-Afterі повторює запит. Запити GET також повторюються при HTTP 5xx і мережевих помилках, щонайбільше дві хвилини. Помилки API показуються текстом повідомлення (detail,errorабополе: повідомлення). - CPU або RAM VM можна зменшити лише з
power_statestoppedі тільки через 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 чи проєкт, що існували раніше, він не перебирає.