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_key wymaga dostępu Write do kluczy SSH.
  • hostd_project wymaga 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 w project_id.
  • hostd_vm wymaga dostępu Write do projektu; usunięcie VM wymaga Full.
  • hostd_ip_set i hostd_ip_set_member wymagają dostępu Write do projektu. Usunięcie zestawu usuwa też reguły firewalla, które go używają.
  • hostd_security_group wymaga dostępu Write do projektu. Usunięcie grupy odłącza ją od każdej VM.
  • hostd_vm_firewall wymaga dostępu Write do projektu. Firewall filtruje publiczny interfejs VM. Reguła z type = "group" i action równym pve_group_name grupy podłącza security group.
  • hostd_public_ips wymaga Read. hostd_public_ip_ptr wymaga Write i ustawia PTR adresu, który projekt już ma. Usunięcie przywraca domyślną nazwę i nie zwalnia adresu.
  • hostd_private_networks i hostd_ip_addresses wymagają Read. free_ips w sieci prywatnej to adresy, których lan_interfaces może użyć z mode = select.
  • Odczyt stanu i hostd_os_images wymagają 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.

PolecenieMinimalny dostęp
terraform planRead do projektu i do kluczy SSH
terraform applyWrite do projektu, Write do kluczy SSH i prawo tworzenia projektów
terraform destroyFull 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

NazwaCzym zarządza
hostd_projectProjekt w klastrze (strefie)
hostd_ssh_keyPubliczny klucz SSH na koncie
hostd_vmVM: CPU, RAM, dysk, klasa CPU, sieci publiczna i prywatne
hostd_ip_setNazwana lista adresów dla reguł firewalla
hostd_ip_set_memberJeden adres lub sieć w zestawie IP
hostd_security_groupNazwana, uporządkowana lista reguł firewalla
hostd_vm_firewallFirewall 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_ptrNazwa 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-After i 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, error albo pole: komunikat).
  • CPU lub RAM VM można zmniejszyć tylko przy power_state ustawionym na stopped i dopiero 24 godziny po jej utworzeniu lub ostatnim zwiększeniu. timeouts zmienia, jak długo mogą trwać utworzenie, zmiana i usunięcie.
  • Zmiana sieci publicznej VM między ipv4, ipv6 i dual odbywa się przez off.
  • Sieci prywatne podłączasz przez lan_interfaces (auto bierze wolny adres, select uż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ą jako is_gateway.
  • rules w hostd_security_group i hostd_vm_firewall to pełna, uporządkowana lista, zapisywana jednym żądaniem. Reguły dodane do tej grupy lub VM w portalu znikają przy następnym apply. Usunięcie hostd_vm_firewall kasuje 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_ips jest true (zarezerwowany IPv4 nadal jest rozliczany). wan_ip i wan_ipv6 podłączają zarezerwowany adres. Zmiana project_id, hostname, os_image, username, wan_ip lub wan_ipv6 odtwarza VM. Dla produkcyjnej VM ustaw lifecycle { prevent_destroy = true }.
  • Klucze SSH są instalowane tylko przy tworzeniu VM. Zmiana ssh_key_ids albo wymiana hostd_ssh_key nie dotyka VM; authorized_keys na VM zmieniasz sam.
  • Zestawu IP nie da się przemianować: nowa name tworzy 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.

On this page