Introduktion

Denne side beskriver hvordan man som leverandør til NSP anvender de værktøjer SDS stiller til rådighed i CI/CD sammenhængfor Continuous Integration & Delivery. Der er både nogle best practices, samt nogle forventninger krav til de enkelte leverancer der skal være opfyldt, for at både leverandør, QAkvalitetssikring, drift driften og anvendere anvenderene kan få mest mulig glæde af leverancerne.

...

Begreberne handler i NSP sammenhæng om at der for CI-delen ønskes hurtige tilbagemeldinger og en høj grad af inddragelse af leverandøren i selve miljøet, uden at bryde de governance regler der gælder for platformen. Leverandøren har således selv mulighed for at definere samt overvåge byg af egne komponenter. For CD-delen handler det om at have en så gnidningsfri overlevering fra leverandør og hele vejen til drift, hvorfor der i dette projekt er blevet defineret nogle afleveringsforretningerleverancekrav, der kan anvendes på tværs af leverandører og sikrer, at der er mindst mulig vej fra leverandør til drift, igen med henblik på de gældende regler. Med dette udgangspunkt er leverandøren således selv med til at definere deployment-tekniske dele af egne komponentetkomponenter. Yderligere har man som leverandør også mulighed for nemt at hente andre (egne såvel som andre leverandøreres) komponenter og afvikle disse i testsammenhæng.

Leverance pipeline

Afsnittet her beskriver de skridt der foretages helt fra idé til idriftsættelse for NSP leverancer fremover. 

Kildekoden oprettes/ændres i svn.nspop.dk/svn/components/<komponent-navn> (herunder ligger trunk, tags og branches). 

Når leverandøren mener at have implementeret kodeændringerne laves et release og der oprettes et tag i svn, med den version, der findes i på de pågældende sager i Jira. Herefter bygger og idriftsætter NSP. Bygget foregår på NSP CI-miljøet, der pt. findes på jenkins.nspop.dk. De enkelte leverandører har selv adgang til en række jobs herunder og forventes at kunne se/afvikle disse imod trunk af deres svn repositories.

For hver komponent knytter sig et antal jobs i CI-miljøet. Nogle af disse kan afvikles af leverandøren, nogle kan afvikles af NSP. Produktet af disse byggejobs er et/flere docker images, som deponeres på NSP docker registry'et. Dette findes på registry.nspop.dk. 

Enhver har mulighed for at pull'e images fra NSP docker registryet. Leverandøren leverer opskrifter til at starte komponenten i en testkonfiguration med de nødvendige afhængigheder. Dette sker via compose-filer i en fastlagt directory-struktur under komponentens kodebase.

I det følgende er et overbliksdiagram over leverance pipelinen.

De værktøjer der anvendes af toolchain'en er således, Jenkins, VMware Harbor, Docker, Docker Compose, Maven og svn. Slack anvendes til div. notifikationer fra CI-miljøet, SDS, QA og driften, så her kan man også forvente både spørgsmål, svar og notifikationer fra miljøet.

Leverancer af support/vedligehold

Ændringer til NSP-platformen opstår og håndteres af SDS i Jira på jira.nspop.dk. Man kan således forvente som leverandør at der er nogle givne sager man skal foretage en leverance af - issue-tracking og kommunikation med NSP foregår på de enkelte issues i jira. Når en sag er klar til udvikling findes der en versions på det issue ændringen knytter sig til.

Leverancer af projekter

Her kan aftales separate projekter under jira.nspop.dk, således leverandøren selv styrer issuetracking osv. efter aftale med NSP. De første leverancer koordineres med NSP via OAT processen. Det er altid muligt at få release candidates deployet til test1, ved at oprette/release et RC-tag af kodebasen, dvs "release-1.0.10RC".

Brug af kode repository

Til de komponenter der findes på svn.nspop.dk/svn/components er der nogle forventninger til indholdet af. Disse findes for at have en ensretning på kodebasen og yderligere ensretning af leverancerne til driften. Derudover er det også et værktøj til udviklerne selv, da det giver mulighed for hurtigere feedback på deres kodeændringer. Adgang til kode repository'et, oprettelse af helt nye brugere i LDAP til brug for CI-miljøet, Jira, svn etc gives af NSP.

Repository'et oprettes med hhv trunk, branches og tags foldere. Under tags forventes navngivningen at være release-<release nummer x.y.z> - release nummeret bliver brugt til at tagge docker imaget i registry'et med automatisk.

