Releases beheren

Een nieuwe versie van PHP, van de agent of van het paneel zelf gaat niet in één keer naar alle servers. Hij loopt: eerst een soak op het beta-kanaal, dan één canary-machine, dan de vloot in golven, met een wachttijd tussen elk paar en een gezondheidscontrole die het geheel kan stilzetten. Deze pagina gaat over hoe je dat vanuit het paneel stuurt, en hoe je leest wat het je vertelt.

Alleen beheerders zien dit. Resellers en eindklanten zien nooit welke versies er zijn, laat staan welke machine op welke versie staat.

Open Servers → Releases.

De drie vragen die het bord beantwoordt

De pagina staat in de volgorde waarin je ze echt stelt.

1. Mag er nú een golf starten? De banner bovenaan. Groen als de deur open staat, oranje als dat niet zo is — en dan staat er in een hele zin waarom: een zaterdag, een feestdag, of een incident dat iemand heeft geopend.

2. Wat wacht er op mij? De pijplijn. Elke versie met een badge voor zijn risicoklasse, zijn kanaal, en hoe ver de soak is.

3. Welke machines raakt hij als eerste? De golfgroepen, onderaan. Sleep een server van de ene kaart naar de andere om de volgorde te veranderen waarin de vloot wordt bijgewerkt.

Risicoklassen

De badge op elke release bepaalt alles aan de manier waarop hij reist.

• minor-runtime — een PHP-patch, een LiteSpeed-build. Op de node blijft er niets van achter, dus een downgrade is een echt antwoord, en het paneel zet hem zelf door zodra de soak schoon is.
• platform — de agent, of het paneel. Doorzetten gebeurt pas als een mens klikt, de canary is minstens drie machines waaronder een drukke, en het paneel rolt vooruit in plaats van terug: een database die gemigreerd is, migreert niet terug omdat een binary achteruit ging.
• security-critical — een fix die niet kan wachten. De timers krimpen. Verder niets.

Een onbekend pakket wordt als platform behandeld; dat is het behoudende antwoord. Onder Geavanceerd → risicoklassen overschrijf je de klasse van een pakket als de naamregel het misslaat.

Een release goedkeuren

Een release waarvan de klasse een mens vereist krijgt de status awaiting_approval, en de banner bovenaan telt ze. Open hem om het bewijs te zien:

Dit zijn dezelfde vier getallen waarop het paneel een minor-runtime-release zelf doorzet. Er is geen tweede, verborgen set.

Is de soak schoon, dan zet Goedkeuren hem naar het volgende kanaal. Is hij dat niet, dan leest de knop Toch goedkeuren en is een reden verplicht — die komt met jouw naam in het promotieregister en blijft daar staan.

Afwijzen vraagt ook een reden. Het is het enige verslag van waarom een release niet is uitgegaan.

Wat er in deze uitgave zit

Boven het bewijs staat sinds kort een link: Wat er in ‹versie› zit. Die brengt je naar de release notes van precies die uitgave van de serveragent — de software die deze uitrol op je machines zet.

Je staat op dit scherm op het punt een bouwsel naar servers van klanten te sturen. Tot voor kort was het versienummer het enige antwoord op "wat is er veranderd"; nu staat het er in gewone taal, per categorie, met de details één klik weg.

De link verschijnt alleen bij corecp-agent en alleen als er notities voor díe versie zijn. De andere pakketten in de pijplijn zijn software van anderen en daar publiceren wij geen notities voor; een tussentijds bouwsel (een nummer met ~dev erin) heeft ze nog niet.

Je kunt de lijst ook zonder een release openen: Wijzigingen in de zijbalk, en daar bovenaan schakelen tussen Paneel en Serveragent.

Golfgroepen

test staat op beta en bevat de operator-machines met synthetische klantsites erop. wave-1, wave-2 en wave-3 staan op stable, op volgorde van blast radius.

Twee dingen waar het paneel op staat:

• Golf 1 heeft een écht drukke server nodig. De kaart laat zien hoeveel hostingaccounts elke machine draagt en markeert de drukke. Een eerste golf van stille machines oefent geen enkel codepad dat de release straks tegenkomt, dus het bord waarschuwt als golf 1 er geen heeft — en een uitrol die zo gepland is wordt geweigerd.
• Een nieuwe server landt vanzelf in een late golf, round-robin, zodra je deze pagina opent. Sleep hem naar voren zodra je weet wat hij draagt.

Een groep kan zichzelf tegenhouden met een kanaal-pin of een versieplafond — een klant die een release achter wil blijven. Elke klasse respecteert dat, behalve security-critical: die bereikt ze tóch, tenzij je de groep expliciet uitzondert, en die uitzondering wordt vastgelegd met jouw naam en jouw reden.

