Upgraden

Migraties bij het starten

De database van een connector heeft een schema dat met de versies meegroeit. Elke nieuwe versie brengt de migraties mee die ze nodig heeft. Control plane en data plane voeren bij het starten de migraties uit die nog niet zijn gedaan; de gebouwservice doet hetzelfde voor zijn eigen schema building. Er is geen aparte stap om de database bij te werken.

Starten meer instances tegelijk, dan voert er één de migraties uit en wachten de andere. Sommige versies zetten bij het starten ook gegevens om; de connector schrijft in het log wat hij heeft gedaan.

Een upgrade, stap voor stap

1. Lees wat er verandert. Bij een nieuw tweede cijfer in het versienummer, zoals van 0.1 naar 0.2, kan er iets breken, ook in het verkeer met andere deelnemers. Zie releases.
2. Maak een back-up van de database, en controleer dat je hem kunt terugzetten. Dat is je enige weg terug (zie hieronder en bij back-up).
3. Stop alle instances van control plane, data plane en gebouwservice. Er is geen garantie dat een oude versie goed werkt op een database die een nieuwe versie al heeft gemigreerd, dus laat ze niet naast elkaar draaien.
4. Start de nieuwe versie, eerst de control plane, dan de data plane en de gebouwservice. Gebruik een vaste tag, zoals ghcr.io/buildinglinks/connector:0.2.0.
5. Controleer /healthz van control plane en data plane: de versie, en status ok. Kijk in de beheeromgeving onder Status of de data plane actief is, en onder Bewijs wanneer het laatste anker was.

Geen weg terug op een gemigreerde database

Een oudere versie start niet op een database met migraties die ze niet kent. Ze stopt dan met een melding dat een migratie al is uitgevoerd maar ontbreekt. Dat is bewust: een oudere versie kan de nieuwe gegevens niet lezen, en zou ze kunnen beschadigen.

Wil je terug naar de vorige versie, dan zet je de back-up van vóór de upgrade terug, en start je de oude versie daarop. Alles wat er sinds die back-up is gebeurd, ben je dan kwijt, en dat heeft gevolgen voor je bewijsketen. Lees daarom eerst wat een herstel betekent.

Andere deelnemers

Een connector praat met connectors van andere organisaties, die hun eigen tempo van upgraden hebben. Er is nog geen vastgelegd beleid voor welke versies met elkaar samenwerken. Een nieuw tweede cijfer kan het protocol tussen connectors veranderen, zoals bij 0.2. Spreek een upgrade daarom af met de deelnemers waarmee je data uitwisselt, en met de beheerder van de dataspace.

Van 0.1 naar 0.2

Versie 0.2 maakt de dataspace gebouwspecifiek: gebouwen zijn BAG-panden, systemen hebben koppelingen per gebouw, producten zijn een selectie van de punten van een gebouw, en de data plane controleert per verzoek het gebouw en de punten uit de overeenkomst.

Wat breekt.

• Beide kanten moeten 0.2 draaien. Een connector van 0.2 sluit overeenkomsten over een verzameling gebouwen. Een connector van 0.1 weigert die. Ook berichten over erkenning en aanwijzing en het startbericht naar een data plane hebben nieuwe velden, die een connector van 0.1 negeert: hij zou dan het hele gebouw leveren en geen afbakening controleren.
• Paden naar gebouwen. Een backend die het Buildinglinks-protocol spreekt, krijgt het BAG-id in het pad, zoals /v1/buildings/nl.bag.pand.0014100040022681/points, in plaats van een eigen gebouw-id. Noemt je systeem gebouwen anders, dan geef je de eigen id op bij de koppeling; je hoeft je backend dan niet aan te passen (zie een backend koppelen).
• De database krijgt de migraties 0016 tot en met 0023, en de gebouwservice 0002. Er is geen weg terug naar 0.1 zonder de back-up terug te zetten.

Wat de connector zelf omzet.

• Een levering met een eigen adres en sleutel wordt bij het starten een systeem met één koppeling.
• Elke bestaande sleutel voor de gateway wordt een app met alle abonnementen en lezen en sturen, precies wat zo’n sleutel voorheen mocht. Je apps blijven werken; beperk ze daarna onder Apps.
• Bestaande producten blijven werken. Oude gebouw-id’s zoals rtm-01 blijven geldig als id van een object, en /api/v1/assets blijft bestaan naast /api/v1/products.

TechnischWat er in de migraties van 0.2 zit

Migratie	Wat
0016_sources_and_scope	systemen (bronnen) en de afbakening van producten en overeenkomsten
0017_agreement_revocations	intrekken van toegang, blijvend en met een reden
0018_topology_and_basis	de indeling als product en de grondslag van een aanwijzing
0019_apps, 0020_app_subscriptions, 0021_key_last4	apps, hun abonnementen en sleutels
0022_own_use	het eigen abonnement van een rechthebbende
0023_agreement_terminations	opzeggen beëindigt de overeenkomst
0002_energy_label (gebouwservice)	het energielabel uit EP-online