# FAQ: jak pracujemy z infrastrukturą

Praktyczne odpowiedzi: jak dodać maszynę, zasób albo playbook i jak zmienić maszynę, która już działa. Przygotowanie narzędzi i zmienne środowiskowe: [Konfiguracja Terraform i Ansible](<https://docs.logintegra.com/logintegra-ansible/setup/index.md>).

## 1\. Zasada: maszyny z IaC są niezmienne

Maszyna utworzona przez Terraform (tag `managed-by-terraform`) jest **w całości opisana w tym repozytorium**. Nie naprawiamy jej ręcznie - zmieniamy kod i wdrażamy go ponownie. Wszystko, co zrobisz na maszynie po SSH, a czego nie ma w repo, zniknie przy jej odtworzeniu - i nikt nie będzie wiedział, że było potrzebne.

| Warstwa | Co ją opisuje | Jak się zmienia |
| --- | --- | --- |
| zasób w chmurze: typ, dysk, IP, tagi, security group | `terraform/environments/<env>/<env>.tfvars` | PR -\> `terraform plan` -\> akceptacja -\> `apply` |
| konfiguracja hosta: konta, pakiety, Docker, Tomcat, porty SSH | role w `ansible/roles/`, dane w `ansible/inventory/group_vars/` | PR -\> `site.yml --check --diff` -\> `site.yml` |
| aplikacja: WAR, stos apollo-docker | TeamCity | build w TeamCity - **nie** Ansible, **nie** Terraform |

Dwie konsekwencje:

- Małą zmianę, np. nowego użytkownika, port, pakiet albo opcję JVM, robimy w roli albo w `group_vars` i uruchamiamy `site.yml`. Maszyna zostaje, Ansible doprowadza ją do stanu z repo. Każda rola jest idempotentna: drugie uruchomienie = zero zmian.
- Przy dużej zmianie **odtwarzamy maszynę** według sekcji 4. Duża zmiana to np. nowa wersja Ubuntu, inny typ dysku albo sytuacja, w której coś się rozjechało i nie wiadomo co.

> [!NOTE]
>
> **Wyjątki - czego repo świadomie nie opisuje**
>
> | Wyjątek | Dlaczego |
> | --- | --- |
> | stan zasilania | włączanie i wyłączanie należy do harmonogramów i TeamCity. Terraform ignoruje `state`, więc wyłączona maszyna nie jest dryfem. |
> | dane aplikacji | bazy, dumpy, dane testerów, `.env.local` i `config/` apollo-docker żyją tylko na maszynie. Przed odtworzeniem trzeba je zabezpieczyć, patrz sekcja 4. |
> | maszyny sprzed IaC | maszyn bez taga `managed-by-terraform` nie importujemy, tylko je [zastępujemy](<https://docs.logintegra.com/logintegra-ansible/devops-process/index.md#zastepowanie-istniejacych-maszyn>). |

## 2\. Jak dodać nową maszynę?

Nowa maszyna to wpis w `<env>.tfvars`. Rodzaj maszyny wybiera środowisko:

| Chcę | Środowisko | Mapa w `tfvars` | Archetyp |
| --- | --- | --- | --- |
| środowisko dla zespołu testerów / staging klienta (np. apollo-docker) | `test` | `docker_nodes` | `docker-node` |
| odpowiednik serwera produkcyjnego: Tomcat i WAR z TeamCity | `qa` | `tomcat_nodes` | `tomcat-node` |
| środowisko produkcyjne | `prod` | TODO | TODO |

1. Branch `DEV-XXXX`, wpis w `terraform/environments/test/test.tfvars`:

   ```
   docker_nodes = {
     "test-apollo-wombaty-docker-01" = {
       type          = "GP1-XS"
       extra_tags    = ["wombaty"]                        # odbiorca - też jako tag
       schedule_tags = ["stoppable", "stop-at-end-of-day"]
       # apollo_docker = true (domyślnie w test), root_volume_gb = 80
     }
   }
   ```
2. `terraform plan -var-file=test.tfvars` - spodziewany wynik: 2 zasoby do dodania (flexible IP, serwer). PR z planem, akceptacja drugiej osoby, `apply`.
3. Konfiguracja hosta:

   ```
   cd ansible
   ansible-playbook -i inventory/test_scw.yml -l test-apollo-wombaty-docker-01 playbooks/state/site.yml
   ```
4. TeamCity: wpis w `AppName.kt` i `ServerConstants.kt`. Jak pozbyć się tego kroku, opisuje [plan dla TeamCity](<https://docs.logintegra.com/logintegra-ansible/teamcity-dynamic-targets/index.md>).

1. Branch `DEV-XXXX`, wpis w `terraform/environments/qa/qa.tfvars`:

   ```
   tomcat_nodes = {
     "qa-apollo-weglokoks-tomcat-01" = {
       type          = "PRO2-S"
       extra_tags    = ["weglokoks"]
       schedule_tags = ["stoppable"]
     }
   }
   ```
2. `terraform plan -var-file=qa.tfvars` -\> PR -\> akceptacja -\> `apply`.
3. `ansible-playbook -i inventory/qa_scw.yml -l qa-apollo-weglokoks-tomcat-01 playbooks/state/site.yml`
4. TeamCity: `ServerConfig` z `tomcatPath = /opt/tomcat/current`, użytkownik `teamcity`, port 666 - jak `APOLLO_PROD` ([szczegóły](<https://docs.logintegra.com/logintegra-ansible/tomcat-node/index.md>)).

**Nazwa** wg konwencji `<env>-apollo-[<odbiorca>-]<rola>-<lp>` - Terraform ją waliduje. Nazwy nigdy nie parsujemy; do celowania służą tagi (`-l tag_wombaty`).

**Tagi** dokłada archetyp: środowisko (`test`/`qa`), rola (`docker`, `apollo-docker`, `tomcat`) i `managed-by-terraform`. Przez `extra_tags` dodajesz odbiorcę, przez `schedule_tags` harmonogram zasilania (`stoppable`, `stop-at-end-of-day`, `weekends-off`).

## 3\. Jak zmienić działającą maszynę?

| Zmiana | Gdzie | Jak wdrożyć | Co się stanie z maszyną |
| --- | --- | --- | --- |
| konto użytkownika / klucz SSH | `group_vars/all.yml` -\> `users_accounts` | `site.yml` | nic poza zmianą kont |
| usunięcie konta | przenieść nazwę do `users_absent` (nie kasować wpisu) | `site.yml` | konto usunięte |
| klucze agentów TeamCity | `group_vars/all.yml` -\> `teamcity_access_authorized_keys` | `site.yml` |  |
| opcje JVM, wersja Tomcata | `tomcat_*` w `group_vars/tag_tomcat.yml` (utworzyć) albo `host_vars/` | `site.yml` | **restart Tomcata** |
| konfiguracja Dockera (`daemon.json`) | `docker_host_*` w `group_vars` | `site.yml` | **restart Dockera = restart kontenerów** |
| otwarcie portu | `inbound_rules.<rola>` w `<env>.tfvars` | `terraform apply` | bez restartu; dotyczy wszystkich maszyn tej roli |
| tag odbiorcy, harmonogram zasilania | `extra_tags` / `schedule_tags` w `<env>.tfvars` | `terraform apply` | bez restartu; zmienia grupy Ansible i harmonogram |
| typ instancji (więcej CPU/RAM) | `type` w `<env>.tfvars` | `terraform apply` | **wyłączenie i ponowne uruchomienie** - zaplanować okno |
| rozmiar dysku | `root_volume_gb` w `<env>.tfvars` | `terraform apply` | przeczytać `plan`: `~` = w miejscu, `-/+` = odtworzenie |
| wersja Ubuntu / świeży obraz | \- | odtworzenie (sekcja 4) | nowa maszyna |
| włączenie / wyłączenie | \- | TeamCity albo `scw instance server start` / `stop` | Terraform tego nie widzi i nie cofa |

Zmiany w Ansible zawsze najpierw z `--check --diff`:

```
cd ansible
ansible-playbook -i inventory/test_scw.yml -l <maszyna> playbooks/state/site.yml --check --diff
```

**Jak czytać `terraform plan`:**

| Znak | Znaczenie | Co robić |
| --- | --- | --- |
| `+` | nowy zasób | sprawdzić nazwę i tagi |
| `~` | zmiana w miejscu | sprawdzić, czy nie wymaga restartu |
| `-/+` | **usunięcie i utworzenie od nowa** | zatrzymać się i sprawdzić przyczynę. Pole wskazuje `# forces replacement` w planie. Dane z maszyny znikną. |
| `-` | usunięcie | upewnić się, że to zamierzone |

## 4\. Jak odtworzyć albo usunąć maszynę?

**Odtworzenie** przydaje się przy świeżym obrazie, podejrzeniu dryfu albo nowej wersji Ubuntu. Moduł `instance` ignoruje zmianę obrazu, żeby każdy nowy build Ubuntu nie wymuszał odtworzenia - dlatego odtworzenie zlecamy wprost:

```
cd terraform/environments/test
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
cd ../../../ansible
ansible-playbook -i inventory/test_scw.yml -l test-apollo-wombaty-docker-01 playbooks/state/site.yml
```

Flexible IP to osobny zasób - odtwarzany jest tylko serwer, **adres IP zostaje**. Nazwa też, więc TeamCity nie wymaga zmian. Dla hosta Tomcata adres zasobu to `module.tomcat_node["<nazwa>"]...`.

**Przed odtworzeniem** zabezpiecz to, czego repo nie opisuje (sekcja 1, wyjątki): na hoście apollo-docker `.env.local`, `config/`, dumpy i dane testerów; na hoście Tomcata - nic, WAR wgra TeamCity. Po odtworzeniu: deploy z TeamCity.

**Usunięcie:** usuń wpis z `<env>.tfvars` -\> `plan` pokaże `-` dla serwera i IP -\> PR -\> `apply`. Potem wpis w TeamCity i monitoringu.

## 5\. Jak dodać nowy zasób?

**Nowa reguła w security group** - wpis w `inbound_rules.<rola>` w `<env>.tfvars`, ze źródłem z mapy `sources` (np. `vpn`, `teamcity_agent`):

```
{ port = 9000, source = "vpn" },   # zawsze z komentarzem: po co i dla kogo
```

Nowe źródło (np. kolejny agent) - wpis w `sources`, nie IP wklejone w regułę. W `test` nie da się otworzyć portu na cały internet - walidacja to odrzuci.

**Nowy rodzaj zasobu**, np. baza, zarządzany Redis, bucket albo private network:

1. Moduł w `terraform/modules/<nazwa>/` - **bez konkretnych wartości** (nazw, IP, rozmiarów); wszystko przez zmienne. Pliki: `main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`.
2. Wywołanie w `terraform/environments/<env>/main.tf`, konkretne wartości w `<env>.tfvars`.
3. Nazwa wg tabeli "Pozostałe zasoby" w [Procesie DevOps](<https://docs.logintegra.com/logintegra-ansible/devops-process/index.md>), sekcja 4; tagi: środowisko + `managed-by-terraform`.
4. `terraform fmt -recursive`, `validate`, `plan` w PR.

**Nowa rola hosta** (np. `proxy-node`, `redis-node`) - pełna ścieżka, jak przy `docker-node` i `tomcat-node`:

- [ ] archetyp `terraform/modules/archetypes/<rola>-node/` - dokłada tag roli
- [ ] mapa `<rola>_nodes` z walidacją nazwy w `environments/<env>/variables.tf` i wywołanie w `main.tf`
- [ ] klucz `<rola>` w `inbound_rules` (osobna security group)
- [ ] rola(e) Ansible + `playbooks/state/<rola>-nodes.yml` z `hosts: tag_<rola>`, import w `site.yml`
- [ ] tag w tabeli tagów w sekcji 3 [Procesu DevOps](<https://docs.logintegra.com/logintegra-ansible/devops-process/index.md>)
- [ ] strona w `docs/` i wpis w `zensical.toml`

## 6\. Jak dodać playbook?

Najpierw jedno pytanie: **czy efekt ma przetrwać `terraform destroy` + `apply`?**

| Odpowiedź | To jest | Gdzie |
| --- | --- | --- |
| **tak**, np. konto, pakiet, reguła, cron, konfiguracja usługi | **stan** | rola w `ansible/roles/` + dane w `group_vars/` |
| **nie**, np. restart, pobranie logów, jednorazowa poprawka, akcja z TeamCity | **operacja** | playbook w `ansible/playbooks/` |

### Stan - nowa rola

1. `ansible/roles/<rzeczownik>/` - nazwa mówi, czym host ma być (`tomcat`, `docker_host`), nie co robi (`install_tomcat`).
2. `defaults/main.yml`: każda zmienna ma prefiks roli, czyli `<rola>_...`, co wymusza `ansible-lint`. Wartości domyślne są bezpieczne, najlepiej takie, przy których rola nic nie robi. **Bez danych** - dane w `group_vars`.
3. `tasks/main.yml`: idempotentnie - drugie uruchomienie = `changed=0`; bez `command`/`shell` tam, gdzie jest moduł.
4. `README.md` z tabelą zmiennych i tym, czego rola **nie** robi.
5. Podpięcie: `playbooks/state/<rola>-nodes.yml` (`hosts: tag_<tag>`) albo do istniejącego; import w `site.yml`.
6. Kontrola: `cd ansible && ansible-lint`, `--check --diff`, dwa uruchomienia (drugie bez zmian).

### Operacja - nowy playbook

1. `ansible/playbooks/<czasownik>-<co>.yml` - **płasko**, bez podkatalogów: TeamCity woła `/home/ansible/playbooks/<nazwa>.yml`.
2. `hosts: all` - zasięg wybiera wywołujący przez `-i inventory/<env>_scw.yml -l tag_<tag>`.
3. Jeśli operacja zmienia stan, który opisuje jakaś rola (np. konta) - czytaj **te same dane** co rola (`group_vars`), żeby się nie rozjechały.
4. Operacja na zasilaniu / API Scaleway nie potrzebuje SSH do maszyny: `gather_facts: false` i `delegate_to: localhost`.

## 7\. Częste pytania

> [!NOTE]
>
> **Zmieniłem coś ręcznie na maszynie. Co teraz?**
>
> Przenieś zmianę do repo (rola albo `group_vars`) i puść `site.yml --check --diff` - diff powinien być pusty. Jeśli tego nie zrobisz, zmiana zniknie przy odtworzeniu maszyny, a następna osoba nie będzie o niej wiedzieć.

> [!NOTE]
>
> **`terraform plan` chce odtworzyć maszynę (`-/+`), a nie chciałem.**
>
> Nie rób `apply`. W planie przy polu z `# forces replacement` jest przyczyna. Często da się ją zrobić inaczej, np. przy zmianie typu dysku. Jeśli odtworzenie jest zamierzone - postępuj jak w sekcji 4, najpierw zabezpieczając dane.

> [!NOTE]
>
> **Zmieniłem obraz, a `plan` nic nie pokazuje.**
>
> Celowo - moduł `instance` ignoruje `image`. Nowy obraz = odtworzenie przez `-replace` (sekcja 4).

> [!NOTE]
>
> **Wyłączyłem maszynę w konsoli - czy Terraform ją włączy?**
>
> Nie. Terraform ignoruje stan zasilania. Uwaga: wyłączona maszyna znika z inwentarza Ansible, bo wtyczka domyślnie pokazuje tylko `running`. `site.yml` jej więc nie skonfiguruje.

> [!NOTE]
>
> **Gdzie są sekrety?**
>
> W Vault. Lokalnie w `.envrc` (poza repo). W repo tylko wartości zaszyfrowane `ansible-vault` (np. `vault_apollo_docker_deploy_key`). Szczegóły: [Konfiguracja](<https://docs.logintegra.com/logintegra-ansible/setup/index.md>).

> [!NOTE]
>
> **Czym różni się `qa` od `test`?**
>
> `qa` to mirror produkcji: hosty Tomcata, WAR z TeamCity, projekt `apollo-qa` w WAW 1. `test` to środowiska testerów na hostach apollo-docker, z całym stosem na jednej maszynie, w projekcie `apollo-test` w WAW 2.

> [!NOTE]
>
> **Mam starą maszynę bez taga `managed-by-terraform`. Mogę ją dopisać do `tfvars`?**
>
> Nie - Terraform utworzy obok nową maszynę, a nazwy starych i tak nie przejdą walidacji. Stare maszyny zastępujemy ([procedura](<https://docs.logintegra.com/logintegra-ansible/devops-process/index.md#zastepowanie-istniejacych-maszyn>)).