Wat een uitrol stopzet

Terwijl een golf loopt wordt elke machine ná zijn eigen update gecontroleerd — niet "gaf apt exitcode nul", maar of zijn klanten er net zo goed voor staan als tien minuten eerder: antwoorden de websites nog, lopen hun foutlogs niet vol, blijft de mailqueue leeg.

Slaat die controle rood uit, dan doet het paneel vier dingen en stopt dan:

1. het rolt die machine terug naar de versie die hij had,
2. het stopt de uitrol, en de machines die het nooit bereikte krijgen de status overgeslagen,
3. het opent een incident, dat elke volgende golf blokkeert tot jij het sluit,
4. het stuurt de pagingmail.

Het probeert het nooit opnieuw. Een uitrol die een gevallen machine opnieuw probeert gaat flapperen, en elke ronde daarvan is weer een storing voor de sites erop. De vloot blijft staan waar hij staat en wacht op jou.

Eén server nu bijwerken

Niet elke update is een uitrol. Loopt één machine achter — je hebt hem net teruggezet, hij stond een dag uit, of je wilt hem vooruit voordat de rest volgt — dan is er Nu bijwerken op de serverpagina en op Componenten.

Wat die knop doet, en vooral wat hij niet doet:

• hij installeert wat het kanaal van díe machine nu aanbiedt. Hij verzet het kanaal niet; dat is een aparte keuze;
• hij haalt een terugrol-pin niet weg. Staat er een, dan blijft die staan en zegt het scherm dat de machine bewust wordt vastgehouden;
• hij wacht niet op het onderhoudsvenster. Dat venster is er voor de onbeheerde timer; jij drukt zelf.

Achteraf staat er één zin: bijgewerkt, was al bij, vastgehouden op een pin of overgeslagen, want …. Diezelfde zin staat op de taak, dus over drie uur is nog steeds te lezen wat die update gedaan heeft — ook voor een collega die er niet bij was. Vanaf de terminal doet dit hetzelfde:

ssh root@stck1.corecp.dev 'corectl update'

Servers buiten het versievenster

Het paneel en de agent op een server praten via een vast contract. Dat contract groeit — er komt een opdracht bij, een veld erbij — en elke groei is een nieuwe protocolversie. Het paneel ondersteunt zijn eigen protocolversie en de twee daarvoor. Dat is precies waarom een uitrol halverwege stopgezet mag worden: een vloot waarvan de helft nog niet bijgewerkt is, is een normale toestand en geen storing.

Staat een server buiten dat venster, dan zie je dat op twee plekken:

• op Servers een balk boven de lijst met de namen die het betreft;
• op de serverpagina zelf een balk met wat er aan de hand is en wat je eraan doet, plus een markering naast de naam.

De vier gevallen, en wat je doet:

Bijwerken doe je met Nu bijwerken op de serverpagina, met een uitrol, of vanaf de terminal:

ssh root@stck1.corecp.dev 'corectl update'

Waarschuwen, en pas daarna weigeren

Standaard waarschuwt het paneel alleen: het voert je wijzigingen gewoon uit en zegt erbij welke servers achterlopen. Wie het platform beheert kan dat aanzetten tot weigeren — eerst op één proefserver, daarna op de hele vloot. Dat staat in de configuratie van het paneel en niet in een scherm, want een vloot half doof zetten is een handeling met een onderhoudsvenster eromheen.

Weigert het paneel, dan blijven twee dingen altijd werken: uitlezen van de server, en de update zelf. Anders zou een geweigerde server een server zijn die je niet meer kunt repareren. Alleen wijzigen — een account aanmaken, een domein toevoegen — wordt geweigerd, met de reden en de herstelstap erbij.

Wat er tussen twee agentversies veranderd is, staat in de release-notities van de agent; de weigering verwijst daar zelf naar.

Een server die iets nog niet kan melden

Een server binnen het venster mag ook gewoon iets missen: het contract groeit door dingen erbij te zetten, dus een agent van twee versies terug beantwoordt alles wat hij kent en zwijgt over de rest. Dat is geen storing en het paneel behandelt het ook niet zo.

Waar dat zichtbaar is, staat het er met naam en versie. Op het certificaatdetail bijvoorbeeld: klik je op een certificaat van een server die de aanvraaggeschiedenis nog niet meldt, dan zegt het paneel welke server dat is, welke protocolversie hij spreekt, en dat bijwerken de geschiedenis zichtbaar maakt. De lijst zelf verandert er niet van — alles wat die server wél kan melden staat er gewoon.

