Przejdź do treści

Plan: TeamCity bez commitu na każdą maszynę

[PLAN] Stan na 2026-09-25. Dotyczy repozytoriów teamcity-configuration-as-a-code i logintegra-ansible.

1. Problem

TeamCity zna maszyny z kodu. Każda nowa maszyna, zmiana IP albo zastąpienie maszyny w fazie E oznacza commit w teamcity-configuration-as-a-code i przeładowanie konfiguracji:

Gdzie Co Skala
_self/enums/AppName.kt nazwa hosta każdej maszyny 66 wpisów
_self/constants/ServerConstants.kt ServerConfig: IP, użytkownik, port, ścieżki Tomcata 29 zaszytych IP
pozostałe pliki .kt IP wpisane wprost, np. 151.115.63.109 w WombatyApolloRunDockerGradleCheck.kt 26 IP w 13 plikach
BuildExtensions.prepareDeployParams if/elif generowany z SERVERS: nazwa -> IP, ścieżki cała lista
buildy zespołów, np. WombatyRebuild.kt AppName.WOMBATY_APOLLO_DOCKER_TEST.host na sztywno ~63 pliki odwołują się do AppName

To blokuje trzy rzeczy, które już planujemy:

  • Zastępowanie maszyn w fazie E: każda z ~23 maszyn testowych i ~12 produkcyjnych to zmiana w TeamCity.
  • Środowiska na żądanie: maszyna tworzona po merge'u nie może czekać na commit.
  • Zmianę IP: flexible IP z Terraforma jest nowe przy każdym odtworzeniu.

2. Zasada

TeamCity zna cel logiczny, a nie maszynę. Cel logiczny to np. „środowisko apollo-docker zespołu wombaty w test” albo „mirror produkcji Apollo w qa”. Maszynę i jej IP TeamCity ustala w chwili buildu z tagów Scaleway. Korzysta przy tym z kontraktu, który już mamy:

Terraform -> tag -> grupa w inwentarzu Ansible -> (rola Ansible | cel deployu TeamCity)
Stałe, w kodzie TeamCity Dynamiczne, ze Scaleway w chwili buildu
lista celów logicznych: wombaty, oposy, qa-apollo... nazwa maszyny
selektor celu: środowisko + tagi, np. test, apollo-docker, wombaty IP
wartości roli: użytkownik teamcity, port 666, /opt/tomcat/current, /home/teamcity/projects/apollo-docker czy maszyna istnieje, stan zasilania

Commit w TeamCity jest potrzebny tylko przy nowym celu logicznym, czyli nowym zespole albo kliencie. Nowa maszyna, zastąpienie i zmiana IP go nie wymagają. Środowiska na żądanie nie potrzebują commitu wcale, bo selektor przychodzi jako parametr (sekcja 6).

3. Jak to działa

sequenceDiagram
    autonumber
    participant B as Build TeamCity<br/>(np. Wystaw środowisko wombaty)
    participant A as Agent TeamCity
    participant D as logintegra-dev<br/>(ansible, poświadczenia SCW)
    participant S as Scaleway API
    participant H as Maszyna docelowa

    B->>A: krok "Ustal maszynę docelową"<br/>cel: env=test, selektor tag_apollo_docker:&tag_wombaty
    A->>D: ssh ansible@logintegra-dev:666<br/>resolve-target test 'tag_apollo_docker:&tag_wombaty'
    D->>S: inwentarz test_scw.yml (tagi -> grupy)
    S-->>D: instancje z tagami, IP, stan
    D-->>A: {"name": "test-apollo-wombaty-docker-01", "ip": "151.115.x.y", "state": "running"}
    alt dokładnie jedna maszyna
        A->>B: setParameter my.target.host = 151.115.x.y
        B->>H: dotychczasowe kroki: ssh teamcity@IP:666, deploy
    else zero albo więcej niż jedna
        A-->>B: build przerwany z listą znalezionych maszyn
    end

Kroki deployu w DeployBackendTemplate, RebuildTemplate i DockerDeployTemplate się nie zmieniają. Dalej czytają %my.target.host%. Zmienia się tylko źródło tej wartości.

Resolver resolve-target

To mały skrypt w logintegra-ansible, wdrażany na logintegra-dev razem z playbookami. Na tej maszynie są już Ansible, kolekcja scaleway.scaleway i poświadczenia SCW.

wejście środowisko (qa, test, prod) i wzorzec hostów Ansible, np. tag_apollo_docker:&tag_wombaty
źródło ansible-inventory -i inventory/<env>_scw.yml --list, czyli te same grupy z tagów co role
wyjście JSON: name, ip, state, id, zone
błąd zero albo więcej niż jedna maszyna: kod wyjścia ≠ 0 i lista kandydatów
stan zasilania zwraca także maszyny wyłączone (stoppable), więc build może je najpierw włączyć

