1. Introduktion

1.1. Formål

Dette dokument indeholder en beskrivelse af hvordan National Adviseringsservice 2 (herefter NAS2) driftes på et NSP Backend miljø.

1.2. Læsevejledning

Læseren forventes at have kendskab til Sundhedsdatastyrelsens platform NSP, samt generelt kendskab til WildFly applikation server, Docker, Docker Compose samt Ubuntu Linux operativ system.

1.3. Dokument Historik

DatoAnsvarligBeskrivelse
TBDJacob QvortrupDraft udgave af driftvejledningen
2020-10-30Jonas PedersenTilføjet max batch størrelse ved id list oprettelse
2020-12-14Jonas PedersenTilføjet nye properties til pullpoint service.
2020-12-17Jonas Pedersen

Tilføjet ny propery til pullpoint service og beskrevet ny statistik log.

2021-02-10Tenna RasmussenTilføjet beskrivelse af topic access
2021-03-10Tenna RasmussenTilføjet ny property til notification service og beskrevet ny statistik log.
2021-04-16Jonas PedersenTilføjet ny property liquibase.changelog.file.
2021-10-08Jonas PedersenTilfæjet administration service

1.4. Definitioner og referencer

ReferenceBeskrivelse
NAS2National Adviseringsservice 2
NAS1National Adviseringsservice 1
NSPDen nationale service platform
DriftenNSP Leverandøren og NSP Driftleverandøren
SDSSundhedsdatastyrelsen
InstallationsvejledningNAS2 - Installationsvejledning

2. Konfiguration

Konfiguration af NAS2 sker i filerne i "compose/configuration" mappen som beskrevet i installationsvejledningen. I det følgende gennemgåes hver enkelt services konfigurationsfiler i detaljer.

2.1. Notification Broker service

Denne service konfigureres i filerne "notificationbroker.properties" og "log4j-notificationbroker.xml".

2.1.1. notificationbroker.properties

PropertyBeskrivelse
kafka.producer.bootstrap.serversKommasepareret liste af Kafka servere som NAS2 skal anvende. Denne liste bør indeholde alle noderne i Kafka clusteret
kafka.producer.client.idNavnet som NAS2 vil fremgå med i listen af Producers på et Kafka Cluster.
nsp.kafka.producer.component.nameNavnet på NAS2 komponenten
nsp.kafka.producer.component.abbreviationKort navn på NAS2 komponenten
nsp.kafka.producer.component.versionVersionen af NAS2 komponenten
nsp.kafka.producer.service.nameNavnet på den service i NAS2 der anvender Kafka
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
app.endpointService endpoint (anvendes i DKS servlet)
dgws.headers.required

Sættes til 'true' eller 'false' alt efter om DGWS beskyttelse er påkrævet eller optionelt. 

Alle properties der starter med "kafka.producer." vil blive givet videre til NSP Kafka Clients API'et og derved videre til Kafka Clients. Det er derved muligt at konfigurere alle aspekter af Kafka klienten som måtte være ønsket, blot ved at tilføje nye properties. Hvis f.eks. Kafka konfigurationen "abc" skulle sætte til "42" så tilføjes blot linien "kafka.producer.abc=42".

2.1.2. log4j-notificationbroker.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.2. ID List service

Denne service konfigureres i filerne "idlist.properties" og "log4j-idlist.xml"

2.2.1. idlist.properties

PropertyBeskrivelse
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
app.endpointService endpoint (anvendes i DKS servlet)
create.max.batch.sizeMax antal entries i SQL batch update når der oprettes og opdateres id lister.

2.2.2. log4j-idlist.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.3. Subscription Manager service

Denne service konfigureres i filerne "subscriptionmanager.properties" og "log4j-subscriptionmanager.xml"

2.3.1. subscriptionmanager.properties

