VGR Fireplace

Publicering av Implementationsguider

Utveckling

Implementationsguider under utveckling byggs och pakteras som SNAPSHOT-versioner av IG webbplatsapplikation och NPM-paket. Webbplatsapplikationen publiceras sedan till utvecklingsmiljön på https://fhir-dev.vgregion.se som s k CI-Builds.
Webbsidor i Utvecklingsmiljön fhir-dev är endast nåbara via VGR:s intranät.

Vid push av kod till IG:ns repo triggas en pipleline så att sidorna byggs om, nedan bild visar översiktligt hur flödet går till.

  1. En utvecklare skickar kodändringar till IG:ns git repository.
  2. Uppdateringen av git repo triggar GitLab CI pipeline. Pipeline bygger IG med IG Publisher, paketerar som Docker OCI och NPM package.
  3. a. CI pipeline pushar Docker OCI till Harbor image registry.
    b. CI pipeline pushar IG package.tgz till Sonartype Nexus package registry.
  4. CI pipeline uppdaterar IG:ns GitOps-repo developement overlay med imagetag för ny Docker OCI. Pipeline klar.
  5. ArgoCD triggas av uppdateringen i GitOps-repo, hämtar ändringarna.
  6. ArgoCD applicerar senaste konfiguration på IG applikationen i “sitt” kubernetes kluster (dvs dev eller test) och uppdateringen blir tillgänglig på webbplatsen.

Test

När man så bedömer att en implementationsguide/revision uppnått en mognadsgrad då den är redo för kvalitetsgranskning kan man bygga en utgåva (release). Detta innebär att IG byggs med ett versionsnummer utan ändelsen ‘-SNAPSHOT’. Se nedan under rubrik Metadata vilka andra parametervärden som behöver sättas för en utgåva i test-fasen, t ex behöver releaseLabel anges.
Exempel:

Denna utgåveversion byggs och paketeras på samma sätt (med samma ci pipeline) som utvecklingsversionen och kommer därmed att publiceras till utvecklingsmiljön.
När utgåvan har byggts och pipeline lyser grönt SKALL versionsnummer räknas upp till nästa potentiella utgåveversion och ändelsen ‘-SNAPSHOT’ läggas till samt releaseLabel återställas till ‘ci-build’.
Exempel:

Nu när det finns en utgåveversion kan denna publiceras till testmiljön på https://fhir-test.vgregion.se.

För att publicera utgåvan till testmiljön utförs motsvarande steg 4-6 i flödet som beskrivs ovan under rubrik Utveckling, med skillnaden att steg 4 görs manuellt.
Det som ska göras i manuellt steg 4 är att uppdatera image TAG i IG:ns gitops-repo. Redigera filen ./overlays/test/patch-imagetag.yaml och sätt den nya utgåvans versionsnummer, spara (och pusha).
OBS! I testmiljön SKALL inga SNAPSHOT-versioner förekomma!

Exempel:

för utgåveversioner krävs inte den unika digest som syns vid snapshotversioner i dev - t ex @sha256:38f5e3026…. - då utgåveversionen endast byggs en gång medan samma SNAPSHOT-version ofta byggs och paketeras ett flertal gånger innan versionen räknas upp och därför behöver en unik markör.

När steg 4 är utfört kommer det automatiska GitOps-flödet att fortsätta med steg 5 och 6. Vänta så på att ArgoCD uppdaterar testmiljön; Kolla att fhir-test har fått utgåve-versionen och sedan är IG:n tillgänglig för kvalitetsgranskning.

Webbsidor i Testmiljön fhir-test är endast nåbara via VGR:s intranät.

Publicering för Extern granskning och Milestone release - Produktionsmiljö

Implementationsguider för extern granskning och färdiga implementationsguider publiceras i produktionsmiljön fhir-prod på https://fhir.vgregion.se.

Att publicera en IG med IG Publisher har visat sig ganska komplext. Dels är det en process i flera steg med flera olika git repon involverade. Dels är det många variabelnamn som ska sättas i olika steg och heta olika eller samma saker i fält med samma eller olika namn i olika filer. VGR har tagit fram verktyg och pipelines för att underlätta, kvalitetssäkra och automatisera processen.
OBS! På grund av komplexiteten och beroenden till det gemensamma ekosystemet (HL7 FHIR) görs denna typ av publicering endast till produktionsmiljön och blir därmed öppet tillgänglig för alla på internet.