TeamCity wywołuje resolver w kroku script na agencie, tak jak dziś prepareDeployParams. Wszystkie istniejące setParameter działają w krokach script, a nie sshExec. Klucz SSH do logintegra-dev daje feature ourSshAgent(), jak w HandleScalewayServerTemplate:

// szkic - _self/utils/BuildExtensions.kt
fun BuildSteps.resolveTarget(env: String, selector: String) {
    script {
        name = "Ustal maszynę docelową ($env: $selector)"
        id = "ResolveTarget"
        scriptContent = """
            set -euo pipefail
            json=$(ssh -p ${AnsibleConstants.ANSIBLE_SERVER_PORT} ${AnsibleConstants.ANSIBLE_USER}@${AppName.LOGINTEGRA_DEV.host} \
                   "resolve-target $env '$selector'")
            echo "Cel: ${'$'}json"
            echo "##teamcity[setParameter name='my.target.host' value='$(jq -r .ip <<<"${'$'}json")']"
            echo "##teamcity[setParameter name='my.target.name' value='$(jq -r .name <<<"${'$'}json")']"
        """.trimIndent()
    }
}

Cele logiczne zamiast ServerConfig per maszyna

Część wartości powtarza się dziś w każdym ServerConfig. W rzeczywistości należą do roli hosta i są takie same na każdej maszynie tej roli. Zapewnia je Ansible, czyli role teamcity_access, tomcat, tomcat_deploy i apollo_docker:

// szkic - zastępuje ServerConfig + wpis w AppName dla maszyn z Terraforma
enum class TargetRole(val user: String, val port: String, val tomcatPath: String?, val backupPath: String?) {
    TOMCAT("teamcity", "666", "/opt/tomcat/current", "/home/teamcity/backups/tomcat"),
    APOLLO_DOCKER("teamcity", "666", null, null),
}

data class DeployTarget(
    val label: String,          // "Wombaty (test)" - to widzi człowiek w liście wyboru
    val env: String,            // "test" -> inventory/test_scw.yml
    val selector: String,       // "tag_apollo_docker:&tag_wombaty"
    val role: TargetRole,
    val warName: String = "apollo",
)

Lista wyboru serwera (selectBackendApp) pokazuje cele logiczne. Opcje parametru select w TeamCity są statyczne, dlatego lista celów zostaje w kodzie. Maszyny z niego znikają.

Maszyny spoza naszego Scaleway zostają przy ServerConfig, bo nie mają tagów ani inwentarza. Chodzi o serwery dedykowane klientów i o Atlasa: 192.168.3.207, użytkownik ymsfrontend, Tomcat z pakietu.

4. Plan wdrożenia

Każdy etap działa samodzielnie i da się go cofnąć. Stary mechanizm AppName + ServerConfig żyje równolegle do końca etapu 5.

Etap 0: warunki wstępne

  • logintegra-dev wdraża logintegra-ansible z repo, buildem TeamCity albo przez git pull z crona. Dziś /home/ansible/playbooks i /home/ansible/inventory nie mają widocznego źródła aktualizacji.
  • Na logintegra-dev są nowe inwentarze <env>_scw.yml, scaleway SDK >= 2.9 i jq. Sprawdzenie opisuje sekcja 6 w docs/setup.md.
  • Klucze agentów TeamCity są w group_vars/all.yml jako teamcity_access_authorized_keys. Nowe maszyny muszą wpuszczać TeamCity bez ręcznej roboty.
  • Wiadomo, jak agent rozwiązuje dziś nazwy typu wombaty-apollo-docker-test: przez /etc/hosts, DNS czy inaczej. Jeśli przez /etc/hosts, to jest trzecia ręczna lista maszyn, którą ten plan też usuwa.

Gotowe, gdy ssh ansible@logintegra-dev -p 666 ansible-inventory -i inventory/test_scw.yml --graph pokazuje grupy tag_*.

Etap 1: resolver

  • resolve-target w logintegra-ansible z testem na inwentarzu constructed, bez API. Przypadki: jedna maszyna, zero, dwie, maszyna wyłączona.
  • Inwentarze widzą też maszyny wyłączone. Opcja state wtyczki ma domyślnie tylko running, patrz pytanie 3 w sekcji 7.

Gotowe, gdy na logintegra-dev polecenie resolve-target test 'tag_apollo_docker:&tag_wombaty' zwraca jedną maszynę albo czytelny błąd.

Etap 2: pilotaż na jednym celu

  • resolveTarget() w BuildExtensions.kt.
  • Jeden build zespołu przepięty z AppName.<X>.host na resolveTarget("test", "..."). Proponowany cel to automaty kapibar, bo ta maszyna nie trzyma danych testerów.
  • Maszyna pilotażowa zastąpiona nową z Terraforma w ramach fazy E, bez wpisu w AppName.kt.

Gotowe, gdy zastąpienie maszyny pilotażowej przez destroy, apply i site.yml nie wymaga żadnego commitu w teamcity-configuration-as-a-code.