PropertyBeskrivelse
kafka.consumer.bootstrap.serversKommasepareret liste af Kafka servere som NAS2 skal anvende. Denne liste bør indeholde alle noderne i Kafka clusteret
kafka.consumer.client.idNavnet som NAS2 vil fremgå med i listen af Consumers på et Kafka Cluster.
nsp.kafka.consumer.component.nameNavnet på NAS2 komponenten
nsp.kafka.consumer.component.abbreviationKort navn på NAS2 komponenten
nsp.kafka.consumer.component.versionVersionen af NAS2 komponenten
nsp.kafka.consumer.service.nameNavnet på den service i NAS2 der anvender Kafka
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
app.endpointService endpoint (anvendes i DKS servlet)
pullpoint.app.endpoint.regexRegex udtryk for service endpoint for pull point servicen. Anvendes til at validere korrekt format af pullpoint. F.eks.: https?://localhost:\\d{1,5}/pullpoint/service/
liquibase.changelog.fileAngiver hvilken changelog fil som liquibase skal anvendes. Property er ikke krævet. Hvis der skal afvikles integrationstest mod det miljø der installeres skal denne sættes til liquibase-changelog-test.xml. Denne kan også sættes via en environmentvariabel i formen liquibase_changelog_file.

2.3.2. log4j-subscriptionmanager.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.4. Pullpoint Factory service

Denne service konfigureres i filerne "pullpointfactory.properties" og "log4j-pullpointfactory.xml"

2.4.1. pullpointfactory.properties

PropertyBeskrivelse
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
app.endpointService endpoint (anvendes i DKS servlet)
pullpoint.app.endpointService endpoint for pull point servicen. Anvendes til at validere korrekt format af pullpoint.
liquibase.changelog.fileAngiver hvilken changelog fil som liquibase skal anvendes. Property er ikke krævet. Hvis der skal afvikles integrationstest mod det miljø der installeres skal denne sættes til liquibase-changelog-test.xml. Denne kan også sættes via en environmentvariabel i formen liquibase_changelog_file.

2.4.2. log4j-pullpointfactory.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.5. Pullpoint service

Denne service konfigureres i filerne "pullpoint.properties" og "log4j-pullpoint.xml"

2.5.1. pullpoint.properties

PropertyBeskrivelse
kafka.consumer.bootstrap.serversKommasepareret liste af Kafka servere som NAS2 skal anvende. Denne liste bør indeholde alle noderne i Kafka clusteret
kafka.consumer.client.idNavnet som NAS2 vil fremgå med i listen af Consumers på et Kafka Cluster.
nsp.kafka.consumer.component.nameNavnet på NAS2 komponenten
nsp.kafka.consumer.component.abbreviationKort navn på NAS2 komponenten
nsp.kafka.consumer.component.versionVersionen af NAS2 komponenten
nsp.kafka.consumer.service.nameNavnet på den service i NAS2 der anvender Kafka
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
app.endpointService endpoint (anvendes i DKS servlet)

kafka.poll.catchup.timeout

Kafka poll timeout der anvendes når en subscription er kommet for langt bagud i forhold til kafka.poll.delta.max. Format er beskrevet på https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-

kafka.poll.delta.max

Maksimal offset difference mellem subscription og partitionerne i det topic der skal læses før "catch up" mode anvendes og kafka.poll.catchup.timout anvendes som timeout til poll i Kafka.

kafka.polls.max.time

Maksimal tid der må anvendes i til poll i Kafka (sum af poll kald + iterering over resultat). Format beskrevet på https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-

statistik.offset.delta.minimum

Minimum offset mellem offset i Kafka Partition og offset for subscription før der laves "offsets" statistiklog.
liquibase.changelog.fileAngiver hvilken changelog fil som liquibase skal anvendes. Property er ikke krævet. Hvis der skal afvikles integrationstest mod det miljø der installeres skal denne sættes til liquibase-changelog-test.xml. Denne kan også sættes via en environmentvariabel i formen liquibase_changelog_file.

2.5.2. log4j-pullpoint.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.6. Cleanup service

Denne service konfigureres i filerne "cleanup.properties" og "log4j-cleanup.xml"

2.6.1. cleanup.properties

PropertyBeskrivelse
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
ageDen maksimale alder for et abonnement før det kommer i betragtning for oprydning. Format er beskrevet på https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-
liquibase.changelog.fileAngiver hvilken changelog fil som liquibase skal anvendes. Property er ikke krævet. Hvis der skal afvikles integrationstest mod det miljø der installeres skal denne sættes til liquibase-changelog-test.xml. Denne kan også sættes via en environmentvariabel i formen liquibase_changelog_file.
delete.batch.sizeAntal nasconsumers, der slettes i ét batch ved cleanup. Begrænses for at undgå at 'låse' databasen for længe ad gangen ved cleanup. 

