Proxmox tworzenie maszyn wirtualnych w Terraform

Terraform to narzędzie typu Infrastructure as Code (IaC), które służy do automatycznego tworzenia i zarządzania infrastrukturą za pomocą plików konfiguracyjnych (najczęściej w języku HCL – HashiCorp Configuration Language).

Zamiast klikać w panelu WWW, opisujesz infrastrukturę w kodzie, a Terraform:

Analizuje konfigurację (terraform plan)
Pokazuje co zostanie utworzone/zmienione
Wdraża zmiany (terraform apply)
Zapamiętuje stan infrastruktury (state)

Bezpłatne warsztaty: NMAP – Skanowanie Urządzeń i Portów w Sieci

Dowiedz się, jak wykrywać urządzenia w sieci, skanować porty i identyfikować usługi przy użyciu narzędzia NMAP. Poznasz podstawy skanowania, analizę wyników oraz praktyczne zastosowania w audycie bezpieczeństwa i testach penetracyjnych.

Środa, 18 marca o 14:00

Sprawdź szczegóły: https://asdevops.pl/warsztaty/

Do czego służy Terraform w Proxmox VE?

W Proxmox Terraform pozwala automatycznie zarządzać:

Tworzeniem maszyn wirtualnych (VM)
Klonowanie template (szablonu)
Konfiguracją dysków
Konfiguracją sieci (bridge, VLAN, IP)
Ustawianiem użytkowników i kluczy SSH (cloud-init)
Parametrami CPU, RAM, storage

Zamiast ręcznie tworzyć każdą VM w GUI Proxmox, możesz opisać ją w pliku:

resource "proxmox_vm_qemu" "vm1" {
  name        = "vm01"
  target_node = "pve"
  clone       = "ubuntu-template"  cores  = 2
  memory = 2048  ipconfig0 = "ip=192.168.1.75/24,gw=192.168.1.1"
}

Jedno polecenie:

terraform apply

→ i maszyna tworzy się automatycznie.

Dlaczego to jest przydatne?

Automatyzacja

Tworzenie 10, 20 czy 100 VM zajmuje tyle samo czasu co jednej.

Powtarzalność

Każde środowisko (dev/test/prod) może być identyczne.

Jak działa to technicznie?

Terraform komunikuje się z Proxmox przez API (token API), używając providera (np. Telmate/proxmox).

Kiedy warto używać Terraform w Proxmox?

Budujesz homelab
Tworzysz środowiska testowe
Zarządzasz większą liczbą VM
Chcesz przejść na Infrastructure as Code
Pracujesz w modelu DevOps

Jak działa Terraform?

Proces pracy z Terraformem składa się z kilku etapów:

Define – opis infrastruktury w kodzie.
Init – inicjalizacja providera (np. Proxmox).
Plan – symulacja zmian.
Apply – wdrożenie zmian.
Destroy – usunięcie infrastruktury (jeśli potrzebne).

Najważniejszą cechą jest podejście deklaratywne – opisuje się jaki ma być stan końcowy, a nie jak krok po kroku go osiągnąć.

Do czego służy Terraform w Proxmox?

W przypadku Proxmox Terraform działa poprzez provider Proxmox, który komunikuje się z API platformy. Pozwala to zarządzać infrastrukturą wirtualną w sposób automatyczny.

1. Automatyczne tworzenie maszyn wirtualnych

Zamiast ręcznie:

tworzyć VM,
przypisywać CPU i RAM,
konfigurować dyski,
ustawiać sieć,

można to opisać w kodzie:

liczba vCPU,
ilość RAM,
storage,
bridge sieciowy,
template,
cloud-init.

Efekt: środowisko testowe lub produkcyjne może zostać utworzone w kilka minut jednym poleceniem.

2. Zarządzanie klastrami Proxmox

W większych środowiskach (np. kilka node’ów):

wdrażanie identycznych VM na różnych hostach,
równoważenie rozmieszczenia maszyn,
automatyczne provisionowanie infrastruktury pod projekty.

Dzięki temu możliwe jest utrzymanie spójnej konfiguracji całego klastra.

3. Integracja z Cloud-Init

Terraform może:

tworzyć VM z template,
przekazywać dane cloud-init (user, SSH keys, hostname, IP),
automatycznie konfigurować system przy pierwszym uruchomieniu.

