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.
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_varsi uruchamiamysite.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.
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. |
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 |
- Branch
DEV-XXXX, wpis wterraform/environments/test/test.tfvars: terraform plan -var-file=test.tfvars- spodziewany wynik: 2 zasoby do dodania (flexible IP, serwer). PR z planem, akceptacja drugiej osoby,apply.- Konfiguracja hosta:
- TeamCity: wpis w
AppName.ktiServerConstants.kt. Jak pozbyć się tego kroku, opisuje plan dla TeamCity.
- Branch
DEV-XXXX, wpis wterraform/environments/qa/qa.tfvars: terraform plan -var-file=qa.tfvars-> PR -> akceptacja ->apply.ansible-playbook -i inventory/qa_scw.yml -l qa-apollo-weglokoks-tomcat-01 playbooks/state/site.yml- TeamCity:
ServerConfigztomcatPath = /opt/tomcat/current, użytkownikteamcity, port 666 - jakAPOLLO_PROD(szczegóły).
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):
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:
- 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. - Wywołanie w
terraform/environments/<env>/main.tf, konkretne wartości w<env>.tfvars. - Nazwa wg tabeli "Pozostałe zasoby" w Procesie DevOps, sekcja 4; tagi: środowisko +
managed-by-terraform. terraform fmt -recursive,validate,planw 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>_nodesz walidacją nazwy wenvironments/<env>/variables.tfi wywołanie wmain.tf - klucz
<rola>winbound_rules(osobna security group) - rola(e) Ansible +
playbooks/state/<rola>-nodes.ymlzhosts: tag_<rola>, import wsite.yml - tag w tabeli tagów w sekcji 3 Procesu DevOps
- strona w
docs/i wpis wzensical.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¶
ansible/roles/<rzeczownik>/- nazwa mówi, czym host ma być (tomcat,docker_host), nie co robi (install_tomcat).defaults/main.yml: każda zmienna ma prefiks roli, czyli<rola>_..., co wymuszaansible-lint. Wartości domyślne są bezpieczne, najlepiej takie, przy których rola nic nie robi. Bez danych - dane wgroup_vars.tasks/main.yml: idempotentnie - drugie uruchomienie =changed=0; bezcommand/shelltam, gdzie jest moduł.README.mdz tabelą zmiennych i tym, czego rola nie robi.- Podpięcie:
playbooks/state/<rola>-nodes.yml(hosts: tag_<tag>) albo do istniejącego; import wsite.yml. - Kontrola:
cd ansible && ansible-lint,--check --diff, dwa uruchomienia (drugie bez zmian).
Operacja - nowy playbook¶
ansible/playbooks/<czasownik>-<co>.yml- płasko, bez podkatalogów: TeamCity woła/home/ansible/playbooks/<nazwa>.yml.hosts: all- zasięg wybiera wywołujący przez-i inventory/<env>_scw.yml -l tag_<tag>.- 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. - Operacja na zasilaniu / API Scaleway nie potrzebuje SSH do maszyny:
gather_facts: falseidelegate_to: localhost.
7. Częste pytania¶
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ć.
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.
Zmieniłem obraz, a plan nic nie pokazuje.
Celowo - moduł instance ignoruje image.
Nowy obraz = odtworzenie przez -replace (sekcja 4).
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.
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.
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.
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).
Ostatnia zmiana: 2026-09-28 · Dariusz Bąkowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e