Pipeline för publicering startas genom verktyget Publicera IG · GitLab.
(OBS för externa läsare, denna länk pekar vidare till VGRs intranät)
Detta verktyg endast i samråd med Kompetensgrupp FHIR. Nedan bild visar översiktligt hur flödet går till. Steg 3.4, där IGn läggs upp i IG registry, körs i dagsläget endast för VGR Base.

  1. Ansvarig för IG Publicering anger metadata för den aktuella publiceringen startar publiceringspipeline m h a verktyget Publicera IG .
  2. GitLab CI pipeline förbereder och validerar förutsättningar för publicering:
    1. CI pipeline klonar repot för aktuell IG och skapar en release-branch för angiven utgåveversion (git clone, git checkout).
    2. CI pipeline klonar IG Publications repo. Detta är det gemensamma repot för alla webbplatsens publicerade IG-versioner, vilket i nuläget innebär alla VGRs IG (git lone).
    3. CI pipeline fork/synkar/klonar VGRs fork av av FHIR IG-registry:
    4. Skapar/synkar fork från FHIR/IG-Registry (gh repo fork, gh repo sync)
    5. Clonar synkad VGR fork och skapar publish-bransch (git clone, git checkout)
    6. CI pipeline klonar HL7 FHIR-IG-History-Template för att hämta senaste mallar för FHIR IG historik (git clone). Detta repo kommer endast att läsas.
  3. CI pipeline bygger IG utgåva med Publisher+SUSHI med –go-publish för att skapa en publicering.
  4. CI pipeline publicerar utgåvan:
    1. Commit+push+tag+push+delete branch för aktuell IG utgåva.
    2. Commit+push+tag+push av uppdaterat webbplatsinnehåll med utgåvan till IG Publication repo main branch.
    3. Commit+push+tag av uppdateringar i VGR-FHIR/IG-registry.
    4. Gör pull request av VGR-Kompetensgrupp-FHIRs fork av FHIR IG-registry på github. Detta sker ännu så länge manuellt och kan göras efter att hela pipelinen kört klart. Pull request görs på https://github.com/VGR-Kompetensgrupp-FHIR/ig-registry. Detta görs endast för de IGs som ska finnas sökbara i FHIR registry, för närvarande endast VGR basprofiler.
  5. Git Publish pipeline - IG Publications CI Pipeline - triggas av uppdateringen i repot och exekverar publiceringsflödet som bygger och paketerar uppdaterad webbplats.
    1. Pushar FHIR IG Package till Nexus Package Registry
    2. Pushar OCI (Docker Image) till Harbor Image registry.
    3. Uppdaterar image tag i GitOps-repo overlays/prod/patch-imagetag.yaml (git commit + push).
  6. ArgoCD triggas av uppdateringen i GitOps-repo, hämtar ändringarna.
  7. ArgoCD applicerar senaste konfiguration på IG-Publications-applikationen i kubernetes produktionskluster, fhir-prod, och uppdateringen blir tillgänglig på den publika webbplatsen.

För ytterligare information om publiceringsprocessen, se beskrivning av verktyget Publicera IG · GitLab.

Metadata

Nedan metadata används i de olika faserna av publicering och anges vid start av scriptet.

Acceptanskriterier för Publicering av Milestone Release

IG Publishers validering (aka QA-report)

När IG Publisher körs genereras en QA report som listar errors, warnings och hints. Den ligger länkad längst ner på varje sida. Denna ska granskas och åtgärdas enligt nedan.

Errors

Inga byggen släpps vidare till prod med errors.

Warnings

Warnings som beror på fel som vi inte kan påverka och som inte påverkar kvaliten kan släckas med ignoreWarnings.txt inklusive motivering. Se mer på HL7 FHIR Guidance for IG creation/handling errors and warnings.
Alla andra warnings ska lösas.

Hints

Ta ställning till om dessa ska följas.

VGR:s profileringsanvisningar ska följas

Säkerställ särskilt att nedan är beaktat:

Användningsfall

Det ska finnas ett flödesdiagram för varje användningsfall. All information som omnämns i användningsfallet är med i profilerna.

Exempel

Det ska finnas exempel för varje profil i IGn. Exemplen ska tillsammans täcka allt som skiljer profilenerna från de profiler som den ärver ifrån. Om profilerna kan användas på många olika sätt bör det finnas flera exempel.

Extensioner

Eventuella extensioner är enda lösningen för behovet.

Kodverk

Alla kodverk är om möjligt publicerade på en kodverkstjänst.

Språk

IGn är konsekvent på det eller de språk som önskas.

Versionshantering och labels

Följ instruktionerna om versionshantering och labels i read.me för publicera IG - intern länk.