Såfremt koden er opdelt i forskellige deployables bør dockerfilerne for de enkelte services også bo under modulerne.

Jenkins pipeline fil

I roden af kodebasen skal der findes en groovy-fil kaldet "Jenkinsfile". Denne indeholder opskriften på at bygge komponenten i NSP CI-miljøet. Denne fil er leverandørens "indgang" til byggejobbet. NSP sørger for at opsætte jobs, der anvender denne fil til byg og sikrer at de nødvendige afviklingsrettigheder er tilstede for leverandøren. I udgangspunktet bliver disse jobs sat op til at bygge komponenten så snart der detekteres kodeændringer under /trunk. 

For referencer til pipelinesyntaksen kan følgende læses: https://jenkins.io/doc/book/pipeline/syntax/ der anvendes scriptede pipelinefiler.

I det følgende er der beskrevet, hvad jenkinsfilen forventes at indeholde. 

Byg af kode

Under pipeline filen skal selve koderepository'et bygges. Hertil stiller NSP et docker-image til rådighed, med de værktøjer der pt. skal bygges med. Til testformål kan dette image hentes og bruges lokalt. Pipeline filen skal således gøre brug af dette image til byg, idet selve CI-maskinen ikke kan forventes at indeholde hverken den korrekte version af java, maven el. lign.

Byg af docker image(s)

Efter selve bygget af de java deployables projektet indeholder skal pipelinefilen indeholde et byg af et eller flere dockerimages, som er leverandørens opskrift på hvordan deres komponent skal deployes. NSP stiller et platforms image til rådighed, hvor  sikkerhedskomponenter og NSP-deployment-tekniske afhængigheder er på plads. Dette image skal bruges som udgangspunkt for det image leverandøren bygger. Resultatet af dette skal være et docker-image, som indeholder den byggede komponent og det statiske konfiguration, der måtte skulle til - konfiguration der forventes ændringer til baseret på miljø osv. håndteres særskilt. Leverandørerne får således et godt indblik i hvordan netop deres komponent kommer til at blive driftet, idet det er nøjagtig samme docker image, der bliver afviklet af QA og driften. Gældende husregler for konfiguration og afhængigheder skal naturligvis stadig overholdes.

Dockerimages der skal driftes på platformen skal derfor altid, med mindre andet er aftalt, tage udgangspunkt i

registry.nspop.dk/platform/nsp:<version>

Ved release skal den seneste version af platformen altid anvendes, denne kan findes på registry.nspop.dk - de forskellige tags er for nuværende ikke 100% immutable, da mindre opdateringer, der for komponenterne er irrelevante kan medføre nye udgaver af versionen. Ved større ændringer, hvor det forventes at kunne have indflydelse, skifter versionsnummeret.

For referencedokumentation til Dockerfiles kan følgende læses: https://docs.docker.com/engine/reference/builder/

Yderligere

Code-coverage rapporter samt testrapporter skal også være inkluderet i pipelinefilen.

Desuden kan også lade sig gøre at notificere via slack, hvis byggejobbet går skævt og leverandøren skal underettes.

Opsætning af Jenkins

Som sådan har NSP jenkins ingen maven eller jdk til bygning af java-artefakterne. Derfor skal al byg ske igennem et nspbuilder-image. Dette findes i flere udgaver, men for nuværende er registry.nspop.dk/platform/nspbuilder:jdk8 default byggeimage. Dette kan til enhver tid hentes af leverandøren og anvendes lokalt.

For hver komponent opsættes 4 jobs til byg samt deploy. Her tages udgangspunkt i NCC eksempel-koden

...

Dette job starter et release-build job og pusher efterfølgende til registryet, med :<x.y.z> tag

Principperne der ligger til grund for CI/CD på NSP er følgende

·         Commit code frequently

·         Don’t commit broken code

·         Fix broken builds immediately

·         Write automated developer tests

·         All tests and inspections must pass

·         Run private builds

·         Avoid getting broken code

Leverance pipeline

Afsnittet her beskriver de skridt der foretages helt fra idé til idriftsættelse for NSP leverancer. 

Værktøjerne der indgår i NSP toolchain'en er følgende: Jenkins, VMware Harbor, Docker, Docker Compose, Maven og svn. Slack anvendes til div. notifikationer fra CI-miljøet, SDS, QA og driften, så her kan man også forvente både spørgsmål, svar og notifikationer fra miljøet. Issuetracking foregår i Jira.

Kildekoden oprettes/ændres i svn.nspop.dk/svn/components/<komponent-navn> (herunder ligger trunk, tags og branches). 

