Przejdź do treści

FAQ: praca z Terraformem

Codzienne operacje na Terraformie i jego state: podgląd, dryf, odtworzenie, zmiana nazwy, usuwanie i start od zera. Ogólne zasady, np. niezmienne maszyny i dodawanie maszyn, opisuje FAQ: jak pracujemy. Instalacja i zmienne: Konfiguracja.

Wszystkie polecenia uruchamiamy w katalogu środowiska:

cd terraform/environments/test     # albo qa
terraform init                     # raz, i po każdej zmianie providerów lub backendu

1. Gdzie jest state i jak to działa?

gdzie Scaleway Object Storage, bucket apollo-terraform-state (pl-waw)
klucz <env>/terraform.tfstate - qa/terraform.tfstate, test/terraform.tfstate
jeden katalog = jeden state = jedno środowisko = jeden projekt Scaleway
dostęp AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY = klucze Scaleway (zmienne)
wersjonowanie włączone - każdy zapis state zostawia poprzednią wersję (sekcja 9)
Object Lock włączony - wersje state nie dają się usunąć ani nadpisać przed końcem retencji
blokada state (lock) brak - Object Lock to nie jest blokada state, patrz sekcja 10

Wersjonowanie + Object Lock w praktyce

Historia state jest kompletna i chroniona. Każde apply, state rm i state push tworzy nową wersję obiektu, a poprzednie zostają. Usunięcie obiektu tworzy tylko znacznik usunięcia, czyli delete marker, a wersje pod nim zostają.

Zablokowanych wersji nie da się skasować do końca okresu retencji. Nie zrobi tego Terraform ani konsola, a w trybie COMPLIANCE nawet administrator. To ochrona przed pomyłką i przed kimś z wykradzionym kluczem.

Koszt rośnie z liczbą zapisów, bo stare wersje zajmują miejsce do końca retencji. State ma kilkadziesiąt KB, więc to pomijalne.

State to mapa "zasób w kodzie -> zasób w chmurze (ID)". Terraform porównuje z nim kod i chmurę przy każdym plan.

Czego nie robimy nigdy

  • Nie edytujemy pliku state ręcznie, tylko poleceniami terraform state ....
  • Nie commitujemy state ani planów, bo mogą zawierać sekrety. Pliki *.tfstate i *.tfplan są w .gitignore.
  • Nie zmieniamy w konsoli Scaleway zasobów z tagiem managed-by-terraform. Następny apply cofnie zmianę albo, co gorsza, odtworzy zasób.

2. Jak sprawdzić, co jest w state?

terraform state list                       # wszystkie zasoby w state
terraform state list module.docker_node    # tylko hosty dockerowe
terraform state show 'module.docker_node["test-apollo-wombaty-docker-01"].module.instance.scaleway_instance_server.this'
terraform output                           # np. docker_nodes = { nazwa = IP }
terraform output -json docker_nodes        # do skryptów
terraform show                             # cały state czytelnie (długie)

Adresy zasobów, które się przydają:

Co Adres
serwer hosta dockerowego module.docker_node["<nazwa>"].module.instance.scaleway_instance_server.this
jego flexible IP module.docker_node["<nazwa>"].module.instance.scaleway_instance_ip.this[0]
serwer hosta Tomcata module.tomcat_node["<nazwa>"].module.instance.scaleway_instance_server.this
security group roli module.sg["<rola>"].scaleway_instance_security_group.this

