Úvod

Záměrem TA ČR je vybudovat a provozovat SISTA jako cloud native systém. Takový systém má být odolný, snadno kontrolovatelný, robustní a nezávislý na konkrétních dodavatelích technologií. Obecná pravidla pro vývoj takového systému shrnuje manifest 12factor.

Manifest je přílohou tohoto dokumentu. Jeho českou mutaci lze taktéž najít zde.

V průběhu řešení projektu „Sdílený informační systém TA ČR“ očekáváme spolupráci architektů dodavatelů (DEV) s OPS týmem při konzultacích/úpravách týkající se právě stavby SISTA.

Kontext SISTA

Obrázek níže ukazuje základní pohled na celkový kontext SISTA. Zainteresované strany představují jednotlivé skupiny uživatelů, Sdílený informační Systém TA ČR je samotný systém, IS v perimetru SISTA jsou okolní systémy, s nimiž SISTA interaguje (interní TA ČR i externí), Dodavatelé projektu SISTA jsou subjekty spolupracující na vzniku SISTA a Definice procesů, pravidel a komponent projektu SISTA představuje soubor principů a nástrojů, jimiž se vývoj SISTA řídí.

Konceptuální rámec
Figure 1. Celkový kontext SISTA

1. DevOps meeting

DevOps meeting:

  • Sestává ze zástupců ops týmu, případně dalších dodavatelů TA ČR nezapojených do vývoje SISTA a technických architektů dev týmů.

  • Schází se podle potřeby (pravidelně či ad hoc) za účelem projednání technických záležitostí a otázek dev týmů ve vztahu k architektuře, technickému řešení platformy a běhovému prostředí.

  • Řeší výhradně otázky týkající se technické stránky věci. Nezasahuje do byznys části služeb.

  • Rozvíjí a udržuje tento dokument.

2. Cílová Architektura

Mikroservisy - je styl architektury [1], který strukturuje aplikaci na kolekci služeb tak, že jsou:

  • Snadno udržovatelné a testovatelné,

  • navzájem v maximální míře nezávislé,

  • nezávisle nasaditelné,

  • organizované podle business funkčností,

  • každá z nich v péči jednoho týmu.

SISTA konverguje k architektuře mikroslužeb, ale nevynucuje fragmentaci; kompozice byznys služeb jako „mikrolity“, tj. funkční služba (příklad: správa projektu, jednání, potřeby) nemusí (a zároveň může) být rozdělena na skupinu mikroslužeb. Volba architektury je na dodavateli, přičemž platí následující požadavky.

2.1. Platforma

Pravidla pro platformu:

  • Jednotlivé služby by měly v maximální míře obsahovat pouze business logiku.

  • Technické řešení poskytující běh služeb zajišťuje platforma, která se stará o repozitáře, pipelines, deployment, správu prostředí, infrastrukturu, IAM management, zabezpečení komunikačních kanálů mezi službami, jejich vzájemnou viditelnost, monitoring atd.

  • Platforma funguje „as a service“ pro vývojové týmy dodavatelů.

  • Její údržbu a rozvoj zajišťuje Ops tým.

  • Dodavatelé mohou přispívat do platformy, jak nápady, tak i přímo kódem.

Note Popis platformy je v repozitáři Platforma SISTA.

  • Platforma by měla zajistit, že není výrazně složitější vytvořit novou službu než začlenit nový kód do služby již existující. Je třeba zajistit, aby zvolené řešení nebylo řízené pouze náročností úpravy ale bylo i správné z hlediska architektury.

  • Jednotlivé Docker kontejnery běží na bázi Linux s tím, že jejich orchestraci zajišťuje Kubernetes provozovaný v Google Cloud Platform.

  • Vývoj všech služeb včetně dokumentace probíhá v git repozitářích TA ČR na Gitlabu.

  • Ops tým může být v procesech a postupech DevOps označován jako „platformní tým“. Tento tým je možné kontaktovat na adrese ops@tacr.cz.

  • Přístup ke službám může podléhat řízení přístupů, viz Pravidla vývoje. Obecně platí, že služby SISTA si navzájem plně důvěřují a poskytují si potřebná data bez omezení.