Etap 3: hosty apollo-docker (test)

  • DeployTarget + TargetRole.APOLLO_DOCKER dla wszystkich zespołów i stagingów. RebuildTemplate i buildy zespołów używają resolveTarget.
  • Przepinanie idzie razem z fazą E: zastąpiona maszyna oznacza przepięty build i usunięty wpis AppName.
  • Start i stop w HandleScalewayServerTemplate działają po selektorze zamiast -l <nazwa>.

Etap 4: hosty Tomcata (qa, potem prod)

  • TargetRole.TOMCAT, a DeployBackendTemplate bierze ścieżki z roli.
  • Najpierw mirror qa, który powstaje od zera i od początku nie ma ServerConfig. Produkcja przechodzi później, przy jej zastępowaniu.
  • Przy deployu na prod resolver wypisuje cel w logu, a build wymaga potwierdzenia parametrem z display = PROMPT. Pomyłka w tagach nie może trafić na produkcję po cichu.

Etap 5: sprzątanie

  • Usunięte wpisy AppName i ServerConfig maszyn z Terraforma oraz zaszyte IP z listy w sekcji 1.
  • Usunięte stare inwentarze *_inventory_scw.yml i AnsibleConstants.ANSIBLE_*_INVENTORY_PATH.

5. Ryzyka i zabezpieczenia

Ryzyko Zabezpieczenie
błąd w tagach kieruje deploy na złą maszynę resolver przyjmuje tylko dokładnie jedną maszynę. Tag środowiska jest obowiązkowy i dokłada go Terraform. Na prod build wymaga potwierdzenia i wypisuje cel w logu.
API Scaleway niedostępne, buildy nie ruszą akceptujemy, bo bez API i tak nie da się włączyć ani odtworzyć maszyny. Błąd resolvera mówi wprost, co się stało.
nowa maszyna ma nowy klucz hosta SSH kroki scp już dziś używają StrictHostKeyChecking=no. Trzeba sprawdzić zachowanie runnera sshExec przy zmianie klucza.
maszyna wyłączona (stoppable) niewidoczna dla resolvera inwentarz z state obejmującym stopped, etap 1
logintegra-dev jako pojedynczy punkt wszystkie akcje start/stop już dziś idą przez tę maszynę, więc nic się nie pogarsza

6. Środowiska na żądanie

Ten sam mechanizm obsługuje maszyny tworzone po merge'u, bez żadnej listy:

  1. Terraform tworzy maszynę z tagiem środowiska na żądanie, np. env-<gałąź>. Każde takie środowisko ma osobny root module i osobny state.
  2. W tym samym łańcuchu buildów IP jest znane z terraform output, więc resolver nie jest potrzebny.
  3. Buildy uruchamiane później, np. testy i sprzątanie, dostają selektor jako parametr tekstowy: tag_env_<gałąź>.
  4. Nocny build usuwa środowiska z przeterminowanym tagiem expires-<data>.

7. Otwarte pytania

  1. Jak agent TeamCity rozwiązuje nazwy hostów, np. wombaty-apollo-docker-test: przez /etc/hosts, DNS czy inaczej?
  2. Jak aktualizowany jest /home/ansible na logintegra-dev: ręcznie czy z klonu repo? Od tego zależy etap 0.
  3. Czy start i stop działają dla maszyn wyłączonych? perform-server-action-and-wait.yml bierze id maszyny z inwentarza, a wtyczka scaleway.scaleway domyślnie zwraca tylko maszyny running. Albo na logintegra-dev jest starsza kolekcja z innym domyślnym zachowaniem, albo tamtejsze inwentarze ustawiają state. Do sprawdzenia przed etapem 1.
  4. Czy runner sshExec sprawdza klucz hosta? Od tego zależy zachowanie po zastąpieniu maszyny.

8. Rozważone alternatywy

Wariant Dlaczego nie teraz
DNS per cel: Terraform zakłada rekord wombaty.test.<domena> Dobre dla ludzi, bo testerzy i tak potrzebują stałych adresów, więc warto to zrobić obok. Wymaga jednak strefy DNS pod Terraformem i ma TTL oraz cache przy zastąpieniu. Dla TeamCity resolver z tagów jest prostszy i nie potrzebuje nowej infrastruktury.
Terraform zapisuje IP do TeamCity przez REST API Wiąże Terraform z TeamCity i wymaga tokenu TeamCity w pipeline Terraforma. Stan rozjeżdża się, gdy ktoś zmieni maszynę poza Terraformem.
TeamCity czyta state Terraforma State zawiera sekrety i jest per środowisko. Czytanie go z buildów daje szerszy dostęp niż potrzebny.
Generowanie AppName.kt z terraform output To dalej commit na każdą maszynę, tylko automatyczny. Nie rozwiązuje środowisk na żądanie.

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