Når leverandøren mener at have implementeret kodeændringerne laves et release og der oprettes et tag i svn, med den version, der findes i på de pågældende sager i Jira. Herefter bygger og idriftsætter NSP. Bygget foregår på NSP CI-miljøet, der pt. findes på jenkins.nspop.dk. De enkelte leverandører har selv adgang til en række jobs herunder og forventes at kunne se/afvikle disse imod deres svn repositories.

For hver komponent knytter sig et antal jobs i CI-miljøet. Nogle af disse kan afvikles af leverandøren, nogle kan afvikles af NSP. Produktet af disse byggejobs er et/flere docker images, som deponeres på NSP docker registry'et. Dette findes på registry.nspop.dk. 

Yderligere produceres der ved byg af et release en docker-compose jinja2 template, som driften anvender sammen med deres deployment ansible kode. Dette er pt. ikke offentlig tilgængeligt.

Enhver har mulighed for at pull'e images fra NSP docker registry'et. Leverandøren leverer opskrifter til at starte komponenten i en testkonfiguration med de nødvendige afhængigheder. Dette sker via compose-filer i en fastlagt directory-struktur under komponentens kodebase.

I CI-miljøet opsættes yderligere jobs til at afvikle integrationstests imod en kørende komponent. Disse kan afvikles af NSP imod deployede komponenter på testsystemerne og anvendes til automatisk at afgøre om en komponent er i en tilstand så den kan flytter videre i testmiljøerne eller sættes i produktion.

I det følgende er et overbliksdiagram over leverance pipelinen.

Herunder ses et eksempel på et release-push job på CI-miljøet.

Image Added

Opstart af nyt projekt

Ved opstart af et nyt kodeprojekt initierer projektet kontakten til NSP ang. hvem der skal have adgang til NSP udviklingsmiljøet.

Adgang til kode repository'et, oprettelse af brugere i LDAP til brug for CI-miljøet, Jira, svn etc gives af NSP. 

De enkelte udviklere skal have installeret docker på udviklermaskinerne, således de images NSP stiller til rådighed kan anvendes i den daglige udvikling og til test.

Initiel Opsætning af tool chain

NSP laver et repository til det enkelte projekt under svn.nspop.dk/svn/components, samt oprtter de initielle foldere herunder.

Efter aftale med projektet opsætter NSP også adgang og jobs på jenkins.nspop.dk - yderligere opsættes også en slack kanal til notifikationer fra CI-miljøet til projektet/leverandøren.

Opsætning af Jenkins - NSP

For hver komponent opsættes 4 jobs til byg samt deploy. Her tages udgangspunkt i NCC eksempel-koden

Jenkins pipeline fil - leverandøren

Efter opsætning af jenkins, skal leverandøren lave en pipeline fil, beskrivende afviklingen af bygget.

Denne indeholder opskriften på at bygge komponenten i NSP CI-miljøet. Denne fil er leverandørens "indgang" til byggejobbet. NSP sørger for at opsætte jobs, der anvender denne fil til byg og sikrer at de nødvendige afviklingsrettigheder er til stede for leverandøren. I udgangspunktet bliver disse jobs sat op til at bygge komponenten så snart der detekteres kodeændringer under /trunk. 

For referencer til pipelinesyntaksen kan følgende læses: https://jenkins.io/doc/book/pipeline/syntax/ der anvendes scriptede pipelinefiler.

I det følgende er der beskrevet, hvad jenkinsfilen forventes at indeholde. 

Byg af kode

Under pipeline filen skal selve koderepository'et bygges. Hertil stilles NSP Docker Build image til rådighed, med de værktøjer der pt. skal bygges med.

Til testformål kan dette image hentes og bruges lokalt. Pipeline filen skal således gøre brug af dette image til byg, idet selve CI-maskinen ikke kan forventes at indeholde hverken den korrekte version af java, maven el. lign.

Byg af docker image(s)

Efter selve bygget af de java deployables projektet indeholder skal pipelinefilen indeholde et byg af et eller flere dockerimages, som er leverandørens opskrift på hvordan deres komponent skal deployes. NSP stiller et platforms image til rådighed, hvor  sikkerhedskomponenter og NSP-deployment-tekniske afhængigheder er på plads.

registry.nspop.dk/platform/nsp:<version>

Resultatet af docker bygget skal være et docker-image, som indeholder den byggede komponent og det statiske konfiguration, der måtte skulle til (module.xml, deployables etc).

