Przejdź do treści

Proces DevOps

[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)

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.

  1. 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

  1. Ś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.

  1. 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
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
  1. Pipeline w TeamCity
commit / PR ---trigger VCS na terraform---> terraform plan -----> terraform apply -------> ansible-playbook
  1. 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, 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.

  1. 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.

  1. Mirror QA

  2. 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.

Ostatnia zmiana: 2026-09-28 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e