iac-proxmox

IAC do zarządzania clustrem Proxmox przy użyciu OpenTofu.

• 1: Pobieranie template LXC
• 2: Kontener LXC
• 3: Virtual Machine

iac-proxmox/
├── containers_templates/   # Szablony LXC
├── machines/               # Definicje kontenerów LXC i VM (ctXXXXX.tf)
├── _locals.tf              # Wspólne zmienne (storage, node, pool)
└── main.tf

1 - Pobieranie template LXC

Pobieranie template LXC

1. Cel i kontekst

Szablony LXC (templates) w środowisku Proxmox VE są wykorzystywane do szybkiego i powtarzalnego tworzenia kontenerów systemowych. W projekcie iac-proxmox za pobieranie oraz utrzymanie tych szablonów odpowiada dedykowany katalog:

./containers_templates/

Zasoby zdefiniowane w tym katalogu:

• automatycznie pobierają obrazy kontenerów,
• zapisują je w magazynie danych Proxmoxa,
• udostępniają je do dalszego użycia przez moduł proxmox-container.

2. Pobranie szablonu LXC

Poniższy zasób odpowiada za pobranie oficjalnego szablonu Ubuntu 24.04 LTS bezpośrednio z repozytorium Proxmoxa:

resource "proxmox_virtual_environment_download_file" "ubuntu24-10" {
  content_type       = "vztmpl"
  datastore_id       = local.storage_name
  node_name          = local.default_node
  file_name          = "ubuntu-24.04.tar.zst"
  url                = "http://download.proxmox.com/images/system/ubuntu-24.04-standard_24.04-2_amd64.tar.zst"
  checksum           = "4030982618eeae70854e8f9711adbd09"
  checksum_algorithm = "md5"
}

3. Omówienie parametrów zasobu

✅ Dzięki zastosowaniu checksum OpenTofu weryfikuje, czy pobrany plik nie został uszkodzony.

4. Zmienne lokalne wykorzystywane w zasobie

Zmienna local.storage_name oraz local.default_node są zwykle zdefiniowane w pliku:

locals.tf

Przykładowa definicja:

locals {
  storage_name = "local"
  default_node = "proxmox-1"
}

✅ Takie podejście zapewnia:

• centralne zarządzanie konfiguracją,
• łatwą migrację między środowiskami,
• brak twardo zakodowanych nazw w zasobach.

5. Zależność od modułu proxmox-container

Po pobraniu szablonu, może on zostać wykorzystany w module:

modules/proxmox-container

Przykład użycia template w definicji kontenera:

template = "local:vztmpl/ubuntu-24.04.tar.zst"

Moduł proxmox-container wykorzystuje ten template do:

• utworzenia systemu plików kontenera,
• konfiguracji sieci,
• ustawienia użytkowników,
• przypisania zasobów CPU i RAM.

2 - Kontener LXC

Kontener LXC

W przeciwieństwie do klasycznych maszyn wirtualnych:

• nie emuluje pełnego sprzętu,
• nie wymaga osobnego jądra systemu,
• zużywa znacznie mniej zasobów,
• uruchamia się niemal natychmiastowo.

W środowisku Proxmox VE kontenery LXC są wykorzystywane do:

• uruchamiania mikroserwisów,
• hostowania aplikacji backendowych,
• serwerów proxy, API, workerów CI,
• środowisk testowych i stagingowych.

✅ LXC to rozwiązanie:

• szybsze niż VM,
• tańsze zasobowo,
• idealne do infrastruktury jako kod (IaC).

1. Rola kontenerów LXC w iac-proxmox

W projekcie iac-proxmox kontenery LXC są:

• w pełni zarządzane przez OpenTofu,
• tworzone automatycznie z gotowych template,
• konfigurowane przez moduł:

modules/proxmox-container

Każdy kontener posiada:

• jednoznaczny CT ID,
• przypisany node, storage, pool,
• zdefiniowane zasoby CPU, RAM i dysk,
• użytkownika technicznego,
• klucz SSH.

2. Struktura katalogów dla kontenerów

Definicje kontenerów znajdują się w katalogu:

./machines/

Każdy kontener posiada osobny plik:

ctXXXXX.tf

Przykład:

ct01011.tf

✅ Zapewnia to:

• czytelność,
• pełną niezależność kontenerów,
• łatwą kontrolę zmian w Git.

3. Tworzenie kontenera LXC

module "ct01011" {
  source = "git@gitlab.rachuna-net.pl:pl.rachuna-net/infrastructure/opentofu/modules/proxmox-container.git?ref=v1.0.0"

  hostname      = "ct01011.rachuna-net.pl"
  description   = "example-service"
  node_name     = "pve-s1"
  ct_id         = 1011
  pool_id       = "web-proxy"
  start_on_boot = true
  tags          = ["example", "ubuntu"]

  cpu_cores = 2
  memory = { dedicated = 2048, swap = 1024 }
  disk   = { storage_name = "local-lvm", disk_size = 32 }

  operating_system = {
    template_file = "local:vztmpl/ubuntu-24.04.tar.zst"
    type          = "ubuntu"
  }

  user_account = {
    username       = "techuser"
    password       = "change-me"
    public_ssh_key = "ssh-ed25519 AAAA..."
  }
}

4. Omówienie kluczowych parametrów

4.1. Identyfikacja i lokalizacja

4.2. Zasoby sprzętowe