konfiguration der forventes ændringer til baseret på miljø osv. håndteres særskilt (keystores, datasource-filet etc.).

Leverandørerne får således et godt indblik i hvordan netop deres komponent kommer til at blive driftet, idet det er nøjagtig samme docker image, der bliver afviklet af QA og driften. Gældende husregler for konfiguration og afhængigheder skal naturligvis stadig overholdes.

For referencedokumentation til Dockerfiles kan følgende læses: https://docs.docker.com/engine/reference/builder/

Yderligere

Pipelinefilen har også muligheder for at definere codecoverage samt notifikationer om fejlede byg.

Desuden kan også lade sig gøre at notificere via slack, hvis byggejobbet går skævt og leverandøren skal underettes.

Opsætning af kode repository

Struktur

For hver komponent skal der være en compose folder under roden af repository'et. Folderen skal indeholde en docker-compose fil, der udtaler sig om hvordan komponenten startes i testsammenhæng og een der udtaler sig om hvordan komponenten startes, når denne skal deployes i NSP miljøerne. Yderligere kan man som leverandør have stor fordel af at lave en development compose-fil, som kan anvendes i udviklingsammenhæng (med mulighed for at mappe stier til deployment af war-filer og specificere hvor dockerfiler findes til build øjemed). 

For referencedokumentation omkring compose-filer kan følgende læses: https://docs.docker.com/compose/compose-file/

Indhold af compose folder

Environment variable i compose-filerne er tilladte og jo mere konfiguration der kan flyttes derover jo bedre.

Dagligt udviklingsarbejde, commit og test

I det daglige arbejde forventes udviklerne at anvende docker til udvikling og aftestning, således at det setup der leveres også er det er lokalt testes på og verificeres op imod. Afvikling imod de containere der driftes sikrer størst mulig træfsikkerhed, når der skal laves rettelser. Yderligere sikrer anvendelsen af docker-compose setuppet også at der ikke glemmes konfiguration el. lign. ved release, som hvis der fx deployes til en lokal wildfly uden NSP sikkerhedskomponenter eller afvikling imod en database med indhold, der ikke er defineret i det setup der leveres til NSP.

Koderepositoryet på svn.nspop.dk/svn/components anvendes som primært repository og udstilles også for offentligheden. CI-miljøet bygger dagligt eller pr. commit fra trunk og det forventes at man umiddelbart reparerer fejlende builds.

Test

Selve bygget i maven skal kunne afvikles med unittests i NSPbuilder-imaget. 

Leverance til QA/PROD

Ved release skal den seneste version af platformen altid anvendes, denne kan findes på registry.nspop.dk - de forskellige tags er for nuværende ikke immutable, da mindre opdateringer, der for komponenterne er irrelevante kan medføre nye udgaver af versionen. Ved større ændringer, hvor det forventes at kunne have indflydelse, skifter versionsnummeret.

Under tags i koderepository'et forventes navngivningen at være <kort komponentnavn>-<release nummer x.y.z> - release nummeret bliver brugt til at tagge docker imaget i registry'et med automatisk.

Såfremt koden er opdelt i forskellige deployables bør dockerfilerne for de enkelte services også bo under modulerne.

Det er altid muligt at få release candidates deployet til test1, ved at oprette/release et rc-tag af kodebasen, dvs "<kort-komponent-navn>-x.y.zrc".

Ved aflevering af en leverance til QA, forventes man at have afviklet en integrationstest imod docker-compose test-setuppet. Dette sikrer en mere friktionsfri deployment til test1

Compose folder

For hver komponent skal der ligeledes være en compose folder under roden af repository'et. Folderen skal indeholde en docker-compose fil, der udtaler sig om hvordan komponenten startes i testsammenhæng og een der udtaler sig om hvordan komponenten startes, når denne skal deployes i NSP miljøerne. Yderligere kan man som leverandør have stor fordel af at lave en development compose-fil, som kan anvendes i udviklingsammenhæng (med mulighed for at mappe stier til deployment af war-filer og specificere hvor dockerfiler findes til build øjemed). 

For referencedokumentation omkring compose-filer kan følgende læses: https://docs.docker.com/compose/compose-file/

Indhold af compose folder

...

Environment variable i compose-filerne er tilladte og jo mere konfiguration der kan flyttes derover jo bedre.

Eksempler

NCC

Der er til formålet konstrueret eksempelkode under NCC (NSP Containerized Component) - dette findes her: https://svn.nspop.dk/svn/components/ncc/ 