2.6.2. log4j-cleanup.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.7. Administration service

Denne service konfigureres i filerne "administration.properties" og "log4j-administration.xml"

2.7.1. cleanup.properties

PropertyBeskrivelse
datasource.jndiJNDI navnet på den datasource der giver adgang til NAS2 databasen.
app.endpointService endpoint (anvendes i OpenAPI specifikationen).

2.7.2. log4j-cleanup.xml

Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.

2.8. Database

Adgang til NAS2 databasen styres gennem filen "nas-ds.xml" - Denne skal matche det NSP miljø hvor komponenten afvikles i.

2.9. Kafka

NAS2 skal anvender NSP Kafka Clusteret på NSP Backend miljøet. Der kræves ikke nogen særlig opsætning af Kafka i forhold til det eksisterende NSP Kafka Cluster.

3. Administration af topics i NAS2

I det følgende gennemgåes de manuelle aktiviteter der skal ske i databasen og i Kafka ifm driften af NAS2. 
Til at administrere topics og adgang til topics anvendes forskellige shell scripts, som kalder administrationsservicen i NAS2. I den forbindelse opdateres topics både i databasen og i kafka.

3.1.  Hent Topic

3.1.1.  Hent liste med alle Topics

get_topics.sh basepath="localhost:8086/administration"

3.1.2.  Hent specifikt topic med detaljer

get_topics.sh basepath="localhost:8086/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard"

3.2. Nyt Topic

For at NAS2 skal kunne modtage adviseringer på et Topic skal dette oprettes i Kafka og i databasen.
For at give tilladelse til at der kan oprettes abonnementer og afhentes adviseringer på et Topic, skal der desuden  oprettes et Topic Access i databasen. 

3.2.1. Opret Topic

Først oprettes Topic via følgende kommando, hvor topic er navnet på topic i databasen og internal_topic er  navnet på topic i kafka:

create_topic.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" internalTopic="dk.nsp.bo.nas.fmk.MedicineCard" numPartitions=6 replicationFactor=2

Udover de ovenstående parametre er det også muligt at sætte kafka topic config parametre, hvis ønsket (fx cleanup.policy=delete).

Mulige kafka topic config parametre findes fx her: https://kafka.apache.org/documentation/#topicconfigs

3.2.2. Opret Topic Access

Efter oprettelse af et Topic, tildeles adgang ved at oprette Topic access. 

Topic Access oprettes med en identifier, der angiver adgangen til et specifikt topic. Identifier kan indeholde "ALL", et cvr-nummer på formen "CVR:XXXXXXXX", eller et Subject Serial Number (CVR-RID, CVR-UID CVR-FID, UUID).
Eksempler:

  • "CVR:46837428"
  • "CVR:46837428-FID:92421325"
  • "UI:DK-O:G:23550132-5e1f-4e43-a5f9-048acf49e0b8"

Topic Access oprettes på følgende måde: 

topic_access.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" operation="create" identifier="ALL" comment="SDS-4393: topic access oprettet"

3.3. Lukke for et Topic

For at lukke for nye adviseringer til et Topic anvendes følgende shell script og parametre:

activate_deactivate_topic.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" activation="disable"

3.4. Slette et Topic

For at slette et topic bør det først være inaktivt i en periode således at der ikke kan afleveres nye data og modtagere kan nå at afhente alle deres adviseringer. Derefter skal nedenstående udføres. 

Nedenstående sletter topic fra NAS databasen og i kafka: 

delete_topic.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" 

Hvis et topic har tilhørende subscriptions vil sletning fejle med ovenstående kommando. Hvis man ønsker at gennemtvinge sletning og dermed også slette tilhørende subscriptions anvendes parameteren 'force' som nedenstående viser:

delete_topic.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" force="true"

3.5. Ændre Topic Access

Hvis der skal ændres på hvem, der har lov til at tilgå et topic, skal det opdates i Topic Access. 

3.5.1. Tilføj en adgang til et Topic

Der kan tildeles adgange til et topic på cvr eller cvr-Xid. Der kan være flere adgange for et topic. For at give en ny tilladelse oprettes et nyt Topic Access på følgende måde: 

topic_access.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" operation="create" identifier="CVR:46837428" comment="SDS-4393: ny tilladelse oprettet"

3.5.2. Slette en adgang til et Topic

Hvis en adgang til et Topic skal slettes, gøres det på følgende måde:

