Automatisk oppgradering

Formålet med denne siden er å gjøre det enklest mulig å installere og konfigurere automatisk oppgradering av eFormidlings integrasjonspunkt.

1. Introduksjon
2. Forutsetninger
3. Konfigurasjon
4. Minimumskonfigurasjon
5. Valgfri konfigurasjon
   1. Setje tidspunkt for oppdatering
   2. Blokkere versjonar
   3. Konfigurasjon for logging
   4. Diverse konfigurasjon
6. Hvordan fungerer automatisk oppgradering?
   1. Finna noverande versjon av integrasjonspunktet
   2. Finna siste versjon av integrasjonspunktet
      1. Early-Bird-versjon
   3. Sjekk av versjon-kompatibilitet
   4. Nedlasting av siste lanserte versjon
   5. Validering av nedlasta artefakt
   6. Stopp av gammalt integrasjonspunkt
   7. Oppstart av ny versjon
      1. Meldingar til brukarane
      2. Blocklisting av versjon som ikkje starta
      3. Logg frå oppdaterande integrasjonspunkt
      4. Allowlisting av versjon som har vore starta før
7. Køyra KOSMOS
   1. Køyra som Windows-teneste
      1. Lokal property-fil for KOSMOS
      2. Andre antakingar i oppsettet i denne seksjonen
      3. Køyra KOSMOS og Integrasjonspunktet frå forskjellige mapper
8. Kjeldekode
9. Neste steg

Introduksjon

Automatisk oppgradering av integrasjonspunktet skjer ved hjelp av støtteapplikasjonen Kosmos. Kosmos er en Java- applikasjon som kan kjøre side om side med integrasjonspunktet.

• Demo av automatisk oppgradering

Automatisk oppgradering e i grove trekk slik:

1. Sammenligner gjeldende integrasjonspunkt-versjon mot siste tilgjengelige i Maven-repositoriet til Digdir
2. Dersom det er en nyere versjon tilgjengelig, vert denne lasta ned til klienten
3. Gjeldende integrasjonspunkt vert forsøkt oppdatert til den nedlasta versjonen (Dersom den nye versjonen ikke starter, ruller KOSMOS attende)

Forutsetninger

Konfigurasjon av automatisk oppgradering forutsetter:

• Installasjon av integrasjonspunktet og bruk av Java
• Støttetjenestene er tilgjengelig i integrasjonspunktet

Konfigurasjon

Automatisk oppgradering av integrasjonspunktet konfigureres ved hjelp av en konfigurasjonsfil.

1. Start med å finne mappen integrasjonspunktet er installert til, for eksempel c:\integrasjonspunkt
2. Last så ned kosmos-local.properties og lagre i overnevnte mappe
3. Last ned kosmos-[versjon].jar
4. Last ned eFormidlings offentlige nøkkel

eFormidling anbefaler å verifisere at kosmos-[versjon].jar er fra Digitaliseringsdirektoratet.

• Hvordan verifiserer jeg at jar-filen er fra Digitaliseringsdirektoratet?

Når du er ferdig skal strukturen på området se slik ut:

c:/
|-- integrasjonspunkt/
   |-- eformidling-key.asc
   |-- integrasjonspunkt-local.properties
   |-- integrasjonspunkt-[versjon].jar
   |-- kosmos-local.properties
   |-- kosmos-[versjon].jar

I tillegg må Kosmos kjøres med nødvendige tilganger til å opprette filer og mapper på dette filområdet.

Ved bruk av Java direkte anbefales det at det konfigureres en bakgrunnstjeneste som starter og stopper Kosmos når operativsystemet starter og stopper, og som ved behov kan startes og stoppes manuelt. Eksempel:

• Kjøre kosmos som en tjeneste (Windows)
• systemctl, upstart eller lignende, avhengig av distribusjon (Linux)

Det er også mulig å starte og stoppe integrasjonspunktet manuelt:

• Kjøre integrasjonspunktet fra kommandovindu

Minimumskonfigurasjon

Eksempel:

# Replace hosts and ports of URL with the location
# of your integrasjonspunkt.
kosmos.integrasjonspunkt.baseURL=http://localhost:9093

# Your organisationnumber. Should be the same as in integrasjonspunkt-local.properties
difi.move.org.number=991825827

# E-mail is optional. Please specify these properties 
# to receive e-mails when KOSMOS updates the integrasjonspunkt-application.
kosmos.mail.recipient=someone@yourdomain.no
kosmos.mail.from=noreply@yourdomain.no

