# 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](<https://docs.logintegra.com/logintegra-ansible/faq/index.md>). Instalacja i zmienne: [Konfiguracja](<https://docs.logintegra.com/logintegra-ansible/setup/index.md>).

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](<https://docs.logintegra.com/logintegra-ansible/setup/index.md#3-zmienne-srodowiskowe>)) |
| 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 |

> [!NOTE]
>
> **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`.

> [!CAUTION]
>
> **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](<https://docs.logintegra.com/logintegra-ansible/faq/index.md#4-jak-odtworzyc-albo-usunac-maszyne>)).

## 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](<https://docs.logintegra.com/logintegra-ansible/faq/index.md#4-jak-odtworzyc-albo-usunac-maszyne>).

## 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](<https://docs.logintegra.com/logintegra-ansible/faq/index.md#1-zasada-maszyny-z-iac-sa-niezmienne>)). 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.

> [!WARNING]
>
> **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](<https://docs.logintegra.com/logintegra-ansible/setup/index.md#3-zmienne-srodowiskowe>) |
| `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](<https://docs.logintegra.com/logintegra-ansible/devops-process/index.md>) sekcja 4 |
| plan pokazuje `-/+` dla maszyny | zmiana pola, którego nie da się zmienić w miejscu (`# forces replacement`) | nie wdrażać bez decyzji - [FAQ](<https://docs.logintegra.com/logintegra-ansible/faq/index.md#3-jak-zmienic-dziaajaca-maszyne>) |
