Provider Terraform
Zarządzaj projektami, kluczami SSH, maszynami wirtualnymi i firewallem hostd Public Cloud za pomocą Terraform.
Provider Terraform hostd zarządza Twoim Public Cloud jako kodem: projektami, kluczami SSH, maszynami wirtualnymi i ich firewallem. Korzysta z tego samego API i tego samego klucza API.
Provider: hostdcloud/hostd w Terraform Registry – tam opisano każdy zasób i argument.
Podłączenie
Utwórz klucz API w portalu w Ustawienia → Klucze API i wyeksportuj go:
export HOSTD_API_KEY=<your-api-key>terraform {
required_providers {
hostd = {
source = "hostdcloud/hostd"
}
}
}
provider "hostd" {}Terraform sprawdza klucz przy starcie. Nieprawidłowy klucz albo api_url, które nie jest pełnym adresem http lub https bez ścieżki, przerywa plan, zanim zmieni się jakikolwiek zasób.
Dostęp
Provider działa z Twoim kluczem API, więc ma taki sam dostęp jak klucz (szczegóły):
hostd_ssh_keywymaga dostępu Write do kluczy SSH.hostd_projectwymaga klucza, który może tworzyć projekty; klucz dostaje Full do projektów, które utworzy. Aby użyć istniejącego projektu, wpisz jego UUID wproject_id.hostd_vmwymaga dostępu Write do projektu; usunięcie VM wymaga Full.hostd_ip_setihostd_ip_set_memberwymagają dostępu Write do projektu. Usunięcie zestawu usuwa też reguły firewalla, które go używają.hostd_security_groupwymaga dostępu Write do projektu. Usunięcie grupy odłącza ją od każdej VM.hostd_vm_firewallwymaga dostępu Write do projektu. Firewall filtruje publiczny interfejs VM. Reguła ztype = "group"iactionrównympve_group_namegrupy podłącza security group.hostd_public_ipswymaga Read.hostd_public_ip_ptrwymaga Write i ustawia PTR adresu, który projekt już ma. Usunięcie przywraca domyślną nazwę i nie zwalnia adresu.hostd_private_networksihostd_ip_addresseswymagają Read.free_ipsw sieci prywatnej to adresy, którychlan_interfacesmoże użyć zmode = select.- Odczyt stanu i
hostd_os_imageswymagają Read.
Użyj osobnego klucza dla każdego workspace Terraform. Ustaw go tylko jako HOSTD_API_KEY (sekret CI), nie w konfiguracji. Lepiej klucz na 30 lub 90 dni: utwórz następny, podmień sekret, potem usuń stary.
| Polecenie | Minimalny dostęp |
|---|---|
terraform plan | Read do projektu i do kluczy SSH |
terraform apply | Write do projektu, Write do kluczy SSH i prawo tworzenia projektów |
terraform destroy | Full do projektu |
Przykład
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
}Nazwy obrazów zależą od klastra: hostd_os_images zwraca obrazy dostępne w projekcie. Do VM logujesz się dołączonymi kluczami SSH; provider ustawia losowe hasło i go nie ujawnia.
Zasoby
| Nazwa | Czym zarządza |
|---|---|
hostd_project | Projekt w klastrze (strefie) |
hostd_ssh_key | Publiczny klucz SSH na koncie |
hostd_vm | VM: CPU, RAM, dysk, klasa CPU, sieci publiczna i prywatne |
hostd_ip_set | Nazwana lista adresów dla reguł firewalla |
hostd_ip_set_member | Jeden adres lub sieć w zestawie IP |
hostd_security_group | Nazwana, uporządkowana lista reguł firewalla |
hostd_vm_firewall | Firewall VM: włączony lub nie, polityki domyślne, reguły i podłączone grupy |
hostd_os_images (źródło danych) | Obrazy systemów dostępne w projekcie |
hostd_public_ips (źródło danych) | Adresy publiczne zarezerwowane w projekcie |
hostd_public_ip_ptr | Nazwa PTR adresu publicznego |
hostd_private_networks (źródło danych) | Sieci prywatne w projekcie, z wolnymi adresami |
hostd_ip_addresses (źródło danych) | Adresy publiczne na koncie |
Limity
- Provider przestrzega limitów API: po osiągnięciu limitu czeka czas z nagłówka
Retry-Afteri ponawia żądanie. Żądania GET są też ponawiane przy HTTP 5xx i błędach sieci, najwyżej przez dwie minuty. Błędy API są pokazywane jako tekst komunikatu (detail,erroralbopole: komunikat). - CPU lub RAM VM można zmniejszyć tylko przy
power_stateustawionym nastoppedi dopiero 24 godziny po jej utworzeniu lub ostatnim zwiększeniu.timeoutszmienia, jak długo mogą trwać utworzenie, zmiana i usunięcie. - Zmiana sieci publicznej VM między
ipv4,ipv6idualodbywa się przezoff. - Sieci prywatne podłączasz przez
lan_interfaces(autobierze wolny adres,selectużywa wybranego). Najpierw utwórz je w portalu. Gdy sieć publiczna jest wyłączona i sieci jest więcej niż jedna, oznacz dokładnie jedną jakois_gateway. ruleswhostd_security_groupihostd_vm_firewallto pełna, uporządkowana lista, zapisywana jednym żądaniem. Reguły dodane do tej grupy lub VM w portalu znikają przy następnym apply. Usunięciehostd_vm_firewallkasuje reguły i wyłącza firewall VM.- Usunięcie VM kasuje jej dyski i wszystkie jej kopie zapasowe. Adresy publiczne wracają do puli, chyba że
retain_public_ipsjest true (zarezerwowany IPv4 nadal jest rozliczany).wan_ipiwan_ipv6podłączają zarezerwowany adres. Zmianaproject_id,hostname,os_image,username,wan_iplubwan_ipv6odtwarza VM. Dla produkcyjnej VM ustawlifecycle { prevent_destroy = true }. - Klucze SSH są instalowane tylko przy tworzeniu VM. Zmiana
ssh_key_idsalbo wymianahostd_ssh_keynie dotyka VM;authorized_keysna VM zmieniasz sam. - Zestawu IP nie da się przemianować: nowa
nametworzy zestaw od nowa. - Gdy tworzenie VM lub projektu zostanie przerwane, provider zostawia VM o tym samym hostname albo projekt o tej samej nazwie w tym samym klastrze, które pojawiły się w trakcie tego wywołania, zamiast tworzyć drugie. VM ani projektu, które istniały wcześniej, nie przejmuje.