Przejdź do treści

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

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

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, 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
  • 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

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