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
*.tfstatei*.tfplansą w.gitignore. - Nie zmieniamy w konsoli Scaleway zasobów z tagiem
managed-by-terraform. Następnyapplycofnie 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)¶
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:
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:
- Kopia:
terraform state pull > backup-$(date +%F).tfstate. Bucket i tak trzyma wszystkie wersje, a lokalna kopia tylko przyspiesza powrót. - Lista zasobów środowiska w Scaleway - tylko nasze, po tagach:
Dla
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-2qa:zone=pl-waw-1i projekt zproject_idwqa.tfvars. - Usunięcie tych zasobów w konsoli albo
scw- najpierw serwery, potem IP i security groups. - Wyczyszczenie state:
planpokaż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¶
- Nie uruchamiaj
apply. Przy pustym state Terraform uzna, że nic nie istnieje, i utworzy wszystko jeszcze raz. - 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.
- 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
applynaraz na środowisko - uprzedzić na kanale zespołu, applytylko z pliku planu (sekcja 4),- docelowo
applywyłącznie z TeamCity (faza F), jeden build na środowisko.
plan i state list/show są bezpieczne równolegle.
11. Jak podnieść wersję providera?¶
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ń:
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:
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