Terraform od środka

Terraform wygląda na prosty: piszesz pliki .tf, wpisujesz terraform apply i chmura się buduje. Kłopoty zaczynają się w dniu, w którym ktoś zmieni coś ręcznie w konsoli, zmienisz nazwę zasobu albo apply wywróci się w połowie. Wtedy liczy się nie to, jakie są komendy, tylko jak Terraform myśli: co porównuje z czym, gdzie to zapisuje i w jakiej kolejności woła API.

Przewodnik ma poziomy. Rozdziały i bloki mają oznaczenia — L1 podstawy, L2 praktyk, L3 ekspert. Głębokość wybierasz przełącznikiem w lewym dolnym rogu; głębszy materiał chowa się, dopóki go nie zechcesz. Mapa poniżej skacze w dowolne miejsce i odhacza przeczytane rozdziały.

Skrypt w bashu z aws ec2 run-instances jest imperatywny: mówi „utwórz maszynę”. Uruchom go dwa razy — masz dwie maszyny. Terraform jest deklaratywny: mówisz „mają istnieć dwie maszyny o takich parametrach”, a narzędzie liczy różnicę między tym celem a tym, co już istnieje, i wykonuje tylko tę różnicę.

Ta różnica to serce wszystkiego, co dalej. Żeby ją policzyć, Terraform musi znać trzy rzeczy: konfigurację (twoje pliki), state (swoją pamięć o tym, co już zbudował) i rzeczywistość (odpowiedzi API). Plan to wynik porównania tych trzech.

Konfiguracja to katalog plików .tf — tak zwany moduł główny (root module). Terraform czyta wszystkie pliki z katalogu naraz; kolejność plików i bloków nie ma znaczenia, bo zależności wynikają z referencji, nie z pozycji w tekście. Kliknij typ bloku:

terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 6.0" }
  }
  backend "s3" { bucket = "tf-state", key = "app.tfstate", region = "eu-central-1" }
}
provider "aws" { region = "eu-central-1" }
variable "env" { type = string, default = "dev" }
locals { name = "app-${var.env}" }
data "aws_ami" "ubuntu" { most_recent = true, owners = ["099720109477"] }
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
  tags          = { Name = local.name }
}
output "ip" { value = aws_instance.web.public_ip }

Terraform dzieli się na dwie części: Terraform Core i pluginy (providery). Core czyta konfigurację, trzyma state, buduje graf i plan. Nie wie nic o EC2 ani o sieciach Azure. Tę wiedzę ma provider — osobny program, z którym Core rozmawia przez RPC. Protokół wtyczek jest wersjonowany i zaimplementowany w Protocol Buffers i gRPC.

terraform init czyta required_providers, pobiera pasujące wersje (zwykle z Terraform Registry) do podkatalogu .terraform i zapisuje wybór w pliku .terraform.lock.hcl. Kolejne init wybiorą tę samą wersję, nawet jeśli wyszła nowsza — chyba że dodasz -upgrade.

Każdy zasób ma adres: aws_instance.web. Pierwsza część to typ zasobu (prefiks aws_ wskazuje providera), druga to nazwa lokalna, którą nadajesz ty. Z count albo for_each dochodzi indeks lub klucz instancji, a w module — prefiks module.nazwa. Adres to tożsamość w świecie Terraform: zmienisz adres — zmienisz tożsamość (rozdział o state pokaże, czym to grozi).

Gdy w argumencie piszesz data.aws_ami.ubuntu.id, tworzysz referencję. Referencje robią dwie rzeczy: podstawiają wartość i rysują krawędź w grafie zależności.

Po apply Terraform zapisuje plik state (lokalnie terraform.tfstate, w JSON). Jego główne zadanie to mapowanie: zasób aws_instance.web z konfiguracji to obiekt o ID i-abcd1234 w chmurze. Dodatkowo state przechowuje metadane (np. zależności, żeby wiedzieć, w jakiej kolejności usuwać zasób, którego nie ma już w kodzie) i cache wartości atrybutów.

Teraz widać odpowiedź na pytanie z początku: gdy usuniesz blok z kodu, adres dalej jest w state. Adres w state bez odpowiednika w konfiguracji = do usunięcia.

Ktoś zmienił tag w konsoli. To drift: rzeczywistość rozjechała się z tym, co mówi kod. Domyślnie terraform plan najpierw odświeża state — czyta aktualne ustawienia obiektów z API — a potem porównuje je z konfiguracją. Wynik: plan, który przywraca wartość z kodu.