To pozwala budować w pełni automatyczne środowiska (np. serwer WWW + baza + load balancer).

4. Tworzenie środowisk testowych i labów

W środowiskach testowych można:

uruchamiać kompletne środowisko (np. 5 VM),
testować rozwiązania (np. monitoring, XDR, SIEM),
usuwać je po zakończeniu testów.

To szczególnie przydatne przy pracy z wieloma VM w Proxmox, gdzie potrzebna jest szybka rotacja środowisk.

Instalacja Terraform w Proxmox

Wymagania po stronie Proxmox VE

Działający serwer lub klaster Proxmox VE
Włączone i dostępne API (domyślnie aktywne)
Utworzony użytkownik z odpowiednimi uprawnieniami (najlepiej z tokenem API)
Skonfigurowany storage (np. local-lvm, ZFS, Ceph)
Bridge sieciowy (np. vmbr0)
Jeśli używany jest Cloud-Init: przygotowany template z zainstalowanym cloud-init

Przejdź na Swój serwer Proxmox. Utworzymy po kolei użytkownika, przypiszemy mu rolę administratora a następnie utworzymy dla niego API Token. Kliknij w Datacenter / Users / Add

Nadaj nazwę użytkownikowi w sekcji User name:, np. terraform oraz kliknij Add

Teraz nad Users, kliknij w Permissions / Add / User Permissions

W sekcji Path:, sybierz „/” i wybierz utworzonego użytkownika w sekcji User, następnie w sekcji Role: wybierz Administrator, kliknij Add

Dodajmy teraz klucz API użytkownikowi w sekcji API Tokens, kliknij Add, wybierz w User: utworzonego wcześniej użytkownika terraform, odznacz sekcję Privilege Separation, nadaj nazwę tokena w Token ID: i finalnie kliknij Add

Skopiuj wartości Token ID: oraz Secret: ,np do notatnika ! Jest to bardzo ważne, bo te dane pojawią się tylko raz, a będą nam potrzebne do konfiguracji pliku main.tf w dalszej części artykułu !

Instalacja szablonu cloud-init oraz terraform

W pierwszej kolejności stwórz szablon cloud-init, proces instalacji opisałem w artykule znajdującym się pod adresem:

Proxmox Cloud-Init krok po kroku

Kolejnym krokiem jest utworzenie serwera (ubuntu lub debian) oraz zainstalowanie na nim Terraform. Po zainstalowaniu serwera, zaloguj się na niego. Zainstaluj wymagane paczki:

sudo apt-get update && sudo apt-get install -y gnupg software-properties-common

Zainstaluj klucz GPG:

wget -O- https://apt.releases.hashicorp.com/gpg | \
gpg --dearmor | \
sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null

Dodaj oficjalne repozytorium HashiCorp:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

Aktualizuj repozytoria:

sudo apt update

Zainstaluj Terraform i potwierdź instalację klawiszem „y„:

sudo apt-get install terraform

Sprawdź zainstalowaną wersję Terraform (w dniu pisania artykułu, moja wersja to 1.44.6):

terraform -v

Tworzenie pierwszej maszyny za pomocą klonowania maszyny wirtualnej (VM) w terraform

Na serwerze z zainstalowanym Terraform, utwórz plik main.tf

nano main.tf

Wklej zawartość kodu:

# This is a basic Terraform configuration to clone a VM from a template using the bpg/proxmox provider.
# Fill in the variables below with your specific Proxmox environment details.
# This block tells Terraform to use the bpg/proxmox provider.
terraform {
  required_providers {
    proxmox = {
      source = "bpg/proxmox"
      # It's a good practice to pin a specific version to prevent unexpected changes.
      version = ">=0.80.0" 
    }
  }
}

# Configure the Proxmox provider.
# You can use a dedicated API token for authentication, which is more secure than a username and password.
provider "proxmox" {
  # The endpoint is the URL of your Proxmox VE API, usually with port 8006.
  endpoint = "https://Proxmox_adres_IP:8006/"
  # The API token should be in the format "<token_id>=<token_secret>"
  # It is highly recommended to use environment variables or a separate tfvars file for sensitive data.
  api_token = "API_ID=API_SECRET"
  # Set to true to bypass TLS certificate verification.
  insecure = true
}