I NCC koden findes eksempler på hvordan koderepository'et bør struktureres, indhold af jenkins-byggefilen, samt en dockerfil. Yderligere bliver denne også releaset og deployet til test1 og indeholder derfor eksempler på funktionelle test-docker-compose-filer.

Repository indhold

Indhold i kode repository'et:

Jenkinsfile

Indholdet af jenkinsfilen kan der ses et eksempel på her. De to variable NSPBUILDER samt REGISTRYTAG oprettes af NSP i opsætningen af byggejobbet:

#!groovy

node {
  try {
    stage('Checkout') {
      checkout scm
    }

    stage('Build') { 
      //This will resolve to docker.image('registry.nspop.dk/platform/nspbuilder:jdk8').inside(){{ 
      docker.image("registry.nspop.dk/tools/nspbuilder:${NSPBUILDER_TAG}").inside(){
        sh "mvn -B clean install"
      }
    }

    stage ('Archive') {
      //This will resolve to docker.build('"registry.nspop.dk/components/ncc:build'${DOCKERTAG}", '--pull .')
      docker.build("${REGISTRYTAG}", '--pull--build-arg BASE_TAG=${NSP_BASE_TAG} .')
    }

  } catch (err) {
    //slackSend channel: '<channelname>', color: 'bad', message: "${env.JOB_NAME} ${env.BUILD_NUMBER} - Build failed ... (<${env.BUILD_URL}|Open>)", tokenCredentialId: 'Slack-Token'
    throw err
  } finally {
    stage ('Clean') {
      deleteDir()
    }
  }
}

Dockerfile

Eksempel på dockerfil:

ARG BASE_TAG=latest
FROM registry.nspop.dk/platform/nsp:1${BASE_TAG}

# Copy configuration files to the module directory
RUN mkdir -p /pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/
COPY etc/module.xml /pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/

# Copy the war file to the deployment directory
COPY target/ncc.war /pack/wildfly8wildfly/standalone/deployments/

compose-filer

Eksempel på test compose-fil

version: "3.6"

networks:
  nsp_net:
    external: true
  ncc_net:
    external: false

services:
  cradb:
    image: registry.nspop.dk/playground/cradb:latest
    networks:
      - ncc_net
    environment:
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
  nccdb:
    image: mariadb:latest
    networks:
      - ncc_net
    environment:
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
    volumes:
      - ../database/01_create_db.sql:/docker-entrypoint-initdb.d/01_create_db.sql
  ncc:
    image: registry.nspop.dk/components/ncc:1.0.9
    ports:
      - "8080"
    depends_on:
      - cradb
      - nccdb
    networks:
      - nsp_net
      - ncc_net
    environment:
      - LOG_MAX_FILE_SIZE=10MB
      - LOG_MAX_BACKUP_INDEX=5
    volumes:
      - ../configuration/ncc.properties:/pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/ncc.properties
      - ../configuration/log4j-ncc.xml:/pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/log4j-ncc.xml
      - ../configuration/ncc-ds.xml:/pack/wildfly8wildfly/standalone/deployments/ncc-ds.xml

...

version: "3.6"

services:
  ncc:
    image: registry.nspop.dk/components/ncc:1.0.9snapshot
    volumes:
      - ../configuration/ncc.properties:/pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/ncc.properties
      - ../configuration/log4j-ncc.xml:/pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/log4j-ncc.xml
      - ../configuration/ncc-ds.xml:/pack/wildfly8wildfly/standalone/deployments/ncc-ds.xml

...

version: '3.6'
services:
  ncc:
    image: registry.nspop.dk/components/ncc:1.0.9
    volumes:
    - ../configuration/ncc.properties:/pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/ncc.properties
    - ../configuration/log4j-ncc.xml:/pack/wildfly8wildfly/modules/dk/sds/nsp/examples/ncc/main/log4j-ncc.xml
    - ../configuration/ncc-ds.xml:/pack/wildfly8wildfly/standalone/deployments/ncc-ds.xml
    - /pack/log/ncc:/pack/wildfly8wildfly/standalone/log
    container_name: '{{ comp_ncc_container_name }}'
    restart: unless-stopped
    ports:
    - '{{ comp_ncc_port }}:8080'
    environment:
    - LOG_MAX_FILE_SIZE=10MB
    - LOG_MAX_BACKUP_INDEX=5
    - CRA_SERVER={{ comp_ncc_cra_dbserver }}
    - CRA_USER={{ comp_ncc_cra_dbuser }}
    - CRA_PWD={{ comp_ncc_cra_dbpassword }}

...