Jeśli zmiana ręczna jest właściwa, masz dwie drogi: przepisać ją do kodu albo — gdy chcesz tylko zaktualizować state bez dotykania chmury — użyć trybu terraform plan -refresh-only / apply -refresh-only. Stara komenda terraform refresh robi to samo, ale jest przestarzała (deprecated).

Backend decyduje, gdzie leży state: lokalny plik, bucket S3, kontener Azure Storage (azurerm), bucket GCS (gcs) i inne. Konfigurujesz go w bloku terraform { backend "…" {} }, a terraform init go inicjalizuje. HCP Terraform konfiguruje się osobnym blokiem cloud, zamiast backend.

Jeśli backend obsługuje blokady, Terraform blokuje state przy każdej operacji, która może go zapisać — automatycznie. Gdy blokada się nie uda, Terraform nie kontynuuje. W backendzie S3 blokadę włączasz argumentem use_lockfile = true (domyślnie false); starsza blokada przez tabelę DynamoDB (dynamodb_table) jest oznaczona jako przestarzała.

Trzy bloki w kodzie pozwalają przerabiać state przez zwykły plan i apply — z podglądem i code review — zamiast ręcznych komend:

State zawiera wartości atrybutów — także hasła do baz i tokeny. Lokalnie to zwykły plik tekstowy. sensitive = true na zmiennej lub outputcie tylko redaguje wartość w wyjściu plan/apply; w state wartość dalej jest. Co więcej, terraform output -json i -raw pokazują wartości wrażliwe otwartym tekstem.

Żeby sekret w ogóle nie trafił do state ani do pliku planu, są dwa nowsze narzędzia: argumenty write-only (np. password_wo w aws_db_instance) i zasoby ephemeral (blok ephemeral), których wartości żyją tylko w trakcie operacji.

terraform init przygotowuje katalog: backend, providery, moduły. terraform plan buduje plan wykonania: odświeża state, porównuje z konfiguracją i wypisuje akcje. terraform apply bez argumentu sam tworzy nowy plan, pyta o zgodę i go wykonuje. W CI lepszy jest tryb dwuetapowy: plan -out=tfplan, review, potem apply tfplan — zapisany plan wykonuje się bez pytania.

Zapisany plan pamięta, z jakiego state powstał (numer serial i lineage). Jeśli w międzyczasie inny apply zmienił state, Terraform odrzuci plan błędem Saved plan is stale.

Z referencji Terraform buduje graf skierowany: krawędź od zasobu do zasobu, od którego zależy. Graf musi być bez cykli. Potem go „przechodzi” równolegle: węzeł startuje, gdy skończą się wszystkie jego zależności. Liczbę równoczesnych operacji ogranicza -parallelism (domyślnie 10).

Usuwanie idzie w odwrotnej kolejności: najpierw maszyna, potem podsieć, na końcu VPC. Gdy zależność nie wynika z żadnej referencji (np. aplikacja potrzebuje uprawnienia IAM, którego nie widać w argumentach), dopisujesz depends_on — ale tylko w ostateczności, bo robi plany bardziej zachowawczymi.

Dla każdego zasobu plan wybiera akcję: create (+), update in-place (~), destroy (-) albo replace (-/+: zniszcz i utwórz). Replace pojawia się, gdy zmieniasz argument, którego zdalne API nie potrafi zmienić na żywym obiekcie. Tę wiedzę ma provider: w jego schemacie atrybut jest oznaczony jako wymagający zastąpienia (w Plugin Framework: plan modifier RequiresReplace). Plan pokazuje wtedy dopisek # forces replacement.

Domyślnie replace to „najpierw zniszcz, potem utwórz” — przez chwilę obiektu nie ma. Blok lifecycle zmienia to zachowanie:

Oba tworzą wiele instancji z jednego bloku. count numeruje je [0], [1]…, for_each nadaje klucze z mapy lub zbioru: ["a"], ["b"]. Dokumentacja radzi: count dla niemal identycznych instancji, for_each, gdy argumenty różnią się wartościami, których nie da się wyprowadzić z liczby całkowitej. Różnica wychodzi przy usuwaniu elementu ze środka listy:

Moduł to katalog plików .tf. Moduł główny wywołuje inne blokiem module "net" { source = "./modules/network" … }. Źródłem może być katalog lokalny, Registry albo repozytorium Git. Zasoby modułu dostają adresy z prefiksem module.net., a wartości wychodzą na zewnątrz tylko przez output.