# The proxmox_virtual_environment_vm resource is used to manage a VM.
resource "proxmox_virtual_environment_vm" "vm" {
  # A descriptive name for the new VM.
  name = "grupadm2-test"
  # The name of the Proxmox node where the VM will be created.
  node_name = "grupadm2" 
  # A unique VM ID. Proxmox will assign one if not specified.
  vm_id = 200
  # This block is crucial for cloning from a template.
  clone {
    # The vm_id of the existing template you want to clone from.
    vm_id = 125
    # Set to true for a full clone, which creates an independent disk image.
    full = true
  }  
  # Set the number of CPU cores for the new VM.
  cpu {
    cores = 2
  }

  # Set the dedicated memory in MB for the new VM.
  memory {
    dedicated = 2048
  }

  # Configure the VM's disk.
  # This section can be used to override or add disks to the cloned VM.
  # The disk cloned from the template is automatically handled.
  # Example to create a new disk on a different datastore:
  # disk {
  #   datastore_id = "local-lvm"
  #   interface    = "scsi0"
  #   size         = 32
  # }

  # Configure networking for the VM. This example uses a bridged network device.
  network_device {
    bridge = "vmbr0"
  }
 agent {
    enabled = false   # disables waiting for guest agent
  }
  

  initialization {
    ip_config {
      ipv4 {
        # Set the IPv4 address to "dhcp" to use a dynamic IP address from the network.
        address = "192.168.1.75/24"
      gateway = "192.168.1.1"
      }
    }
  }
}

Ważne! Adres IP a po dwukropku port 8006 https://Proxmox_adres_IP:8006/ oraz xxxxxxx=xxxxxxx (Token_ID=SECRET). Wartości wklej przed i po znaku „=” !

Sekcja name (nazwa maszyny która będzie utworzona), sekcja node_name (nazwa Node Twojego serwera Proxmox)

node_name znajduje się pod Datacenter

vm_id to numer maszyny który zostanie utworzony po sklonowaniu maszyny wirtualnej (VM), musi być od dostępny/unikatowy, nie może pokrywać się z aktualnie posiadanymi maszynami na Twoim serwerze !

Pod sekcją clone, znajduje się kolejny vm_id, jest to numer maszyny który już istnieje na Twoim serwerze i z niego będzie kopiowana maszyna wirtualna:

W sekcji cpu ustawiasz za cores ilość rdzeni, które chcesz przypisać tworzonej maszynie

W sekcji memory ustawiasz za dedicated ilość pamięci RAM:

W sekcji network_device ustawiasz za bridge, nazwę interfejsu sieciowego z którego korzystasz. Możesz znaleźć nazwę interfejsu sieciowego w Twój node / Network

W sekcji ipv4 ustawiasz za address oraz gateway, ręcznie przypisujesz adres IP oraz bramę sieciową

Lub automatycznie przez serwer DHCP, po prostu wpisując dhcp

Po skonfigurowaniu zapisz plik i wykonaj komendę, pobrania providera oraz zainicjalizowanie Terraform

terraform init

Jeśli konfiguracja jest poprawna ujrzysz „Terraform has been successfully initialized!”

Kolejna komenda planuje i podsumowuje konfigurację:

terraform plan

KOmenda apply, zatwierdza i uruchamia proces tworzenia maszyny:

Po wykonaniu polecenia, zostaniesz poproszony o potwierdzenie wykonania akcji za Enter a value: wpisz yes i zatwierdź:

Po wykonaniu zadań Terraform, poinformuje Cię o utworzeniu maszyny (u mnie zajęło to 4s i utworzona została maszyna o id=200)

Gotowe! Po utworzeniu maszyna automatycznie zacznie się uruchamiać. Po uruchomieniu możesz się zalogować!

Tworzenie maszyn za pomocą cloud-init

Podobnie tworzy się maszyny za pomocą szablonu cloud-init. Tutaj uprościłem kod pliku main.tf

terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = ">=0.80.0"
    }
  }
}

provider "proxmox" {
  endpoint  = "https://Proxmox_adres_IP:8006/"
  api_token = "API_ID=API_SECRET"
  insecure  = true
}