topic_access.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard" operation="delete" identifier="CVR:46837428"

3.5.3. Ændre tilladelse fra 'ALL' til cvr eller cvr-Xid

Hvis et Topic skal ændres fra at være tilgængeligt for alle, er det vigtigt at Topic Access med identifier 'ALL' ikke længere findes i databasen. 

Dette sikres ved først at slette adgang for det specifikke Topic hvor identifier = 'ALL'.

Herefter tilføjes adgang for de ønskede CVR eller eller CVR-Xid. 

3.5.4.  Hent liste over adgange for et Topic

For at se hvilke identifiers der er tildelt adgang til et topic anvendes følgende script:

topic_access.sh basepath="NAS/administration" topic="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard"

3.6. Udvide antallet af partitioner

Hvis der opstår et behov i Kafka for at udvide antallet af partitioner for et Topic, skal der ikke foretages noget i NAS2 idet den selv opdager dette og tilpasser sig det nye antal.

4. Overvågning

Alle services i NAS udstiller en status side. På denne side fremgår servicens versionsnummer samt status for adgang til database og/eller Kafka. Status siden kan tilgås via http://NAS/SERVICE_NAME/health. SERVICE_NAME er pullpoint, pullpointfactory, idlist, notificationbroker, subscriptionmanager eller cleanup. Det svarer til de 6 services der er implementeret i NAS2.

Eksempel på svar på fra status-siden. 

HTTP/1.1 200 OK
Connection: keep-alive
X-Powered-By: Undertow/1
Server: WildFly/8
Content-Type: application/json
Content-Length: 82
Date: Fri, 10 May 2019 08:06:26 GMT

{
	"version": "1.0.0-SNAPSHOT"
	,"database": "OK"
	,"kafka streamer": "OK"
}

4.1. HTTP statuskode

Status-siden returnerer følgende status koder afhængig af servicens status. 

200: Applikationen er sund

500: Der er opstået en fejl i applikationen eller en af de services der integreres med.

4.2. Fejlfinding

Såfremt der er problemer med adgang til servicens database, vises nedenstående fejl. Bemærk at den giver en HTTP statuskode 500, og at man i body kan se, at det er NAS servicen der ikke er OK.

HTTP/1.1 500 Internal Server Error
Connection: keep-alive
X-Powered-By: Undertow/1
Server: WildFly/8
Content-Type: application/json
Content-Length: 103
Date: Wed, 20 Feb 2019 13:30:11 GMT
 
 
{ "version": "1.0.0-SNAPSHOT", "database": "FAILED", "kafka streamer": "OK" }

Følgende årsager kan resultere i en statuskode 500. 

  • Hvis database eller Kafka ikke er tilgængelig. 
  • Andre ukendte årsager

Hvis status-siden returnerer HTTP status 500 bør man tjekke applikationsloggen, da fejl logges her til. 

Servicen kan genstartes ved at genstarte den docker container, som servicen den kører i. 

4.2.1. Cleanup Service Status

Statussiden for Cleanup servicen indeholder tidspunkt for seneste cleanup, status for seneste clean up og beskrivelse af eventuel fejl. 

Bemærk at statusoplysninger fra Cleanup servicen gemmes i memory og præsenterer derfor udelukkende status for den kaldte instans af servicen. Hvis det seneste oprydningsjob er udført på en anden instans af servicen, vil dette derfor ikke reflekteres i den returnerede statusside. 

4.3. Statistiklogning

Som en del af den almindelige applikationslog foretages en række logninger særligt beregnet til udtræk til statistik og ledelsesinformation.

Følgende logningspunkter til statistik er defineret:

LogningspunktKomponent

Eksempel på message fra applikationsloggen

(formatteret så det er lettere at læse i denne vejledning)

Der logges når der oprettes et PullPoint. Hertil medtages yderligere information, så som ejeren, evt. abonnement og URL, der er tilknyttet.

PullPointFactory

Service

STATISTIK: {
"action":"createPullPoint",
"info":{
"pullPointId":"98a3f337-4a65-45db-9001-2c9f0b69ff05",
"ownerItSystem":"NAS2UnitTests",
"ownerCvr":"46837428"}}

Logning af alle forespørgsler til Pull Point service herunder antal af adviseringer, der medtages i svaret.

Der logges også om der var tale om replay (DGWS).