Każdy typ zasobu w providerze to schemat (jakie argumenty i atrybuty, które są wymagane, które wymuszają replace) oraz implementacja operacji Create, Read, Update, Delete. Core decyduje co zrobić (akcja z planu), provider jak: tłumaczy argumenty na żądania do API konkretnej chmury i zapisuje odpowiedź jako atrybuty w state.

Dlatego abstrakcja Terraform kończy się na poziomie cyklu życia: create, read, update, delete, import. Same zasoby nie są abstrakcyjne — aws_vpc ma argumenty EC2, a azurerm_virtual_network argumenty ARM.

Częsty mit: „napiszę kod raz i przeniosę między chmurami”. Terraform daje wspólny język i workflow, ale nie wspólny model zasobów. Sieć w AWS jest regionalna, w Google Cloud globalna (podsieci są regionalne), a w Azure każdy zasób musi leżeć w grupie zasobów. Kod trzeba napisać osobno dla każdej chmury.

Blok provider ustawia region, konto i uwierzytelnienie. Sekretów nie wpisuj w kod — providery czytają standardowe źródła poświadczeń chmury (zmienne środowiskowe, profile, tożsamość maszyny/CI). Gdy potrzebujesz dwóch regionów albo dwóch kont, tworzysz drugą konfigurację z argumentem alias i wskazujesz ją w zasobie przez provider = aws.eu.

provider "aws" { region = "us-east-1" }
provider "aws" {
  alias  = "eu"
  region = "eu-central-1"
}

Chmury to systemy rozproszone. Wiele API jest ostatecznie spójnych: obiekt utworzony przed chwilą może przez moment nie być widoczny dla innego wywołania. Terraform Core tego nie rozwiązuje — robią to providery: ponawiają żądania, czekają na stan „gotowy” i mają limity czasu. Część zasobów pozwala zmienić te limity zagnieżdżonym blokiem timeouts { create = "60m" }.

Gdy apply trafi na błąd, Terraform loguje błąd, zapisuje w state zmiany, które już się udały, zdejmuje blokadę i kończy. Nie cofa automatycznie częściowo wykonanego apply. Infrastruktura może zostać w stanie pośrednim; poprawiasz kod (albo przyczynę) i uruchamiasz apply ponownie — plan dokończy resztę.

CloudFormation to natywne IaC AWS. Szablon (JSON/YAML) opisuje zasoby; z szablonu powstaje stos (stack), którego stan trzyma usługa AWS — nie masz pliku state ani backendu. Odpowiednikiem planu jest change set: pokazuje, co się zmieni (także czy zasób zostanie usunięty lub zastąpiony), a zmiany wchodzą dopiero po jego wykonaniu.

Przy niepowodzeniu operacji stos można wycofać do ostatniego stabilnego stanu albo — opcją „Preserve successfully provisioned resources” — zachować udane zasoby i ponowić. Drift wykrywa osobna operacja drift detection; zasoby, które jej nie wspierają, dostają status NOT_CHECKED.

Bicep to język kompilowany do szablonów ARM. Nie ma plików state: Azure Resource Manager przechowuje stan zasobów, a wdrożenie jest idempotentne. Podgląd zmian daje operacja what-if. Domyślny tryb wdrożenia to incremental: zasoby w grupie, których nie ma w szablonie, zostają nietknięte. Tryb complete by je usunął, ale Microsoft go stopniowo wycofuje i do usuwania poleca deployment stacks.

Różnica w myśleniu: Terraform usuwa to, co zna ze state, a czego nie ma w kodzie. ARM w trybie incremental niczego nie usuwa; dopiero deployment stack śledzi „swoje” zasoby i może je usunąć lub odłączyć, a także zablokować zmiany spoza stosu (denySettings).

Google Cloud Deployment Manager osiągnął koniec wsparcia 31 marca 2026 r.; Google każe migrować do Infrastructure Manager. Infra Manager to zarządzana usługa, która wdraża konfiguracje Terraform (z Cloud Storage, repozytorium Git lub katalogu lokalnego). Natywne IaC w Google Cloud to więc Terraform uruchamiany przez Google, a nie osobny język.

OpenTofu powstał w 2023 r. jako fork Terraform, po tym jak HashiCorp zmienił licencję swoich produktów na Business Source License (BSL). Projekt trafił pod skrzydła Linux Foundation i dąży do zgodności z konfiguracjami Terraform — większość kodu działa bez zmian, ale funkcje dodane po rozejściu się projektów mogą się różnić.

Ściąga