Gå til hovedinnhold

1 Rutiner for bygging og utrulling av FS-plattform-applikasjonen

Her beskriver vi hvordan du går fram for å bygge og rulle ut nye versjoner av FS-plattformen. Når en endring blir merget inn i main-branchen-settes det automatisk i gang en GitLab-pipeline, som bygger og ruller ut en ny versjon til utv-miljøet (https://api-utv.fellesstudentsystem.no). Den samme pipelinen benyttes for å rulle versjonen videre ut til test og produksjon. Vi har også et oppsett der versjonen som er bygd av GitLab rulles ut via Jenkins, men dette er under utfasing.

1.1 Finn riktig pipeline

For å starte utrulling til test og produksjon, må du først finne riktig pipeline i GitLab. Dette gjør du enklest ved å gå til https://gitlab.sikt.no/fs/fs-plattform/-/pipelines?page=1&scope=branches&ref=main. Der skal du finne en pipeline for den siste endringen som ble flettet inn i main. Dersom den allerede har blitt deployet til utv-miljøet skal den ha status "blocked", fordi den venter på input fra deg.

1.2 Rulle ut nye versjoner via GitLab​

Nye versjoner rulles ut via GitLab CI/CD. Det er foreløpig en del manuelle steg i denne prosessen, men det er lagt inn sjekker som gjør at det ikke skal være mulig å gjøre ting i feil rekkefølge.

1.2.1 Finn ut hvilken farge som er online​

Vi har applikasjoner i test og produksjon til enhver tid, green og blue, én online og én offline. Klikk på knappen med tannhjul og teksten "blocked" for å komme inn på pipelinen. I første kolonne gjøres det en sjekk på hvilken farge som var online på det tidspunktet pipelinen ble startet (er du i tvil om den fortsatt gjelder, kan du klikke på sirkel-pilene for å kjøre steget på nytt). Du vil se en grønn hake ved siden av den som er online, og et utropstegn ved siden av den som er offline. Du skal deploye til den fargen som er offline.

1.2.2 Rull ut databasen​

Gå nå til neste kolonne og trykk på update-test-db-knappen for den fargen du skal rulle ut til. Den ekspanderer, og du må trykke på hver database for seg for å sette i gang utrulling av databasekode. Du må gjerne rulle ut til alle databasene i parallell.

1.2.3 Rull ut applikasjonen​

Når alle databasene er oppdatert kan du gå til neste kolonne og klikke på knappen for å deploye appen til riktig farge. NB!

1.3 Flippe mellom green og blue i test og produksjon i Gravitee​

I test- og produksjonsmiljøene har vi som nevnt to instanser av APIet, kalt blue og green. Blue skal normalt være online, og green skal normalt være offline. Dette administreres i Gravitee: https://api-mgmt-sikt.intark.uh-it.no/.

For å få tilgang til dette grensesnittet, må du ligge i en tilgangsgruppe. Er du Sikt-ansatt kan du be om tilgang i slack- kanalen # fs-plattform-api-utvikling. Er du ikke Sikt-ansatt, og mener du skal ha tilgang, kontakt FS-support.

Utrulling foregår slik:

  1. Sjekk hvilket miljø som er online akkurat nå: Velg APIs i venstre-menyen. Klikk på GEMINI-TEST for test-miljøet eller GEMINI-PROD for prod-miljøet. Velg deretter Proxy og Backend Services -> Endpoints i venstremenyen. I grensesnittet som kommer opp vil den instansen som er offline vises i lys grå kursiv-skrift, mens den som er online vises i mørk grå uten kursiv.
  2. Rull ut til den instansen som er offline via Jenkins (se 1.3 over)
  3. Hvis alt gikk fint, klikk på den instansen som er offline. Fjern krysset for "Secondary endpoint" og klikk Save. Gå tilbake til oversikten, velg den andre instansen. Kryss av for "Secondary endpoint" og klikk Save. Du får nå opp et brunt banner øverst på siden hvor det står at APIet ditt ikke lenger er i sync. Klikk på lenken "Deploy API" for at de nye innstillingene skal ta effekt.
  4. Rull ut til den andre instansen via Jenkins.
  5. Hvis alt gikk fint, gjenta trinn 3.

1.4 Oppdatere Changelog ved release av nye versjoner​

Når en ny versjon av FS-plattformen blir lagt ut i test og produksjon, er det viktig å oppdatere release-notes for den nye versjonen. Releasenotes ligger foreløpig i Vortex, og kan endres her:

Den som legger ut ny versjon, er ansvarlig for at alle endringer i FS GraphQL API siden forrige deploy er dokumentert.

Endringer i Gemini blir dokumentert ved behov av team Oppfølging, så andre team kan overse disse.

For FS GraphQL API har vi et bash-script schema-diff.sh som vi kan kjøre, for å sammenligne forskjellige versjoner av GraphQL-skjemaet til FS GrahpQL API. Scriptet ligger under
/scripts/ i FS-plattform-prosjektet (se readme-fila for detaljer om installasjon før første gangs bruk).

Scriptet lister ut differansen mellom de to skjemaene, og angir om endringen er bakoverkompatibel, bakoverinkompatibel eller "farlig", det vil si bakoverinkompatibel avhengig av hvordan den blir brukt. Listen blir oversatt til norsk av scriptet, men det kan være lurt å se over, da det av og til kommer tekst som ikke blir oversatt riktig. Kopier ut teksten og lim inn på riktig sted i endringsloggen i Vortex.

På sikt skal denne sammenligningen kjøres i pipelinen, slik at changelogen blir oppdatert automatisk.

2 Konfigurasjon av pipelinen

Her finner du mer detaljert informasjon om konfigurasjonen av de forskjelle leddene i pipelinen.

2.1 GitLab CI/CD​

Konfigurasjon for GitLab CI/CD ligger i .gitlab-ci.yml.

2.2 Artifactory​

Hovedartefakten er fsapi-rest-2.build.xyz.abcdef.war. Versjoner bygget fra main-branchen blir publisert til https://artifactory.sikt.no/ui/native/libs-releases/no/fellesstudentsystem/fsapi-rest/. Versjoner bygd fra en branch eller fra en merge-request havner i https://artifactory.sikt.no/ui/native/libs-snapshots-local/no/fellesstudentsystem/fsapi-rest/.

2. Gravitee​

Mer informasjon vil komme etter hvert.