cpu_cores = 2

memory = {
  dedicated = 2048
  swap      = 1024
}

disk = {
  storage_name = "local-lvm"
  disk_size    = 32
}

✅ Pozwala to precyzyjnie sterować:

• obciążeniem hosta,
• wydajnością usług,
• dynamicznym skalowaniem.

4.3. System operacyjny

operating_system = {
  template_file = "local:vztmpl/ubuntu-24.04.tar.zst"
  type          = "ubuntu"
}

✅ Template musi być:

• wcześniej pobrany przez containers_templates,
• dostępny na storage Proxmoxa.

4.4. Konto użytkownika

user_account = {
  username       = "techuser"
  password       = "change-me"
  public_ssh_key = "ssh-ed25519 AAAA..."
}

✅ Tworzone automatycznie:

• konto techniczne,
• dostęp SSH,
• możliwość wyłączenia logowania root.

5. Integracja z Vault

Jeżeli dane dostępowe pochodzą z Vault, zamiast jawnych wartości:

user_account = {
  username       = data.vault_kv_secret_v2.ct.data["username"]
  password       = data.vault_kv_secret_v2.ct.data["password"]
  public_ssh_key = data.vault_kv_secret_v2.ct.data["ssh_key"]
}

✅ Pozwala to:

• usunąć hasła z repozytorium,
• rotować dane dostępowe,
• centralnie kontrolować dostęp.

3 - Virtual Machine

Maszyny wirtualne

1. Struktura katalogów dla kontenerów

Definicje vm znajdują się w katalogu:

./machines/

Każdy vm posiada osobny plik:

vmXXXXX.tf

Przykład:

vm01011.tf

✅ Zapewnia to:

• czytelność,
• pełną niezależność kontenerów,
• łatwą kontrolę zmian w Git.

2. Tworzenie VM

module "vm01017" {
  source = "git@gitlab.rachuna-net.pl:pl.rachuna-net/infrastructure/opentofu/modules/proxmox-vm.git?ref=v1.0.0"

  hostname      = "vm01017.rachuna-net.pl"
  description   = "Kubernetes master w4"
  node_name     = "pve-s1"
  vm_id         = 1017
  pool_id       = "kubernetes"
  protection    = true
  tags          = ["kubernetes", "master", "ubuntu"]
  is_dmz        = false
  mac_address   = "BC:24:11:50:5F:83"
  datastore_id  = "storage.rachuna-net.pl"

  template = {
    node_name = "pve-s1"
    vm_id     = 901
    full      = true
  }

  cpu = {
    cores   = 4
    sockets = 2
  }

  memory = {
    dedicated = 8192
  }

  user_account = {
    username       = data.vault_kv_secret_v2.auth_techuser.data["username"]
    password       = data.vault_kv_secret_v2.auth_techuser.data["password"]
    public_ssh_key = data.vault_kv_secret_v2.auth_techuser.data["public_ssh_key"]
  }

  vault = {
    mount = "kv-gitlab"
    path  = "pl.rachuna-net/infrastructure/opentofu/iac-proxmox/machine/vm01017"
  }
}

• source = "git@gitlab.rachuna-net.pl:pl.rachuna-net/infrastructure/opentofu/modules/proxmox-vm.git?ref=v1.0.0" - Źródło modułu.
• hostname – pełna nazwa FQDN VM.
• description – krótki opis roli serwera (widzoczny w Proxmox).
• node_name – węzeł Proxmox, na którym VM ma być tworzona (pve-s1, pve-s2, pve-s3, …).
• vm_id – unikalny ID VM w klastrze (sprawdź, czy numer nie jest zajęty).
• pool_id – pula Proxmox (np. kubernetes), ustaw zgodnie z przeznaczeniem.
• protection – zwykle true dla ochrony przed przypadkowym usunięciem.
• tags – lista tagów (rola, system, np. ["kubernetes", "master", "ubuntu"]).
• is_dmz – true/false zależnie od strefy sieci.
• mac_address – statyczny MAC (zapewnij unikalność w sieci).
• datastore_id – magazyn na dyski (obecnie storage.rachuna-net.pl jak w istniejących VM).

2.1. Sekcje template, cpu, memory

• template – wskaż template VM (aktualnie wykorzystywany jest vm_id = 901 na pve-s1 z kopią pełną: full = true).
• cpu – ustaw liczbę rdzeni (cores) i gniazd (sockets).
• memory – dedicated w MB (np. 8192).

2.2. Dostępy i sekrety

• user_account pobiera dane użytkownika technicznego z Vault: data.vault_kv_secret_v2.auth_techuser.data[...] – upewnij się, że wpis istnieje (definicja w machines/_data.tf).
• vault – ustaw ścieżkę na sekrety specyficzne dla VM, zgodnie z konwencją pl.rachuna-net/infrastructure/opentofu/iac-proxmox/machine/vmNNNNN (zaktualizuj numer).

3. Integracja z Vault

Jeżeli dane dostępowe pochodzą z Vault, zamiast jawnych wartości:

user_account = {
  username       = data.vault_kv_secret_v2.ct.data["username"]
  password       = data.vault_kv_secret_v2.ct.data["password"]
  public_ssh_key = data.vault_kv_secret_v2.ct.data["ssh_key"]
}

✅ Pozwala to:

• usunąć hasła z repozytorium,
• rotować dane dostępowe,
• centralnie kontrolować dostęp.