2.2. Komunikace mezi službami

  • Veškerá komunikace v rámci služeb SISTA se odehrává v kódování UTF-8.

  • Všechna data se ukládají v kódování UTF-8.

  • Všechny časové údaje zahrnují i časovou zónu.

  • Je žádoucí vhodně kombinovat synchronní (REST API volání) a asynchronní komunikaci (MQ).

    • Pokud služba potřebuje v danou chvíli (př. uživatelský požadavek, údaje s nízkou latencí) data jiné služby, volá ji synchronně. Vždy musí počítat s možností, že jiná služba neběží, a musí použít vhodnou retry policy – opakování dotazu, prodlužování intervalu, ošetření timeoutu.

    • Synchronní volání by nemělo přetěžovat cílovou službu. Cílová služba může přetížení indikovat dedikovaným HTTP kódem.

    • Pokud je synchronní volání drahé, měla by volající strana implementovat kešování. Obecný interval vypršení keše je 5 minut, pokud cílová služba nedokumentuje jinou hodnotu.

    • Všechny služby by měly přednostně využívat primární zdroje datových entit a nevytvářet jejich kopie, pokud to není pro fungování služby nutné. Pokud kopie existovat musí, je třeba zajistit jejich dlouhodobou konzistenci. Viz doporučení v kap. 2.5. Přístup k datům v [MT039] a terminologii tam stanovenou.

    • Pro informování o provedených změnách stavu (př. aktualizace údajů, přesun workflow do kroku XY) služby mají využít MQ – fronty zpráv. Služby zodpovědné za doménová data mají povinnost notifikovat ostatní o aktualizacích dat.

    • Architektura využívá koncept publish / subscribe.

    • Služby publikují zprávy do Topic a konzumují ze Subscription. Jedno nebo více Subscription může být připojeno na jeden Topic.

    • Pro každý Topic je přípustný jeden datový typ zprávy. Definování Topic_ů a _Subscription je deklarativně v gesci dev týmů, ops je zajišťuje.

      • Schéma pro validaci zprávy bude publikováno ve sdíleném schema registry.

      • Formát schématu je JSON.

      • Fronta zpráv je agnostická a obsahu jednotlivých zpráv nemá rozumět (schéma dumb pipes, smart end-points).

      • Formát zpráv je JSON a/nebo binární data.

    • Služba může obdržet totožnou zprávu vícekrát (at least once delivery).

      • Zpracování zpráv by mělo být idempotentní, aby nedocházelo k nekonzistenci.

      • Volající služba by měla předpokládat, že zpráva dojde k adresátovi.

    • Pořadí zpráv v Subscription je totožné jako pořadí zpráv v Topic.

    • Pokud jedna ze služeb neběží, druhou to přímo neovlivní. Zprávy se drží v messaging službě nezávisle na samotných službách.

    • Asynchronní sémantika v komunikaci vede k eventuální konzistenci (https://en.wikipedia.org/wiki/Eventual_consistency).

    • Asynchronní komunikace je zajištěna messaging službou (zajišťuje ops tým prostřednictvím technologie Dapr – ta slouží zároveň i jako jednoduchý servicebus). Dapr funguje jako sidecar Docker image: aplikace volá přes HTTP nebo gRPC Dapr, který zprostředkuje synchronní a asynchronní volání přes Google Pub–Sub. Dapr umožňuje pouze push zpráv. Podrobnosti vč. zabezpečení viz v HOWTO Platform.

  • Každá služba je zodpovědná za kontrolu svých vstupních parametrů. Upřednostňuje se pravidlo „parse, don’t validate“, v některých případech se validace považuje za správné řešení (př.: platné RČ).

  • Čtení/zobrazování dat, která pocházejí či závisí na cizí službě (např. SMS brána, IS datových schránek apod.), by nikdy nemělo být synchronního charakteru.

    • Komunikace s jakoukoli externí službou musí být implementována nezávisle, aby výpadek nebo nedostupnost externí služby nezpůsobily výpadek / nedostupnost služby SISTA.

2.3. Identifikátory SISTA

Komunikace mezi jednotlivými službami SISTA vyžaduje jednoznačnou identifikaci datových objektů (entit, instancí). K tomu účelu se definuje identifikátor SISTA dle standardu Uniform Resource Name (viz [URN]) podle následujících pravidel:

  • identifikátor sestává ze 3 řetězců dle schématu: "urn" ":" NID ":" NSS, části odděluje znak dvojtečka (:),

  • 1. část představuje pevný řetězec urn,

  • 2. část NID spojuje pevný řetězec sista: a identifikátor typu objektu,

  • 3. část NSS je jednoznačný identifikátor objektu daného typu.

NID typicky představuje buď definovaný typ objektu (sista:profiles) nebo namespace dané služby (sista:need). Jeho přidělení je stanoveno dohodou vývojových týmů jednotlivých služeb. Aktuální identifikátory jsou v tabulce níže s uvedením primárního zdroje.

Primární zdroj NIDs (zde bez prefixu sista:)

ApiGov

services

Rejstřík

departments, organizations, persons, profiles, projects, providers, relations

IdM

account

Notis

message

FiSto

files

Potřeby

need

Workflow

definitions, processes

Rule Engine

rulebooks

Správa úkolů

tasks

Vzkazník

conversation

Přidělení NSS je plně v kompetenci primárního zdroje, je pouze nutné dodržet povolené znaky dle standardu [URN] (pro případnou podkategorizaci se doporučuje použití oddělovače :). Pro definici NSS preferujeme název (objektu, služby) v množném čísle.

Příklady identifikátoru SISTA:

  • urn:sista:services:${serviceSysName}

  • urn:sista:departments:d:mzp,

  • urn:sista:projects:123,

  • urn:sista:need:D3990620-CD2F-4A14-8E8B-DE98B40C42D7,

  • urn:sista:files:rdy9RMGbj65D0lBv7NgoKOgPKOkJZ31X2Qe8xaoA/4826939563156/a6dd3748d92ebd67314c702349cdd0ae/pokusXX.pdf.

Konzumenti identifikátoru SISTA by s měli s částí NSS pracovat pouze jako s identifikačním řetězcem a neměli by ji parsovat, validovat, tokenizovat atd. Primární zdroj smí do části NSS ukládat dodatečné informace, ale na klientské straně se nepředpokládá jejich zpracovávání.

2.4. Uživatelské rozhraní

Pro tvorbu uživatelského rozhraní se používá architektura minifrontendů, viz Pravidla vývoje.

2.5. Aktuální stavba

Agentura provozuje systémy ISTA a ISBETA, které jsou zcela oddělené a zabezpečují rozdílné agendy (ISTA=veřejné soutěže X ISBETA=Veřejné zakázky). TA ČR disponuje možnostmi integrací obou systémů jak na datové, tak i funkční rovině do ekosystému SISTA. Cílem je oba systémy sjednotit v SISTA a “po cestě” agendy a data zjednodušit tak, aby výsledná služba byla pro klienty TA ČR co nejvíce uživatelsky přívětivá. Původní systémy by měly do konce roku sérií postupných kroků zaniknout, či být pouze v režimu read-only dostupné na infrastruktuře TA ČR.

Z hlediska architektury je možné klást požadavky na vznik nových API endpointů původních systémů, či definici potřebných dat, která lze z aplikací poměrně jednoduše získat. Mohou posloužit pro produkční provoz nových modulů v SISTA.

2.6. Q&A

  1. Jak se technologicky se napojím na platformu?

    • Dodané templates od ops týmu.

  2. Jak najdu službu, na kterou mám poslat data?

    • Service catalog - backstage.

    • Data catalog.

  3. Jakým způsobem data pošlu, jak mám se službou komunikovat (Dapr, synchronní REST volání, přímo Google Pub-Sub)?

    • Záleží na use case, všechny varianty jsou možné; přímý kontakt na Google Pub-Sub mimo Dapr je považován za nechtěný.

  4. Kde najdu formáty zpráv?

    • Schema registry.

  5. Jakou garanci mi dává platforma co se týče doručení zpráv?

    • At–least–once–delivery platforma zajistí, že zpráva dojde. Volající služba by měla předpokládat, že zpráva dojde.

3. Release notes dokumentu

Verze: 1.4.
Datum vydání: 31. 10. 2023.
Autor: Jiří Hanuš, David Ondřich, jiri.hanus@tacr.cz, dond@dond.cz.
Poznámka k verzi: Přesun repozitářů do Gitlabu.

Detailní popis změn:

  • Doplnění konceptuálního rámce projektu SISTA,

  • Aktualizace zpětné vazby z řešení projektu za měsíce říjen a listopad 2022.

  • Identifikátor SISTA.

  • Přesun repozitářů do Gitlabu.

Závěr

V dokumentu naleznete pravidla architektury SISTA.

Pokud byste něco chtěli upravit, udělejte nám pull request.

Termíny a definice

Datová entita

Datová reprezentace reálného objektu v datovém modelu, představující daný typ objektu. Příklad: uživatel, projekt, zakázka.

DevOps meeting

Exekutivní skupina zodpovědná za kontrolu a údržbu strategické a technologické architektury. Reprezentuje klíčové subjekty zainteresované v architektuře (stakeholder) a typicky sestává z členů ops týmu zodpovědných za dohled a údržbu celkové architektury z úhlu pohledu svých zodpovědností a relevantních členů dev dodavatelských týmů.

Odkazy a zdroje

Vnitřní předpisy a dokumenty
Internetové zdroje

Rejstřík

Příloha A: Seznam příloh

ID Název přílohy s odkazem repozitář Verze

01

02

03

04

05

06

07

08

09

10
1. https://cs.wikipedia.org/wiki/Mikroslu%C5%BEby