spring.mail.host=smtp.yourdomain.no
spring.mail.port=25

# Digitaliseringsdirektoratet public key paths. i.e: file:keyname.asc
kosmos.verification.publicKeyPaths[0]=file:eformidling-key.asc

NB! Dersom en ønsker å bruke integrasjonspunktet med transportsikring må en endre til kosmos.integrasjonspunkt.baseURL=https://servernavn.no:portnummer. Se mer her: Transportsikring

Valgfri konfigurasjon

Setje tidspunkt for oppdatering

Valgfritt

Ein kan setje tidspunkt for kor tid applikasjonen vil forsøke å oppdatere integrasjonspunktet om ein ikkje ynskjer å bruke standard-verdiane. Standard verdiane er kl. 05:30, 19:30 og 21:30

Her er nokre døme som viser korleis ein kan styre tidspunkt for oppdatering.

#Standard verdi: Sjekkar etter oppdatering måndag-fredag kl. 05:30, 19:30 og 21:30.
kosmos.schedulerCronExpression=0 30 5,19,21 * * MON-FRI

#Sjekkar etter oppdatering kvar dag kl. 06:00.
kosmos.schedulerCronExpression=0 0 6 * * ?

#Sjekkar etter oppdatering kvar dag kl. 23:15.
kosmos.schedulerCronExpression=0 15 23 ? * *

#Sjekkar etter oppdatering kvar laurdag og søndag kl. 12:00.
kosmos.schedulerCronExpression=0 0 12 ? * SAT,SUN

#Sjekkar etter oppdatering kvart tredje minutt kvar time.
kosmos.schedulerCronExpression=0 0,3,6,9,12,15,18,21,24,27,30,33,36,39,42,45,48,51,54,57 * ? * *

Blokkere versjonar

Valgfritt Det finnes funksjonalitet for å la applikasjonen blokkliste versjonar om den ikkje er godkjend eller klarer starte. Standard verdien til denne er false, men kan aktivere ved å endre properties. Det kan være fornuftig å bruke om ein ynskjer hyppig polling på kor ofte applikasjonen skal sjekke etter ny versjon.

kosmos.blocklist.enabled=true

Ein kan fjerne ein blokklista versjon ved å slette den frå katalogen. Filnamn er til dømes integrasjonspunkt-versjonsnr.blocklisted. Denne har standard levetid på 2 timar om aktivert, så etter levetid er utløpt vil applikasjonen fjerne den og forsøke å oppdatere igjen ved neste schedulerte tidspunkt.

Konfigurasjon for logging

Valgfritt

Denne er ikkje satt som default og må leggast inn manuelt

Diverse konfigurasjon

Valgfritt

Hvordan fungerer automatisk oppgradering?

KOSMOS køyrer periodiske sjekkar i rekkefølga beskriven her. Innstillinga kosmos.scheduler-cron-expression avgjer kor ofte dette skjer.

Finna noverande versjon av integrasjonspunktet

Den versjonen av integrasjonspunktet som ev. køyrer, vert henta frå info-endepunktet (Spring Boot Actuator) til det køyrande integrasjonspunktet. URL-en til info-endepunktet er avleia frå verdien på kosmos.integrasjonspunkt.baseURL. Dersom KOSMOS ikkje mottek informasjon frå info-endepunktet, eller det ikkje finst - noko som er godt mogleg - antek me at det ikkje køyrer noko integrasjonspunkt hjå klienten. Applikasjonen held då fram med neste steg.

Finna siste versjon av integrasjonspunktet

Siste versjon av integrasjonspunktet vert bestemt av konfigurasjonar frå efm-eureka, som er Spring Cloud Config Server-applikasjonen vår. Ved kvar periodiske køyring vil KOSMOS henta ned oppdaterte konfigurasjonar frå efm-eureka. Innstillinga kosmos.integrasjonspunkt.latest-version angir siste offisielle versjon som er lansert av Digdir. Det finst konfigurasjonar for dev-, test- staging- og production-profilar, der sistnemnde er relevant i ein produksjons-omgjevnad.

Early-Bird-versjon

For interne test-miljø (som endå ikkje er på føtene) og klientar som ev. ønsker å hjelpa oss med testing, kan siste lanserte versjon overstyrast til den såkalla “early-bird-versjonen”. Dette er versjonar som har vorte testa i mindre grad enn siste offisielle versjon ovanfor. Early-bird-versjon kan aktiverast mha. kosmos.integrasjonspunkt.early-bird (true/false). Dersom denne er aktivert, vil versjonen i kosmos.integrasjonspunkt.early-bird-version overstyra kosmos.integrasjonspunkt.latest-version. Early-bird-versjonen skal også konfigurerast mha. efm-eureka (dvs. utan lokal overstyring hjå klienten).