Dat onderscheid is de reden dat het zo geschreven staat: "deze server heeft nog geen poging opgeschreven" en "deze server kan het niet melden" zijn twee verschillende zinnen, en maar één daarvan noemt iets om te doen.

Wat er op een server staat: Componenten

Het tabblad Componenten van een server is de inventaris: per soort — agent, PHP (FPM), PHP (LiteSpeed), database — welke versie erop staat, welke het kanaal klaar heeft en hoeveel oudere er nog in de repository liggen. Die oudere zijn geen geschiedenis: dat is waar een terugrol naartoe kan.

Op dat scherm zitten de handelingen die er al waren: een PHP-serie installeren of verwijderen (verwijderen weigert de machine zolang er nog een website op draait) en de server nu bijwerken. Met Kanaal lezen kijk je wat een ánder kanaal zou aanbieden zonder de machine te verzetten — het scherm zegt er dan bij dat die lijst niet tegen de sleutelbos van deze machine is gecontroleerd.

Blackout-vensters

Er start geen golf op vrijdag, zaterdag of zondag, op een Nederlandse feestdag, of terwijl er een incident open staat. Dat is geen bijgeloof: een golf bakt urenlang, en de hele waarde van dat bakken is dat iemand meekijkt.

Het toch proberen wordt geweigerd, met het venster erbij genoemd. De enige weg eromheen is de noodbaan.

Een herstel-uitrol voor wat achterbleef

Een uitrol die stopt laat machines achter: één die viel, en de rest die nooit geprobeerd is. Binnen die uitrol gebeurt er niets meer — dat is de regel hierboven en die blijft.

Wat je wél kunt doen staat sinds deze ronde op het bord zelf. Onder Vastgelopen updates staat de gestopte uitrol met de reden, en ernaast één knop: Herstel-update starten. Die opent een nieuwe uitrol die precies de achtergebleven machines dekt — de gevallen en de overgeslagen, en níet de machines die de update wél genomen hebben.

Twee dingen die je daar kunt tegenkomen:

• Er staat een incident open. Een uitrol die op een rode controle stopte opent er zelf een, en zolang die openstaat weigert het paneel elke nieuwe uitrol. Het bord zegt dat erbij. Sluit het incident, of ga via de noodbaan met een reden.
• Je kiest zelf de machines, dus jij bent de canary-keuze. Bij een groep blijft er altijd minstens één machine achter de poort: de canary is dan een steekproef. Een lijst die je zelf samenstelt is dat niet — je hebt ze één voor één aangewezen — en daarom is één server hier een geldig plan.

Dezelfde uitrol vanaf de terminal, met de machines erin:

curl -s -b cookies -X POST https://panel1.corecp.dev/api/v1/rollouts \
  -H 'Content-Type: application/json' \
  -d '{"node_ids":["<id>","<id>"],"canary_count":1,"note":"herstel"}'

De noodbaan

Het rode blok op het paneel van een release. Hij vraagt eerst om een reden, en somt op wat hij gaat overschrijven:

• de beta-soak — uren in plaats van dagen,
• de bake tussen golven — minuten in plaats van een dag,
• de kanaal-pin en het versieplafond van een groep,
• blackout-vensters,
• de zachtere gezondheidscontroles.

En wat hij niet overschrijft, en dat is het deel dat vertrouwen verdient:

• de canary. Geen enkele klasse mag hem overslaan, en er is geen pad in het paneel dat een uitrol zonder canary plant.
• een rode gate. De uitrol stopt nog steeds, rolt de gevallen machine nog steeds terug, en stuurt nog steeds een pagingmail.

Alles wat de noodbaan doet wordt vastgelegd: op de release, op de uitrol, en in het auditlog.

Vanaf de terminal

Alles hierboven is de API, en het is dezelfde API die het scherm gebruikt.

# Wat staat er in de pijplijn
$ curl -s -b cookies https://panel1.corecp.dev/api/v1/releases |
    python3 -c 'import json,sys
for r in json.load(sys.stdin):
    print(r["package"], r["version"], r["risk_class"], r["state"], r["channel"])'
corecp-php85 8.5.3 minor-runtime approved stable
corecp-agent 0.34.1 platform awaiting_approval beta

# Draai het promotiebeleid nu, in plaats van een kwartier te wachten
$ curl -s -X POST -b cookies https://panel1.corecp.dev/api/v1/releases/tick

# Mag er een golf starten?
$ curl -s -b cookies https://panel1.corecp.dev/api/v1/releases/windows |
    python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["open"])'
True

Op een server zelf is dezelfde controle die de gate gebruikt één commando:

