\[DRAFT\]

1. Cel i zakres

Serwery na Scaleway powstają dziś przez ręcznie klikanie w konsoli i UI. Wiedza o tym, dlaczego dany serwer wygląda tak, a nie inaczej, jest rozproszona między administratorami i nigdzie nie zapisana. Skutki, które widzimy:

- Brak jednego źródła prawdy. Żeby dowiedzieć się, jak skonfigurowany jest serwer i dlaczego, trzeba się na niego zalogować albo zapytać kolegi.
- Brak poglądu zmiany przed jej wykonaniem. Nie ma momentu, w którym inni administratorzy mogłyby zobaczyć i zaakceptować (lub zatrzymać) zmiany na serwerze
- Brak code review.
- Rozbieżności między środowiskami. Nasze serwery rozjeżdzają się w sposób, którego nikt nie śledzi
- Narastające śmieci. Stare obrazy, snapshoty, odpięte wolumeny i IP-ki ([PRZYKŁAD](<https://youtrack.logintegra.com/issue/DEV-2450/Przygotowanie-instancji-pod-testy-DEV-2371-mirror-prod#focus=Comments-78-185952.0-0>))

Docelowo każda zmiana infstastruktury będzie wiązać się z zadaniem DEV i PR-ki na Bitbucket. Przed każdym wdrożeniem \`terraform plan\` pokaże dokładnie, co się zmieni. Nikt nie wykonuj `apply` sam i będzie to wymagało akceptacji drugiej osoby. Serwery Prod i QA powstaną z tego samego modułu Terraforma i różnić się będą wyłącznie plikiem zmiennych. Pobocznym celem jest zebranie i usystematyzowanie wiedzy w jedno miejsce.

2. Repozytorium, gałęzie i code review infrastruktury

### Proponowany nowy układ repozytorium

```
logintegra-infra/
├── terraform/
│   ├── modules/                    # kod wielokrotnego użytku, bez wartości konkretnych
│   │   ├── network/                # VPC, private network, public gateway
│   │   ├── security-group/         # reguły scaleway
│   │   └── app-server/             # instancja + wolumeny + IP + tagi
│   └── environments/               # zmienne środowiskowe
│       ├── prod/{main.tf, backend.tf, prod.tfvars}
│       └── qa/{main.tf, backend.tf, qa.tfvars}
├── ansible/
│   ├── inventory/
│   ├── playbooks/
│   ├── roles/
│   ├── collections/requirements.yml
│   └── ansible.cfg
├── docs/
│   ├── devops-process.md          # ten dokument
│   └── logintegra-resources.md    # dokument z opisem naszych zasobów Scaleway
└── README.md
```

### Branche i commity

Konwencja: - Branch na zadanie: `DEV-XXXX` - Commity "conventional commits" ([LINK](<https://www.conventionalcommits.org/en/v1.0.0/>)) z numerem zadań i zakresem, np.: `feat(terraform): add qa environment module (DEV-XXXX)` `fix(ansible): fix bug x (DEV-XXXX)` - Zakres: `terraform`, `ansible`, `docs`, `script`, `teamcity` itp.

### Zasady pull requesta

TODO

3. Środowiska i tagi

### Dlaczego tagi są ważne

Nasze inventory Ansible są dynamiczne - pobierane z plugina scaleway i nie ma nigdzie listy hostów. Plugin `scaleway.scaleway.scaleway` pyta API Scaleway o instancje z określonymi tagami i buduje listę hostów "w locie". Na przykład:

```
# ansible/inventory/prod_inventory_scw.yml
plugin: scaleway.scaleway.scaleway
api_url: https://api.scaleway.com
hostnames:
  - hostname
zones:
  - pl-waw-1
  - pl-waw-2
tags:
  - prod
variables:
  ansible_host: public_ipv4
  host_status: state
  id: id
  tags: tags
  zone: zone
```

Konsekwencja, którą trzeba zapamiętać: - Tag jest kontraktem między Terraformem a Ansible.

Dlatego lista tagów musi mieć zamkniętą listę z walidacją.

### Lista tagów

**Do weryfikacji i zmiany**

| Tag | Znaczenie | Inwentarz, który go czyta |
| --- | --- | --- |
| `prod` | środowisko produkcyjne | `prod_inventory_scw.yml` |
| `qa` | mirror produkcji (nowy) - hosty Tomcata | `qa_scw.yml` |
| `test` | serwery testowe | `test_inventory_scw.yml` |
| `dev` | serwery deweloperskie | `dev_inventory_scw.yml` |
| `live-test` | (?) | `live-test_inventory_scw.yml` |
| `tomcat` | serwer aplikacyjny Tomcat | `tomcat_inventory_scw.yml` |
| `nginx` | reverse proxy | `nginx_inventory_scw.yml` |
| `docker` | host dockerowy | `docker_inventory_scw.yml` |
| `apollo-docker` | host ze stosem apollo-docker (wymaga też `docker`) | `test_scw.yml` -\> grupa `tag_apollo_docker` |
| `docker-db-backup` | Host wykonujący backup bazy z kontenera | `docker_db_backup_inventory_scw.yml` |
| `infokiosk` | infokiosk | `kiosk_inventory_scw.yml` |
| `site24x7` | Host z agentem monitoringu | `site24x7_inventory_scw.yml` |
| `stepping-stone` | Bastion / jump host | `stepping_stone_inventory_scw.yml` |
| `kapibary` | kapibary | `kapibary_{prod,test}_inventory_scw.yml` |
| `womposy` | womposy | `womposy_{prod,test}_inventory_scw.yml` |
| `stoppable` | wyłączany poza godzinami pracy | `stoppable_inventory_scw.yml` |
| `stop-at-end-of-day` | wyłączany na koniec dnia | `stop_at_end_of_day_inventory_scw.yml` |
| `weekends-off` | wyłączany na weekend | `weekends_off_inventory_scw.yml` |
| `managed-by-terraform` | Zasób zarządzany kodem | (TODO) - Używany do oznaczania zasobu, który jest zarządzany kodem |

Kolumna "Inwentarz, który go czyta" opisuje stan dzisiejszy. Mamy jeden plik na tag. W układzie docelowym (sekcja 7) plików będzie cztery, po jednym na środowisko, a grupa `tag_<tag>` powstaje z taga automatycznie ((keyed\_groups)\[[https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html\#using-inventory-plugins](<https://docs.ansible.com/projects/ansible/latest/plugins/inventory.html#using-inventory-plugins>)\]). Dodanie nowego taga przestaje wtedy wymagać dodania pliku.

4. Konwencja nazewnicza

### Instancje

```
<środowisko>-<produkt>-<odbiorca>-<rola>-<lp>
```

**Skąd człon `<odbiorca>`.** To jest u nas wymiar dominujący, a wcześniejsza wersja konwencji nie miała na niego miejsca. Na produkcji maszyny są per klient: `drog-bruk`, `euroglas`, `weglokoks`, `neuca`. W testach są per zespół: `wombaty`, `oposy`, `kapibary`. To główny powód, dla którego jedna maszyna różni się od drugiej. Bez tego członu odbiorca wchodzi w miejsce produktu albo znika z nazwy zupełnie. Przykład: `prod-womposy-nginx-01` sugeruje, że `womposy` to osobny produkt, a to zespół testerski.

| Człon | Wartości | Uwagi |
| --- | --- | --- |
| `<środowisko>` | `prod`, `qa`, `test`, `dev` | ta sama nazwa co katalog w `terraform/environments/` i plik `ansible/inventory/<env>_scw.yml` |
| `<produkt>` | `apollo` | dziś jedyny |
| `<odbiorca>` | klient: `drogbruk`, `euroglas`, `weglokoks`, `neuca`<br>zespół: `wombaty`, `oposy`, `kapibary` | **opcjonalny**; bez myślnika wewnątrz członu |
| `<rola>` | `tomcat`, `docker`, `nginx`, `redis`, `bastion`, `ftp`, `vpn`, `kiosk`, `parser` | ta sama lista co tagi ról z sekcji 3 |
| `<lp>` | `01`, `02` | zawsze dwie cyfry, także gdy maszyna jest jedna |

Odbiorcę pomijamy tam, gdzie maszyna służy wszystkim.

| Przykład | Znaczenie |
| --- | --- |
| `prod-apollo-drogbruk-tomcat-01` | prod, Apollo, klient Drog-Bruk, Tomcat |
| `qa-apollo-drogbruk-tomcat-01` | jego odpowiednik w mirrorze QA - różni się **wyłącznie** pierwszym członem |
| `test-apollo-wombaty-docker-01` | test, maszyna zespołu wombaty |
| `prod-apollo-bastion-01` | wspólna dla wszystkich, bez odbiorcy |

Jak wyglądałyby dzisiejsze maszyny:

| Dziś | Wg konwencji |
| --- | --- |
| `drog-bruk-apollo-prod` | `prod-apollo-drogbruk-tomcat-01` |
| `redis-weglokoks-apollo-prod` | `prod-apollo-weglokoks-redis-01` |
| `stepping-stone-apollo-prod` | `prod-apollo-bastion-01` |
| `wombaty-apollo-docker-test` | `test-apollo-wombaty-docker-01` |
| `wombaty-automaty-apollo-docker-test` | `test-apollo-wombaty-docker-02` + tag `automaty` |

Myślnik rozdziela człony, więc nie może występować wewnątrz członu - stąd `drogbruk`, nie `drog-bruk`. Tag może zostać z myślnikiem (`drog-bruk`), bo tagów nie parsujemy.

### Nazwa jest dla człowieka, tag dla maszyny

Nazwa maszyny ma być czytelna na liście w konsoli. Do celowania służą tagi: `-l tag_wombaty`, a nie dopasowanie wzorca do nazwy hosta. **Nazwy maszyny nigdy nie parsujemy w kodzie** - inaczej każda zmiana nazwy staje się zmianą łamiącą, a konwencja przestaje być konwencją i staje się interfejsem.

### Istniejące maszyny

Istniejących maszyn **nie importujemy do Terraforma i nie przemianowujemy**. Zastępujemy je nowymi według procedury z sekcji 9, „Zastępowanie istniejących maszyn”. Dzięki temu konwencja obowiązuje od pierwszej maszyny z Terraforma i nie ma w kodzie wyjątków na stare nazwy. Tabela "Jak wyglądałyby dzisiejsze maszyny" pokazuje, jak będzie się nazywał następca.

### Pozostałe zasoby

| Typ | Wzorzec | Przykład |
| --- | --- | --- |
| Security group | `<env>-<rola>-sg` | `prod-tomcat-sg` |
| Private network | `<env>-pn` | `qa-pn` |
| VPC | `<env>-vpc` | `prod-vpc` |
| Public gateway | `<env>-gw` | `qa-gw` |
| Flexible IP | `<env>-<produkt>-<rola>-<nn>-ip` | `prod-apollo-tomcat-01-ip` |
| Klucz w state | `<env>/terraform.tfstate` | `prod/terraform.tfstate` |

5. Pipeline w TeamCity

```
commit / PR ---trigger VCS na terraform---> terraform plan -----> terraform apply -------> ansible-playbook
```

6. Stan (state) terraforma, blokady i disaster recovery

|  | Stan |
| --- | --- |
| Miejsce | Scaleway Object Storage, bucket `apollo-terraform-state` , klucz `<env>/terraform.tfstate` |
| Historia / disaster recovery | **wersjonowanie + Object Lock włączone** - każda wersja state jest zachowana i chroniona przed usunięciem do końca retencji; odtworzenie: [FAQ Terraform](<https://docs.logintegra.com/logintegra-ansible/terraform-faq/index.md>), sekcja 9 |
| Blokada przed równoczesnym `apply` | **brak** - do czasu jej wprowadzenia jedno `apply` naraz; docelowo `apply` tylko z TeamCity (faza F) |

Otwarte: blokada state. Terraform \>= 1.10 potrafi blokować przez plik `.tflock` w tym samym buckecie (`use_lockfile = true`), o ile Object Storage obsługuje zapisy warunkowe (`If-None-Match`) - do sprawdzenia na Scaleway.

7. Zarządzanie konfiguracją serwera

Ansible robi u nas dwie różne rzeczy i dopiero ich rozdzielenie sprawia, że mirror QA ma z czego powstać.

### Dwa rodzaje pracy

|  | Operacje (`playbooks/`) | Stan docelowy (`playbooks/state/` + `roles/`) |
| --- | --- | --- |
| Pytanie | „zrób X na wskazanym hoście" | „czym ma być ten serwer" |
| Wywołanie | ręcznie albo z TeamCity, z parametrami | cyklicznie i po każdym `terraform apply` |
| Idempotencja | nieistotna | obowiązkowa |
| Efekt zapisany | nigdzie - tylko na maszynie | w repozytorium |
| Przykłady | `stop-server-api`, `download-tomcat-logs-from-tmp` | konta, ufw, Tomcat, silnik Dockera |

Dziś prawie wszystko jest po lewej stronie: 30 playbooków operacyjnych i jedna rola. Prawa kolumna jest tym, czego brakuje - Terraform postawi maszynę, ale nic nie powie, co ma być w środku. Kryterium fazy D brzmi „`destroy` + `apply` odtwarza całe QA” i bez ról jest nieosiągalne.

### Zasada podziału

Jedno pytanie: **czy efekt tej zmiany ma przetrwać `terraform destroy` + `apply`?**

| Odpowiedź | To jest | Gdzie |
| --- | --- | --- |
| tak | stan | rola w `roles/`, dane w `inventory/group_vars/` |
| nie | operacja | playbook w `playbooks/` |

Konto użytkownika ma przetrwać - stan. Reguła ufw ma przetrwać - stan. Restart serwera nie ma czego przetrwać - operacja. Pobranie logów z `/tmp` - operacja.

### Układ katalogów

```
ansible/
├── inventory/
│   ├── prod_scw.yml, qa_scw.yml, test_scw.yml, dev_scw.yml   # docelowe: jeden na środowisko
│   ├── <18 plików *_inventory_scw.yml>                       # dotychczasowe, wygaszane
│   └── group_vars/
│       ├── all.yml                # dane wspólne (m.in. lista kont)
│       └── tag_<tag>.yml          # dane per grupa, np. tag_tomcat.yml
├── roles/
│   ├── users/
│   └── server_checks/
├── playbooks/
│   ├── <30 playbooków operacyjnych - płasko>
│   └── state/
│       ├── site.yml               # stan docelowy całego stada
│       └── base.yml               # warstwa bazowa: każdy host
└── ansible.cfg
```

Dwie rzeczy w tym układzie wymagają wyjaśnienia:

**`group_vars/` leży w `inventory/`, a nie obok playbooków.** Ansible wczytuje `group_vars/` z katalogu inwentarza, więc te dane widzą wszystkie inwentarze - i nowe, i te wygaszane. Gdyby leżały obok playbooków, playbook uruchomiony z innego katalogu dostawałby inny zestaw zmiennych.

**Playbooki operacyjne zostają płasko.** Przeniesienie ich do `playbooks/ops/` byłoby czytelniejsze, ale `AnsibleConstants.kt` woła `/home/ansible/playbooks/<nazwa>.yml`, a triggery cron gaszą po nich serwery. Rozdzielenie realizuje podkatalog `state/` - nowe rzeczy w nowym miejscu, stare ścieżki nietknięte.

### Konwencje w rolach

- Nazwa roli to rzeczownik opisujący, czym host ma być albo co ma mieć: `users`, `tomcat`, `docker_host`. Nie `install_tomcat`.
- Każda zmienna roli ma prefiks nazwy roli, np. `users_accounts`, `tomcat_version`. Wymusza to `ansible-lint` (`var-naming[no-role-prefix]`).
- Rola nie zawiera danych. `defaults/main.yml` trzyma bezpieczne wartości domyślne - najlepiej takie, przy których rola nic nie robi - a konkrety mieszkają w `group_vars/`.
- Rola musi przechodzić `--check --diff` i być idempotentna: drugie uruchomienie = zero `changed`.
- Rola nie decyduje o zasięgu. `hosts:` jest w playbooku w `state/`, celowanie przez `-l tag_*`.
- Każda rola ma `README.md` z tabelą zmiennych.

### Wygaszanie playbooków operacyjnych

Playbook nie znika w momencie powstania roli - TeamCity go woła. Kolejność:

1. Powstaje rola i przejmuje opis stanu; dane trafiają do `group_vars/`.
2. Playbook operacyjny czyta **to samo źródło danych** co rola. Od tego momentu nie da się ich rozjechać.
3. Buildy TeamCity przepięte na `playbooks/state/`.
4. Dopiero teraz playbook można usunąć - osobnym commitem, który da się cofnąć.

Kroki 1-2 są zrobione dla użytkowników. Kroki 3-4 to zadanie z fazy F.

### Przykład: użytkownicy

Konta i klucze tworzy pięć playbooków: `create-all-users-with-key`, `create-user-with-key`, `add-ssh-key-for-user`, `delete-user`, `remove-all-keys-from-user`. Żaden nie zostawia śladu w repozytorium: po odtworzeniu maszyny nikt nie wie, kto miał na niej dostęp.

Stanowym odpowiednikiem jest rola `users`, a lista kont mieszka w `inventory/group_vars/all.yml` jako `users_accounts`. Ten sam plik zasila `create-all-users-with-key.yml` - zmieniło się w nim tylko źródło danych, nie zachowanie. **Playbooki zostają i nadal działają.**

Co to zmienia: dopisanie osoby to PR z code review i historią, a nowa maszyna z Terraforma dostaje komplet kont z `playbooks/state/base.yml`, bez pamiętania o niczym.

Jedna decyzja jest świadomie odłożona: `users_exclusive_keys` ma domyślnie `false`, czyli rola dokłada klucze i nie rusza tych dopisanych ręcznie. Przełączenie na `true` sprawia, że `authorized_keys` zawiera wyłącznie klucze z repozytorium - i dopiero wtedy repo odpowiada na pytanie „kto ma dostęp do serwerów". Zrobić to trzeba jednorazowo i świadomie, po przejrzeniu, co faktycznie leży dziś na maszynach.

### Grupy powstają z tagów

Cztery nowe inwentarze (`<env>_scw.yml`) nie wypisują grup - budują je z tagów instancji przez `keyed_groups`. Zamiast osobnego pliku inwentarza na każdy tag:

```
ansible-playbook -i inventory/prod_scw.yml -l tag_tomcat playbooks/state/site.yml
ansible-playbook -i inventory/test_scw.yml -l 'tag_docker:&tag_wombaty' ...
```

Skutek uboczny jest tu ważniejszy niż liczba plików: skoro grupa nazywa się tak jak tag, to `group_vars/tag_tomcat.yml` zaczyna działać sam z siebie. Domyka to pętlę **Terraform -\> tag -\> grupa -\> zmienne -\> rola**: nadanie maszynie taga `tomcat` w `tfvars` wystarczy, żeby dostała konfigurację Tomcata.

Myślniki w tagach zamieniają się na podkreślenia (`stop-at-end-of-day` -\> `tag_stop_at_end_of_day`) - odpowiada za to `force_valid_group_names` w `ansible.cfg`, bo myślnik nie jest poprawnym znakiem w nazwie grupy Ansible.

### Uruchamianie

Wszystkie polecenia Ansible odpalamy **z katalogu `ansible/`** - stamtąd wczytywany jest `ansible.cfg` i stamtąd widoczne są role. Dotyczy to także `ansible-lint`, który konfigurację i tak znajduje w `.config/` w katalogu głównym repozytorium.

8. Mirror QA
9. Plan wdrożenia

| Faza | Zakres |
| --- | --- |
| **A** | Audyt i czystki na Scaleway |
| **B** | Restrukturyzacja repo: `logintegra-infra` z katalogami `terraform/` i `ansible/` |
| **C** | Bootstrap terraform |
| **D** | Mirror QA zbudowany od zera |
| **E** | Zastąpienie istniejących maszyn maszynami z Terraforma, w kolejności `test`, `dev`, `prod` |
| **F** | Pipeline TeamCity |

### Zastępowanie istniejących maszyn

Istniejących maszyn nie importujemy (`terraform import`). Każdą zastępuje nowa, zbudowana od zera z tego repozytorium, a starą wyłączamy i kasujemy.

**Dlaczego nie import.** Import przenosi do kodu stan, którego nikt nie zaprojektował: ręcznie dobrane typy, dyski Block Storage Legacy 5K, Ubuntu 22.04, nazwy spoza konwencji i konfigurację, której nie ma w repo. Zastąpienie od razu daje maszynę, którą umiemy odtworzyć - i sprawdza to przy każdej z nich, bo nowa maszyna działa tylko wtedy, gdy repo opisuje wszystko, czego potrzebuje.

**Procedura - maszyna po maszynie:**

1. Nowa maszyna trafia do kodu jako wpis w `<env>.tfvars`, z nazwą według konwencji z sekcji 4. Typ dobieramy na nowo, bo to moment na zmianę rozmiaru i generacji, np. z `DEV1` na `PRO2`. PR, `plan`, akceptacja, `apply`.
2. Host dostaje konfigurację: `ansible-playbook -i inventory/<env>_scw.yml playbooks/state/site.yml`.
3. Przed przełączeniem spisujemy i przenosimy stan, który żyje tylko na starej maszynie. Najlepiej do repo, do `group_vars`, żeby kolejne odtworzenie tego nie wymagało:

   - apollo-docker: `.env.local`, `config/app/**`, dumpy baz, dane testerów,
   - Tomcat: opcje JVM (`setenv.sh`), pliki poza WAR-em, agent APM,
   - wspólne: klucze w `authorized_keys` spoza repo, crony, reguły ufw.
4. TeamCity dostaje nowy wpis w `AppName.kt` i `ServerConstants.kt`, a potem robi pierwszy deploy na nową maszynę.
5. Przełączamy na nową maszynę adresy dla testerów, DNS, a na produkcji `api-proxy`. Stara działa równolegle - to jest plan wycofania.
6. Po okresie karencji wygaszamy starą maszynę. Proponowana karencja to 2 tygodnie dla `test` i miesiąc dla `prod`. Najpierw wyłączenie, po którym płacimy tylko za dyski i IP, potem ewentualnie ostatni snapshot. Na końcu usunięcie razem z wolumenami i flexible IP. Wpis znika z TeamCity, z monitoringu site24x7 i z `logintegra-resources.md`.

**Produkcja** różni się tylko krokiem 5: przełączenie w oknie serwisowym, przez `api-proxy`, z bazą i Redisem, które nie leżą na zastępowanej maszynie. Stara maszyna zostaje włączona do końca karencji, żeby powrót był przełączeniem z powrotem, a nie odtwarzaniem.

Stare inwentarze `*_inventory_scw.yml`, po jednym pliku na tag, usuwamy, gdy zniknie ostatnia maszyna, której używały buildy TeamCity.