Adres zawsze w pojedynczych cudzysłowach - inaczej shell zje [ i ".

3. Czy chmura zgadza się z kodem? (dryf)

terraform plan -var-file=test.tfvars

No changes. = kod, state i chmura są zgodne. Każda inna odpowiedź to albo niezatwierdzona zmiana w kodzie, albo dryf - ktoś zmienił zasób poza Terraformem.

Samo odświeżenie, bez planowania zmian w chmurze:

terraform plan -refresh-only -var-file=test.tfvars

Do automatycznej kontroli, np. w nocnym buildzie TeamCity:

terraform plan -detailed-exitcode -var-file=test.tfvars
# 0 = brak zmian, 2 = są zmiany (dryf albo niewdrożony kod), 1 = błąd

Co zrobić z dryfem:

Sytuacja Działanie
zmiana w konsoli była pomyłką apply - Terraform przywróci stan z kodu
zmiana w konsoli była potrzebna przenieść ją do <env>.tfvars (PR), potem plan = brak zmian
zasób usunięty w konsoli plan pokaże + - apply odtworzy go z kodu

Świadomie nie jest dryfem: stan zasilania, obraz, cloud-init - moduł instance je ignoruje (dlaczego).

4. Jak bezpiecznie wdrożyć zmianę?

Zawsze przez zapisany plan - wdrażamy dokładnie to, co ktoś przejrzał:

terraform plan -var-file=test.tfvars -out=test.tfplan
terraform show test.tfplan         # to wklejamy/opisujemy w PR
terraform apply test.tfplan        # po akceptacji drugiej osoby

apply bez pliku planu liczy plan od nowa - jeśli ktoś w międzyczasie coś zmienił, wdrożysz coś innego niż przejrzane.

5. Jak odtworzyć jeden zasób?

terraform plan -var-file=test.tfvars -out=replace.tfplan \
  -replace='module.docker_node["test-apollo-wombaty-docker-01"].module.instance.scaleway_instance_server.this'
terraform apply replace.tfplan

IP to osobny zasób - zostaje. Dane z maszyny znikają; co zabezpieczyć i co zrobić potem: FAQ, sekcja 4.

6. Jak zmienić nazwę maszyny bez jej odtwarzania?

Nazwa maszyny jest kluczem w mapie docker_nodes / tomcat_nodes. Sama zmiana klucza w tfvars to dla Terraforma usunięcie starej maszyny i utworzenie nowej. Żeby zachować maszynę, dopisz blok moved w environments/<env>/main.tf:

moved {
  from = module.docker_node["test-apollo-wombaty-docker-01"]
  to   = module.docker_node["test-apollo-wombaty-docker-02"]
}

Zmień klucz w tfvars, uruchom plan: zamiast -/+ powinna być zmiana nazwy w miejscu (~ name). Po apply blok moved można usunąć. Nowa nazwa to też nowa nazwa w inwentarzu Ansible i we wpisie TeamCity.

To samo przy przenoszeniu zasobu między modułami (refaktoryzacja kodu) - moved zamiast usuwania i tworzenia od nowa.

7. Jak usunąć zasób?

Usunąć z chmury (normalna ścieżka): usuń wpis z <env>.tfvars -> plan pokaże - -> PR -> apply.

Usunąć tylko z state i zostawić w chmurze. Terraform przestaje wtedy zarządzać zasobem, np. maszyną przekazaną poza IaC:

terraform state pull > backup-$(date +%F).tfstate    # kopia (bucket i tak trzyma wersje)
terraform state rm 'module.docker_node["test-apollo-wombaty-docker-01"]'

Potem usuń wpis z tfvars w tym samym PR - inaczej następny apply utworzy maszynę od nowa, obok tej zostawionej. Zasób nadal kosztuje, zdejmij z niego tag managed-by-terraform.

8. Jak zacząć od zera?

Wariant A: zniszczyć środowisko i zbudować ponownie. State zostaje, tylko pusty:

terraform plan -destroy -var-file=test.tfvars -out=destroy.tfplan
terraform show destroy.tfplan          # przejrzeć: tylko to środowisko, nic więcej
terraform apply destroy.tfplan
terraform plan -var-file=test.tfvars -out=test.tfplan && terraform apply test.tfplan

Na test zniszczy wszystkie środowiska testerów razem z ich danymi - uzgodnić z zespołami. Na qa to dokładnie kryterium fazy D: destroy + apply odtwarza QA.

Wariant B: wyczyścić state, a zasoby usunąć ręcznie. Przydaje się, gdy state jest bezużyteczny, a destroy nie działa:

  1. Kopia: terraform state pull > backup-$(date +%F).tfstate. Bucket i tak trzyma wszystkie wersje, a lokalna kopia tylko przyspiesza powrót.
  2. Lista zasobów środowiska w Scaleway - tylko nasze, po tagach:
    scw instance server list tags.0=managed-by-terraform zone=pl-waw-2 -o human
    scw instance ip list zone=pl-waw-2
    scw instance security-group list zone=pl-waw-2
    
    Dla qa: zone=pl-waw-1 i projekt z project_id w qa.tfvars.
  3. Usunięcie tych zasobów w konsoli albo scw - najpierw serwery, potem IP i security groups.
  4. Wyczyszczenie state:
    terraform state list | xargs -r -I{} terraform state rm '{}'
    terraform state list        # pusto
    
  5. plan pokaże same + - PR, apply.

Kolejność kroków 3 i 4 jest ważna. Przy pustym state i istniejących zasobach apply utworzy drugi komplet obok, bo Scaleway dopuszcza powtórzone nazwy.

Nie importujemy (terraform import) - odbudowa z kodu jest zgodna z zasadą niezmiennych maszyn (FAQ). Wyjątek do rozważenia tylko awaryjnie, gdy chodzi o produkcję.

9. State zgubiony albo uszkodzony

  1. Nie uruchamiaj apply. Przy pustym state Terraform uzna, że nic nie istnieje, i utworzy wszystko jeszcze raz.
  2. Przywróć poprzednią wersję z bucketu. Wersjonowanie jest włączone, a Object Lock gwarantuje, że wersje z okresu retencji istnieją. Szukamy ostatniej wersji sprzed awarii po dacie modyfikacji i rozmiarze. Pusty state ma kilkaset bajtów.
  3. Jeśli żadna wersja nie jest dobra: wariant B z sekcji 8.

Wersje w konsoli: Object Storage -> apollo-terraform-state -> <env>/ -> terraform.tfstate -> zakładka wersji -> pobranie wybranej.

Wersje z CLI. Wystarczy dowolny klient S3, np. aws, z tymi samymi kluczami co backend:

aws s3api list-object-versions --bucket apollo-terraform-state \
  --prefix test/terraform.tfstate --endpoint-url https://s3.pl-waw.scw.cloud \
  --query 'Versions[].[VersionId,LastModified,Size]' --output table

aws s3api get-object --bucket apollo-terraform-state --key test/terraform.tfstate \
  --version-id <VersionId> restored.tfstate --endpoint-url https://s3.pl-waw.scw.cloud

Wgranie odzyskanej wersji:

terraform show restored.tfstate | head        # czy to właściwy state
terraform state push -force restored.tfstate  # -force: starsza wersja ma niższy serial
terraform plan -var-file=test.tfvars          # różnice = zmiany po tej wersji

state push tworzy nową wersję obiektu, a bieżąca, uszkodzona wersja zostaje w historii. Tę operację też da się więc cofnąć. Mimo to: tylko świadomie, z drugą osobą.

10. Czy dwie osoby mogą pracować jednocześnie?

Nie. Backend nie ma skonfigurowanej blokady state (docs/devops-process.md, sekcja 6). Dwa równoczesne apply na tym samym środowisku nadpiszą sobie state.

Object Lock ≠ blokada state

Object Lock chroni zapisane wersje przed usunięciem. Nie zatrzymuje drugiego apply - oba zapiszą state, a ostatni wygra. Dzięki wersjonowaniu da się potem odzyskać wersję pierwszego (sekcja 9), ale zasoby utworzone przez "przegrany" apply znikną ze state i zostaną w chmurze.

Do czasu blokady:

  • jedno apply naraz na środowisko - uprzedzić na kanale zespołu,
  • apply tylko z pliku planu (sekcja 4),
  • docelowo apply wyłącznie z TeamCity (faza F), jeden build na środowisko.

plan i state list/show są bezpieczne równolegle.

11. Jak podnieść wersję providera?

terraform init -upgrade
terraform plan -var-file=test.tfvars    # czy nowa wersja nie zmienia zasobów

Zmieniony .terraform.lock.hcl commitujemy osobnym PR, dla obu środowisk - lock jest w każdym katalogu środowiska.

12. Jak sprawdzić zmianę bez dostępu do state?

Składnia i typy - bez poświadczeń:

terraform init -backend=false && terraform validate
terraform fmt -check -recursive ../..

Plan bez dostępu do bucketu przydaje się np. przy przeglądzie zmian w module. Lokalny backend ustawia plik override, a *_override.tf jest w .gitignore:

printf 'terraform {\n  backend "local" {}\n}\n' > backend_override.tf
terraform init -reconfigure
terraform plan -refresh=false -var-file=test.tfvars
rm backend_override.tf terraform.tfstate* && terraform init -reconfigure   # powrót do bucketu

Taki plan porównuje kod z pustym state - pokazuje wszystko jako +. Nadaje się do sprawdzenia nazw, tagów i reguł, nie do oceny zmian w działającym środowisku.

Wyrażenia i zmienne na żywo:

terraform console -var-file=test.tfvars
> local.inbound_rules["apollo_docker"]

13. Częste błędy

Błąd Przyczyna Rozwiązanie
Backend initialization required brak init w tym katalogu terraform init
Backend configuration changed zmiana w backend.tf od ostatniego init terraform init -reconfigure (ten sam state) albo -migrate-state (przeniesienie state)
Inconsistent dependency lock file ktoś podniósł provider terraform init
zapis state kończy się błędem o Content-MD5 / sumie kontrolnej (InvalidRequest) Object Lock z domyślną retencją wymaga sumy kontrolnej przy zapisie, a backend.tf ma skip_s3_checksum = true usunąć skip_s3_checksum z backend.tf obu środowisk i powtórzyć; do sprawdzenia przy pierwszym apply - wcześniej nic nie zapisywało state do tego bucketu
No valid credential sources found brak AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY zmienne
project_id: ID projektu ... (UUID) project_id = "TODO" w <env>.tfvars wpisać ID projektu
Invalid index przy var.sources[...] reguła wskazuje source, którego nie ma w sources dopisać źródło albo poprawić nazwę
Nazwa hosta w test: ... nazwa spoza konwencji konwencja sekcja 4
plan pokazuje -/+ dla maszyny zmiana pola, którego nie da się zmienić w miejscu (# forces replacement) nie wdrażać bez decyzji - FAQ

Ostatnia zmiana: 2026-09-28 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e