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