PullPoint

Service

STATISTIK: {
"action":"getmessages",
"info":{
"pullPointId":"2acedce5-c00a-40bc-8ddf-fe6de2a596a3",
"subscriptionIds":["a34c720f-9c26-4832-83d1-8671d4b6f7f3"],
"quota":2,
"replay":false}}

Alle kald til Notification Broker skal ligeledes logges sådan at antal af adviseringer modtaget kan uddrages. Her vil topic også medtages.

NotificationBroker

Service

STATISTIK: {
"action":"notify",
"info":{
"quota":1,
"topic":"TESTNAS-TOPIC1"}}
Offsets statistik log logger information omkring subscription og offsets på subscription og offsets i Kafka.PullPoint service
STATISTIK: {
"action":"offsets",
"owner":["46837428NAS2UnitTests"],
"e
ndOffsets":["146","72","72"],
"maxOffsetDelta":["17"],
"pullPointId":["d43c793f-b29a-4d61-b9db-5970e2fc65f0"],
"deltaOffsets":["17","16","17"],
"topic":["topic"],
"subscriptionId":["d8274761-4c27-40d4-bef3-31cec848f5a6"]
}

For alle kald til Notifikation Broker logges det om et request indeholder DGWS headers.
Dermed er muligt at overvåge dette i forbindelse med udfasningen af muligheden for at kalde uden.

NotificationBroker

Service

STATISTIK: {
     "action":"notify",
     "info":{"No security headers found. Notification request is without DGWS protection"}
}

5. DKS-snitflader

Relevante services udstiller deres DKS-snitflade på endpointet "/dks".  I skrivende stund findes følgende:

  • <serverurl>/idlist/service/dks
  • <serverurl>/subscriptionmanager/service/dks
  • <serverurl>/pullpointfactory/service/dks
  • <serverurl>/pullpoint/service/dks

5.1. Test af DKS

Efter konfiguration og deployment af NAS2, kan en given DKS-snitfladen testes i stil med følgende:

curl -i http://localhost:8080/pullpointfactory/service/dks

Eksempel på output:

HTTP/1.1 200 OK
Connection: keep-alive
Transfer-Encoding: chunked
Content-Type: text/xml;charset=UTF-8
Date: Thu, 18 Jan 2024 09:28:28 GMT

<?xml version="1.0"?><root xmlns="http://nspop.dk/2014/04" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://nspop.dk/2014/04 dks.xsd">    <dksVersion>1</dksVersion>    <timestamp>2024-01-18T09:25:06+01:00</timestamp>    <name>pullpointfactory</name>    <endpoint>http://localhost:8080/pullpointfactory/service</endpoint>    <operations>    <action name="http://docs.oasis-open.org/wsn/bw-2/CreatePullPoint/CreatePullPointRequest"><model>synchronous_timeout</model><timeoutMillis>120000</timeoutMillis><idCardLevel>VOCES</idCardLevel></action>    </operations></root>

6. Oprydning

Der kan foretages oprydning af abonnementer og nasconsumers i databasen.
Der konfigureres hvor gamle abonnementer må være – se tidligere – og så sker oprydningen når oprydningsservicen kaldes.
Nasconsumers fjernes i batches af 20. 

Kald laves på følgende URL: http://NAS/cleanup/start (et simpelt GET request er tilstrækkeligt). Svaret for kaldet vil være 200 medmindre der er gået noget galt. Derudover svares der med hvor mange henholdsvis abonnementer og nasconsumers, der er blevet fjernet.

Statussiden for cleanup servicen: http://NAS/cleanup/status viser status for seneste oprydningsjob på instansten, og her bemærkes at status gemmes i memory og ikke representere status på tværs af instanser. 

7. Persistere offsets for tilbagespoling af subscription

Subscriptionmanager servicen udstiller en service til at persistere offsets for alle topics. Disse data kan bruges til at spole en subscription tilbage til et givent tidspunkt. Servicen skal kaldes med regulære mellemrum. og kan tilgås på føglende URL: http://nas/subscriptionmanager/saveOffsets. Hvis kaldet går godt returneres der HTTP 200 med nedenstående body.

{"rowsDeleted":0,"rowsInserted":6}

8. Databasen

Database modellen er beskrevet i NAS2 - Design og arktitekturbeskrivelse.


  • No labels