# root@stck1
$ corectl release gate

Hij eindigt met 0 als de machine er niet slechter voor staat dan zijn baseline, en met 1 als dat wel zo is — met de site of de dienst erbij die veranderde.

Alles op deze pagina staat in jouw taal

Het releasebord legt veel uit: waarom een venster dicht is, wat een risicoklasse inhoudt, wie een versie mag doorzetten, en waarom een soak nog niet schoon is. Die zinnen worden op de server gemaakt, en tot de eindcontrole van ronde 2 kwamen ze er in het Engels uit — ook als je paneel op Nederlands stond.

Dat is opgelost, en op een manier die je merkt als je de taal omzet: zet het paneel rechtsboven op English en dezelfde uitleg verschijnt in het Engels, zonder de pagina opnieuw te laden. De server stuurt geen zin meer maar een verwijzing plus de getallen die erin horen; het paneel maakt er de zin van.

Op de commandoregel verandert er niets — daar staat de Engelse tekst nog steeds:

ssh panel1.corecp.dev 'corecp-panel releases policy --config /etc/corecp-panel/panel.yaml'
ssh panel1.corecp.dev 'corecp-panel waves board --config /etc/corecp-panel/panel.yaml'

Zie je op dit scherm tóch nog een Engelse zin terwijl je paneel Nederlands staat, meld hem dan: dat is een gaatje in de vertaallijst en geen bedoeling.

Zie ook

• docs/maintenance.md — het volledige beleid, de matrix en het mechanisme.
• Een server toevoegen — een nieuwe machine landt in een late golf; daar komt dat vandaan.

Als een terugrol wordt geweigerd

De vier knoppen op een lopende uitrol — stoppen, pauzeren, terugrollen per server en het kanaal terugzetten — vragen eerst om bevestiging. Wordt het daarna geweigerd, dan blijft dat venster staan met de reden erin. Vroeger ging het dicht en stond de uitleg op de kaart eronder, die je net had afgedekt.

Wat wél lukt, landt nog steeds op de kaart: het rapport per server van een terugrol staat daar, en tegen die tijd is het venster weg en kijk je naar de kaart.

Deze knoppen vragen ook om een verse bevestiging van wie je bent — een uitrol raakt elke machine in een golf. Dat venster verschijnt vanzelf, je vult je code in, en de handeling gaat daarna door zonder dat je iets opnieuw hoeft te kiezen. Klik je het weg, dan is er niets gebeurd: geen uitrol, geen melding, en de knop staat er nog precies zo bij.

Een nieuwe versie die niet in een kanaal opduikt

Heel af en toe is een pakket gebouwd, ondertekend en aan de repository toegevoegd terwijl het kanaal nog de versie ervóór levert. Wat er dan gebeurd is: twee bouwlanen waren in dezelfde seconde klaar en probeerden allebei de lijst van het kanaal aan te maken; één won en de ander stopte daar, met alles behalve die laatste stap al gedaan. Het platform herkent nu precies die botsing en wijst het kanaal naar het nieuwere moment in plaats van te stoppen, dus het zou niet meer moeten gebeuren — en gebeurt het toch, dan is de oplossing de bouw nog één keer draaien. Er hoeft niets ongedaan gemaakt te worden: het pakket zit al in de repository en de tweede run doet alleen de stap over die misging.

Wat elk kanaal levert kun je altijd opvragen:

bash scripts/release.sh status

Loopt een kanaal achter op het kanaal ervóór, dan zegt die regel dat en noemt hij het commando dat het bijtrekt.

Wat er precies in een versie zit

Naast elk gepubliceerd pakket staan sinds deze ronde twee extra bestanden: een stuklijst met elk onderdeel dat erin zit, en een herkomstnota die zegt waaruit en waarmee het gebouwd is. Ze zijn ondertekend, en hun vingerafdruk staat in het releasebestand dat je toch al controleert.

bash scripts/sign-release.sh verify corecp-agent 0.39.0

== attestations
   ok  corecp-agent_0.39.0_amd64.sbom.cdx.json  cyclonedx-1.6  20431 bytes
   ok  corecp-agent_0.39.0_amd64.provenance.json  slsa-provenance-1.0  1685 bytes

Een release zonder stuklijst wordt niet gepubliceerd — het ondertekenen weigert hem. Bij pakketten van vóór deze werkwijze staat er een lege lijst, zodat je "er is er geen" kunt onderscheiden van "niemand heeft gekeken".

Hoe je de stuklijst van je eigen versie ophaalt en zelf nakijkt dat ze echt is, staat in Waar een release vandaan komt.