# ── VM 1 ──────────────────────────────────────────────
resource "proxmox_virtual_environment_vm" "vm1" {
  name      = "simple-cloned-vm-1"
  node_name = "grupadm2"
  vm_id     = 200

  clone {
    vm_id = 300
    full  = true
  }

  cpu    { cores = 2 }
  memory { dedicated = 2048 }

  network_device { bridge = "vmbr0" }
  agent          { enabled = false }

  initialization {
    ip_config {
      ipv4 {
        address = "192.168.1.75/24"
        gateway = "192.168.1.1"
      }
    }
  }
}

# ── VM 2 ──────────────────────────────────────────────
resource "proxmox_virtual_environment_vm" "vm2" {
  name      = "simple-cloned-vm-2"
  node_name = "grupadm2"
  vm_id     = 201             # inny vm_id!

  clone {
    vm_id = 300
    full  = true
  }

  cpu    { cores = 1 }
  memory { dedicated = 1024 }

  network_device { bridge = "vmbr0" }
  agent          { enabled = false }

  initialization {
    ip_config {
      ipv4 {
        address = "192.168.1.76/24"
        gateway = "192.168.1.1"
      }
    }
  }
}

W sekcji provider za endpoint wpisz adres IP serwera proxmox, a za api_token wpisz API_ID oraz API_SECRET bez spacji przy znaku „=„:

Analogicznie zmieniasz ustawienia jak w/w skrypcie. Jedyną różnicą jest sekcja clone, gdzie za vm_id (w moim przypadku 300), ustawiasz numer ID, szablonu z którego Tworzysz maszyny! Konfigurować możesz dowolnie, według własnych potrzeb. To samo tyczy się konfiguracji VM1 oraz VM2 !

Do utworzenia maszyn ponownie wykonaj kolejno komendy:

terraform init

terraform plan

terraform apply

Po utworzeniu maszyn, zostaną one utworzone niemal w tym samym czasie !

Ostatnią ważną komendą jest, komenda:

terraform destroy

Usuwa ona wszystkie utworzone maszyny, które są skonfigurowane w pliku main.tf. Oczywiście przed dokonaniem usunięcia, musisz potwierdzić czy na pewno chcesz usunąć maszyny. Enter a value: yes

Artykuł opisuje wykorzystanie Terraform jako narzędzia typu Infrastructure as Code do automatycznego zarządzania infrastrukturą w Proxmox VE. Zamiast ręcznej konfiguracji w panelu WWW, infrastruktura definiowana jest deklaratywnie w plikach HCL, a proces wdrożenia obejmuje etapy init, plan, apply oraz destroy, przy czym Terraform analizuje zmiany, wdraża je i zapisuje stan infrastruktury.

W kontekście Proxmox narzędzie umożliwia automatyczne tworzenie i klonowanie maszyn wirtualnych, konfigurację CPU, RAM, dysków, sieci (bridge, VLAN, IP), a także integrację z Cloud-Init w celu ustawienia użytkowników, kluczy SSH i parametrów startowych systemu. Komunikacja odbywa się przez API Proxmox z wykorzystaniem tokena oraz providera (np. bpg/proxmox), co pozwala na szybkie budowanie powtarzalnych środowisk testowych, laboratoryjnych i produkcyjnych.

Przed wdrożeniem wymagane jest skonfigurowanie użytkownika z odpowiednimi uprawnieniami i tokenem API w Proxmox, przygotowanie storage oraz – w przypadku automatycznej konfiguracji systemu – szablonu z Cloud-Init. Instalacja Terraform na serwerze polega na dodaniu repozytorium HashiCorp i instalacji pakietu, a następnie utworzeniu pliku konfiguracyjnego (np. main.tf), w którym definiowane są parametry maszyny, źródłowy template, zasoby sprzętowe i ustawienia sieciowe.

Proces tworzenia VM odbywa się poprzez inicjalizację providera (terraform init), symulację zmian (terraform plan) oraz ich wdrożenie (terraform apply). Możliwe jest jednoczesne tworzenie wielu maszyn z jednego szablonu, a usunięcie całej infrastruktury realizowane jest poleceniem terraform destroy. Całość podkreśla zalety automatyzacji, powtarzalności konfiguracji oraz efektywnego zarządzania większą liczbą maszyn w środowisku Proxmox.

Bezpłatne warsztaty: NMAP – Skanowanie Urządzeń i Portów w Sieci

Środa, 18 marca o 14:00

Sprawdź szczegóły: https://asdevops.pl/warsztaty/