Sjekk av versjon-kompatibilitet

Semantisk versjonering er nytta i eFormidling. Applikasjonar som nyttar denne versjoneringa vert gjort tilgjengelege i major-, minor- og patch-versjonar som er reflektert i namnet på distribusjonane i form av -.., t.d. integrasjonspunkt-1.9.2. Oppgradering av ein større eller mindre versjon inneber alltid ein inkrement i namnet på distribusjonen.

Ein oppgradert major-versjon (t.d. frå integrasjonspunkt-1.9.2 til integrasjonspunkt-2.0.0 inneheld endringar som bryt med førre versjon. Oppgraderingar av major-versjonar kan føra med seg større eller mindre endringar hjå klientane. Eit døme på dette kan vera oppgradering av Java-versjonen som integrasjonspunktet køyrer på, som medfører at klienten må gjera oppgraderingar før det nye integrasjonspunktet kan takast i bruk. For å sikra at KOSMOS sin automatiske oppgradering ikkje lagar krøll for klientar som ikkje er klare for ein ny major-versjon endå, har me innført eit “setebelte” i form av kosmos.integrasjonspunkt.supported-major-version. Denne verdien kan setjast lokalt hjå klientar, og sikrar at KOSMOS ikkje utfører oppgraderingar til ein nyare major-versjon enn den som er angjeven.

Nedlasting av siste lanserte versjon

JAR-fila med siste integrasjonspunkt-versjon vert lasta ned til mappa angjeve i kosmos.integrasjonspunkt.home, som har mappa KOSMOS køyrer frå som standard-verdi. Dersom eit tidlegare forsøk på å starta den siste versjonen har feila (dvs. versjonen er blocklista), vil KOSMOS avbryta nedlastinga og skriva ut ein beskjed om tilfellet. Sjå meir om block- og allow-listing av versjonar seinare.

Artefaktar vert lasta ned frå lokasjonen som er angjeven i innstillinga kosmos.mavenCentral . Innstillingane , kosmos.group-id og kosmos.artifact-id bidreg vidare med å plukka ut den ønska distribusjonen for klienten. Nedlastinga skjer frå MavenCentral repositoriet til Digdir, døme kan sjåast her

Validering av nedlasta artefakt

MD5- og SHA1-sjekksummar vert samanlikna etter nedlasting av JAR-filer frå Maven-repositoriet.

Kodesignering og validering er innført. Den offentlege delen av eFormidling sitt GPG-signeringssertifikat er gjort tilgjengeleg for kundane på maven central . Dette vil nyttast til verifikasjon av at JAR-filene som vert lasta ned er signert av Digdir. Brukarar av KOSMOS må lasta ned den offentlege nøkkelen til eFormidling sitt GPG-signeringssertifikat frå ei sikker nettside (dokumentasjonen vår/ HTTPS). Dokumentasjonen vil også innehalda fingeravtrykket til den offentlege nøkkelen. Etter å ha lasta ned offentleg nøkkel, kan brukarar rekna ut fingeravtrykket frå den nedlasta fila og samanlikna med den publiserte verdien frå Digdir. Dersom verdiane er like, kan dei nytta nøkkelen til å verifisera integrasjonspunkt-distribusjonar. Verifiseringa vert gjort av deploymanager, og det einaste brukarane treng å gjera er å legga nøkkelen i same mappe som deploymanager-JAR-fila.

Dersom namnet på nøkkel-fila har vorte endra, eller brukarane ønsker å legga den offentlege nøkkelen i ei anna mappe, må dei setja ein konfigurasjonsverdi: kosmos.verification.publicKeyPaths[0]. Talet i klammeparantes er påkrevd fordi publicKeyPaths er ei liste - noko me nyttar oss av i overgangsperiodar når ein nøkkel er i ferd med å gå ut på tid. To offentlege nøklar med tilhøyrande fingeravtrykk vil då vera publiserte i Digdir sin dokumentasjon, og brukarane må setja publicKeyPaths[0] og -[1] for å bruka begge til å verifisera integrasjonspunkt-distribusjonar.

Stopp av gammalt integrasjonspunkt

Dersom valideringa av den nye versjonen passerer, vert eit ev. køyrande integrasjonspunkt stoppa via ein førespurnad til shutdown-endepunktet. Deretter sjekkar KOSMOS helse-endepunktet inntil status ikkje lenger returnerer “UP” eller operasjonen timar ut. Innstillingane kosmos.shutdown-retries og kosmos.shutdown-poll-interval-in-ms har sentrale rollar i denne funksjonaliteten. Dersom integrasjonspunktet ikkje stoppar innan det resulterande vindauget, vil KOSMOS logga at den ikkje kunne stoppa integrasjonspunktet. Operasjonen vil då avbryta, og integrasjonspunktet vil vera i inneverande tilstand fram til neste periodiske KOSMOS-køyring.

Oppstart av ny versjon

Når den førre versjonen er stoppa, vil det nye integrasjonspunktet verta forsøkt starta opp. Den nye versjonen køyrer som ein child-prosess av KOSMOS, med profil angjeven i innstillinga kosmos.integrasjonspunkt.profile.

Ei relevant innstilling å nemna i denne samanheng er kosmos.environment.prefixes-removed-from-child-process, som inneheld ei liste med prefiks på innstillingar som ikkje skal vidareførast til child-prosessen - då dei kan skapa utfordringar i det oppdaterte integrasjonspunktet. Sluttbrukarar skal ikkje ha noko forhald til denne innstillinga, så den er derfor ikkje fremheva.

Innstillingane kosmos.launch-poll-interval-in-ms og kosmos.launch-timeout-in-ms definerar eit vindauge der KOSMOS sjekkar helse-endepunktet til det nyleg starta integrasjonspunktet. Dersom helse-endepunktet ikkje svarar innan dette vindauget, antek KOSMOS at oppdateringa feila. Den vil då starta oppatt førre versjon, dersom klienten hadde eit køyrande integrasjonspunkt før oppdateringsforsøket.

Meldingar til brukarane

Dersom brukarane har sett innstillingane kosmos.mail.recipient og kosmos.mail.from, vil KOSMOS senda e-postar ved vellykka og feilande oppgraderingar. Elles er informasjonen tilgjengeleg i loggane til applikasjonen, som kan sendast til Digdir dersom kunden ønsker det.

Blocklisting av versjon som ikkje starta

Dersom kosmos.blocklist.enable har verdien ‘true’, og eit forsøk på oppdatering av integrasjonspunktet feilar innan vindauget beskrive i førre seksjon, vil versjonen verta blocklista. Dette medfører at KOSMOS ikkje vil forsøka å oppdatera til denne versjonen innan eit vindauge som er bestemt av innstillinga kosmos.blocklist.duration-in-hours. Ved kvar periodiske køyring vil KOSMOS sjekka levetida på ei ev. blocklisting av siste versjon, som beskrive i ein tidlegare seksjon av dette dokumentet.

Logg frå oppdaterande integrasjonspunkt

Integrasjonspunktet loggar mykje under oppstart, noko som kan vera nyttig medan ein prøver å setja opp KOSMOS for første gang. Ein kan setja innstillinga kosmos.integrasjonspunkt.include-log=true for å importera loggane frå det nye integrasjonspunktet i KOSMOS-loggen. Resultatet er at det vert litt enklare å få tak i loggen til den integrasjonspunkt-versjonen ein prøver å oppdatera til, sidan den vert tilgjengeleg saman med annan nyttig KOSMOS-logg. Ulempa er at det vert meir logg å forhalda seg til, samt at ein kan risikera dobbel-logging dersom både integrasjonspunktet og KOSMOS sender loggar til samme aggregeringsløysing, t.d. logstash. Logg-linjene som vert importerte frå integrasjonspunktet vil ha eit gjenkjenneleg prefiks ([INCLUDED]) for å skilla dei frå KOSMOS-linjer.

Allowlisting av versjon som har vore starta før

Som eit tiltak for å sikre at applikasjonen vil starte opp integrasjonspunktet etter at applikasjonen har vore skrudd av så vart allowlisting innført og denne lagar .allowlisted filer. Til dømes om applikasjonen og integrasjonspunktet begge er av så vil den ikkje forsøker å oppdatere integrasjonspunktet om det allereie eksisterer ei .allowlisted fil. Dette var også eit behov i ein spesiell case der kosmos.integrasjonspunkt.supported-major-version var satt lik køyrande versjon og det har vore releasa ein “latest-version” som har høgare major enn det som er konfigurert til å være støtta. Etter at integrasjonspunktet har starta så vil applikasjonen lage denne .allowlisted fila, denne vert automatisk fjerna ved oppgradering og ny fil for gjeldande versjon vert oppretta. Innhaldet er tidspunktet den vart oppretta.

Køyra KOSMOS

Køyra som Windows-teneste

Me brukar WinSW som Windows-service-wrappar. Følg standard-installasjonsinstruksane med denne konfigurasjonsfila:

<configuration>
  
  <!-- Identifikator for tenesta. Bør vera unik innanfor Windows-systemet. -->
  <id>kosmossvc</id>
  <!-- Namn på tenesta -->
  <name>Kosmos Service</name>
  <!-- Beskriving av tenesta -->
  <description>Keeps the integrasjonspunkt application up-to-date.</description>
  
  <!-- Sti til det køyrbare programmet som skal startast. -->
  <executable>java</executable>
    <arguments>-jar %BASE%\kosmos-X.Y.Z.jar --spring.profiles.active=production</arguments>
    <!-- For å køyra med staging-profil: Erstatt 'production' med 'staging' i linja ovanfor. -->
  <logpath>%BASE%\kosmos-logs</logpath>
  
  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>
</configuration>

Legg merke til at ein treng å vera lokal administrator-brukar når ein installerar tenesta.

Lokal property-fil for KOSMOS

Det trengs ei fil med namn kosmos-local.properties i samme mappe som WinSW. Her er eit døme på ei slik fil. Erstatt verdiane i innstillingane med tilsvarande for din organisasjon.

difi.move.org.number=<organisasjonsnummer-med-ni-siffer>

# Erstatt vert og port i URL-en med plasseringa til Integrasjonspunktet ditt:
kosmos.integrasjonspunkt.baseURL=http://localhost:9093

# E-post-varse er frivillig. Spesifiser desse innstillingane for å motta e-postar når KOSMOS oppdaterar Integrasjonspunktet ditt:
kosmos.mail.recipient=nokon@domenet-ditt.no
kosmos.mail.from=ikkjesvar@domenet-ditt.no

spring.mail.host=<adressa-til-smtp-servaren-din>
spring.mail.port=<porten-på-servaren-din>

Andre antakingar i oppsettet i denne seksjonen

• KOSMOS og Integrasjonspunktet sine JAR-filer er plasserte i samme mappe
• Den offentlege nøkkelen til GPG-signeringssertifikat ligg i samme mappe

Køyra KOSMOS og Integrasjonspunktet frå forskjellige mapper

Det anbefalte oppsettet (treng mindre konfigurasjon) er å ha både KOSMOS- og Integrasjonspunkt-JAR-filene i samme mappe. Dersom ein skulle føretrekka å køyra applikasjonane frå forskjellige mapper, må følgande innstillingar leggast til:

1. I kosmos-local.properties:

   kosmos.integrasjonspunkt.home={sti-til-mappa-der-integrasjonspunktet-køyrer}
   

2. I XML-konfigurasjonsfila for WinSW: ```

### Køyra KOSMOS på Linux
Ein kan nytta den samme konfigurasjonsfila som i førre seksjon. Følgande filer bør vera på plass i installasjonsmappa:

* kosmos-local.properties
* kosmos.jar
* integrasjonspunkt-local.properties
* integrasjonspunkt-keystore.jks (di eiga JKS som Integrasjonspunktet nyttar)
* eformidling-key.asc (kan finnast [HER](https://docs.digdir.no/eformidling_auto_update.html#verifisere-sertifikatet))

Ein kan velja mellom å køyra i noverande skal eller som oppgåve vha. desse kommandoane:
1. Køyra i noverande skal med staging-profil:

java -jar kosmos-x.y.z.jar -Dspring.profiles.active=staging -Dspring.config.additional-location=file:%BASE%\integrasjonspunkt-local.properties

2. Køyra som oppgåve med staging-profil:

java -jar kosmos-x.y.z.jar -Dspring.profiles.active=staging -Dspring.config.additional-location=file:%BASE%\integrasjonspunkt-local.properties & ```

• For å køyra med produksjonsprofil: Erstatt ‘staging’ med ‘production’ i linjene ovanfor.

Når denne kommandoen er køyrt, vert PID-en til processen returnert. Denne kan nyttast dersom du treng å stoppa prosessen. (Kan også finnast vha. htop eller top.) Integrasjonspunktet startar som ein eigen Java-prosess.

Kjeldekode

KOSMOS’ kjeldekode er tilgjengeleg på GitHub.

Neste steg

• Sikkerhetskopi (anbefalt)
• Overvåking (anbefalt)