Proces DevOps
[DRAFT]
- 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)
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.
- 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) 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
- Ś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]).
Dodanie nowego taga przestaje wtedy wymagać dodania pliku.
- Konwencja nazewnicza
Instancje¶
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, neucazespół: 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 |
- Pipeline w TeamCity
commit / PR ---trigger VCS na terraform---> terraform plan -----> terraform apply -------> ansible-playbook
- Stan (state) terraforma, blokady i disaster recovery
| Stan | |
|---|---|
| Miejsce | Scaleway Object Storage, bucket apollo-terraform-state <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, 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.
- 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. Nieinstall_tomcat. - Każda zmienna roli ma prefiks nazwy roli, np.
users_accounts,tomcat_version. Wymusza toansible-lint(var-naming[no-role-prefix]). - Rola nie zawiera danych.
defaults/main.ymltrzyma bezpieczne wartości domyślne - najlepiej takie, przy których rola nic nie robi - a konkrety mieszkają wgroup_vars/. - Rola musi przechodzić
--check --diffi być idempotentna: drugie uruchomienie = zerochanged. - Rola nie decyduje o zasięgu.
hosts:jest w playbooku wstate/, celowanie przez-l tag_*. - Każda rola ma
README.mdz tabelą zmiennych.
Wygaszanie playbooków operacyjnych¶
Playbook nie znika w momencie powstania roli - TeamCity go woła. Kolejność:
- Powstaje rola i przejmuje opis stanu; dane trafiają do
group_vars/. - Playbook operacyjny czyta to samo źródło danych co rola. Od tego momentu nie da się ich rozjechać.
- Buildy TeamCity przepięte na
playbooks/state/. - 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.
-
Mirror QA
-
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:
- 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. zDEV1naPRO2. PR,plan, akceptacja,apply. - Host dostaje konfigurację:
ansible-playbook -i inventory/<env>_scw.yml playbooks/state/site.yml. - 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_keysspoza repo, crony, reguły ufw.
- apollo-docker:
- TeamCity dostaje nowy wpis w
AppName.ktiServerConstants.kt, a potem robi pierwszy deploy na nową maszynę. - Przełączamy na nową maszynę adresy dla testerów, DNS, a na produkcji
api-proxy. Stara działa równolegle - to jest plan wycofania. - Po okresie karencji wygaszamy starą maszynę.
Proponowana karencja to 2 tygodnie dla
testi miesiąc dlaprod. 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 zlogintegra-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.
Ostatnia zmiana: 2026-09-28 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e