Document D-4 Ministerie van Infrastructuur en Milieu Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten Versie 1.0 Datum Status 15 juli 2014 Definitief Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 Colofon Versie 1.0 Contactpersoon Paul Leunissen M 06 - 5250 6691 [email protected] Ministerie van Infrastructuur en Milieu Hoofddirectie Financiën, Management en Bedrijfsvoering Directie Concern Informatievoorziening Afdeling Architectuur en Informatie Management Team Architectuur Koningskade 4 Postbus 20906 2500 EX Den Haag Auteurs Stephen Oostenbrink Pagina 3 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 Inhoud 1 Inleiding ........................................................................................................... 7 1.1 Identificatie .................................................................................................................. 7 1.2 Leeswijzer .................................................................................................................... 7 1.3 Doel van dit document .................................................................................................... 7 1.4 Referenties ................................................................................................................... 7 1.5 Afkortingen .................................................................................................................. 7 1.6 Begrippen .................................................................................................................... 7 2 Eisen aan applicaties .......................................................................................... 8 2.1 Opzet applicaties ........................................................................................................... 8 2.2 Applicatie ..................................................................................................................... 8 2.3 Ontwikkelen voor het Standaard Platform ........................................................................... 9 2.4 Scheiden van omgevingsspecifieke configuratie ................................................................. 11 2.5 Databases .................................................................................................................. 11 2.6 Database wijzigingen.................................................................................................... 12 2.7 ESB........................................................................................................................... 13 2.8 Applicatie Server (AS) containers.................................................................................... 13 2.9 Performance ............................................................................................................... 14 2.10 Applicaties zijn clusterbaar ............................................................................................ 15 2.11 Applicaties zijn Java EE 6 compliant ................................................................................ 15 2.12 Webservices zijn stateless ............................................................................................. 15 2.13 Versioneren ................................................................................................................ 16 2.14 Omgevingsspecifieke configuratiebestanden ..................................................................... 19 2.15 Aanlever formaat van artefact(en) .................................................................................. 19 2.16 Uitrollen ..................................................................................................................... 20 3 Leveranciersomgeving ...................................................................................... 21 3.1 Eisen ......................................................................................................................... 21 3.2 PKIoverheid certificaat .................................................................................................. 21 3.3 Opzet ........................................................................................................................ 21 3.4 Databases .................................................................................................................. 22 3.5 Ingebruikname ............................................................................................................ 23 3.6 Command line client ..................................................................................................... 23 3.7 Black box ................................................................................................................... 23 3.8 Ondersteuning ............................................................................................................ 24 4 Bijlage 1 XSD’s ................................................................................................ 25 4.1 common.xsd ............................................................................................................... 25 4.2 application-deployment-meta.xsd ................................................................................... 26 Pagina 5 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 1 Inleiding 1.1 Identificatie Dit document beschrijft de eisen die het Standaard Platform van het Ministerie van Infrastructuur en Milieu (IenM) stelt aan leveranciers zodat hun maatwerksoftware samenwerkt met het Standaard Platform. 1.2 Leeswijzer Om dit document goed te begrijpen wordt het document IMEA Katern Standaard Platform als bekend verondersteld. 1.3 Doel van dit document Het doel van dit document is het informeren van leveranciers aan welke eisen hun maatwerksoftware moet voldoen om gebruik te kunnen maken van het Standaard Platform. 1.4 Referenties De volgende documenten zijn relevant om dit document goed te begrijpen. # 1.5 Referentie Document 1 Afkortingen en begrippen IenM - Standaard Platform - Afkortingen en begrippen v0.9.docx 2 SGA IMEA - Katern - Service Gerichte Architectuur - v1.0.docx 3 SP IMEA - Katern - Standaard Platform - v1.0.docx 4 Koppelingen IMEA - Katern - ESB Koppelingen - v1.0.docx 5 Aansluitvoorwaarden IMEA - Aansluitvoorwaarden - v1.0.docx Afkortingen In dit document worden de volgende afkortingen gehanteerd. Zie het document IenM Standaard Platform Afkortingen en begrippen [Afkortingen en begrippen]. 1.6 Begrippen Aangezien dit document voor diverse doelgroepen bedoeld is en het in algemene zin belangrijk is dat een document op een eenduidige manier geïnterpreteerd wordt, volgen hierna diverse begrippen die van belang zijn bij het lezen van dit document. Zie het document IenM Standaard Platform Afkortingen en begrippen [Afkortingen en begrippen]. Pagina 7 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 2 Eisen aan applicaties Maatwerksoftware moet aan een aantal eisen voldoen om gebruik te maken van het Standaard Platform. Hierdoor zal de applicatie correct werken op het Standaard Platform en automatisch uitgerold worden. De eisen beschreven in dit hoofdstuk zijn gerealiseerd als referentie implementatie zodat ontwikkelaars beschikken over een werkend voorbeeld, zie hoofdstuk 4. 2.1 Opzet applicaties Een applicatie bestaat uit een front-end en de backend componenten die ontsloten worden met webservices. Deze webservices zijn altijd ontkoppeld door de ESB. ID Eis OA01 Front-end: De front-end ook wel aangeduid als interactiekanaal is de gebruikersinterface die verantwoordelijk is voor het afhandelen van de gebruikersinteractie en terugkoppeling naar de gebruiker. De front-end bevat geen business logica. Business logica is onderdeel van de backend en wordt met webservices ontsloten. De front-end maakt gebruik van de backend webservices via koppelingen op de ESB. Rechtstreekse koppelingen zijn niet toegestaan. Voorbeelden van een interactiekanaal zijn mobile, app, web en desktop. OA02 Koppelingen: Een koppelvlak op de ESB. Een ESB zorgt voor ontkoppeling tussen webservice afnemende systemen en webservice aanbiedende systemen. OA03 Backend: Met backend wordt alles bedoeld dat verantwoordelijk is voor een specifiek groep functionaliteit én data. De functionaliteit van een backend wordt ontsloten via webservices. Deze webservices zijn niet direct te benaderen maar altijd via een koppeling op de ESB. De backend functionaliteit kan via webservices ook aan andere systemen dan de eigen front-end beschikbaar gesteld worden. Hierdoor wordt een eenduidig resultaat over interactiekanalen en systemen heen gegarandeerd. OA04 Gegevens: De gegevens van een applicatie ook wel aangeduid als applicatiedata staat in een database. Deze gegevens zijn alleen via de backend toegankelijk. OA05 Een applicatie kan bestaan uit verschillende componenten. Deze component worden door architectuur geïdentificeerd. De componenten kennen elk een eigen release- en beheercyclus en moeten als zelfstandige component uitgerold kunnen worden. 2.2 Applicatie ID Eis AG01 De gestructureerde gegevens van een applicatie worden opgeslagen in een database. Deze gegevens zijn alleen via de backend toegankelijk. AG02 Applicaties die gebruik maken van het Standaard Platform zijn OS agnostisch. Dit betekent dat er binnen de applicaties geen aannames gedaan mogen worden over het besturingssysteem waarop het Standaard Platform draait. Denk hierbij bijvoorbeeld aan het gebruik van File.seperator in plaats van het hard coderen van een ‘/’ of ‘\’ karakter. Daarnaast moeten alle bestandsverwijzingen Pagina 8 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 hoofdlettergevoelig geïmplementeerd worden, zodat bestanden ook gevonden worden op besturingssystemen die hiervan uitgaan. Een URL is een uniek adres waar op een applicatie te benaderen is. URL worden volgens de volgende systematiek opgebouwd. http(s)://<omgeving>.<applicatienaam | status>.<domein>/[applicatie context] Een voorbeeld voor de actieve versie van een applicatie met context root https://acc.actief.ilt.nl/inspectieview Een voorbeeld voor de actieve versie van een applicatie zonder context root https://acc.inspectieview.ilt.nl Een voorbeeld voor een nieuwe versie van een applicatie https://acc.nieuw.ilt.nl/inspectieview Op deze manier is het mogelijk om meerdere versies van een applicatie naast elkaar te draaien. Een URL element maakt gebruik van kleine letters. Omgeving Omgeving waarin de applicatie actief is: dev, tst, int, acc, pre of prd. domein Domein waar de applicatie actief is: ienm.nl, ilent.nl, rws.nl, nea.nl. Systemen die in de buitenwereld een eigen identiteit hebben, bijvoorbeeld Olo of LAVS, hebben een eigen domein (omgevingsloket.nl, landelijkasbestsysteem.nl). applicatienaam De logische naam van de applicatie. Als deze onderdeel is van het domein dan wordt geen status opgenomen in het domein, omdat dit de actieve versie impliceert. Als de applicatienaam wordt gebruikt dan is er geen applicatiecontext. status Status geeft aan of het de actieve of nieuwe versie van een applicatie betreft. applicatiecontext De context waaronder de applicatie beschikbaar is. Deze wordt niet gebruikt indien de applicatienaam wordt gebruikt. 2.3 Ontwikkelen voor het Standaard Platform Om het ontwikkelen op basis van het Standaard Platform zo eenvoudig mogelijk te maken stelt IenM een tweetal kant en klare omgevingen beschikbaar als virtuele machine (VM). Hiermee beschikt de leverancier in haar eigen omgeving over een volledig werkend Standaard Platform inclusief clustering en automatisch uitrolmechanisme. Hierdoor kan de leverancier zich richten op het ontwikkelen van de applicatie en hoeft zich niet bezig te houden met het inrichten van het platform (infrastructuur en middleware). Pagina 9 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 ID Eis VM01 De leverancier dient met de VM images in eigen omgeving te testen of de applicatie correct werkt op het Standaard Platform en automatisch uitgerold kan worden. VM02 De leverancier dient de voorgeschreven Standaard Platform componenten met de gespecificeerde versies te gebruiken. VM03 Het is niet toegestaan om instellingen van Standaard Platform componenten te wijzigen, bijvoorbeeld geheugen, caching, poortnummers, databasesinstellingen en beveiligingsinstellingen. VM05 Een applicatie stelt een health service beschikbaar op basis van REST en JSON. Met deze service kan de status van alle applicatie componenten opgevraagd kunnen worden. Bijvoorbeeld: { “health”: { “Versie”: “1.3.5”, “Front-end”: “OK”, “Services”: [ “UserAdmin”: { “Status”: “OK”, “Versie”: “1.0.0”, “Gemiddelde response tijd”: “950ms”, “Langste response tijd”: “2045ms”, “Kortste response tijd”: “670ms”, “Afgesproken response tijd”: “1000ms”, “Requests:”: 1200, “Errors”: 12 }, “Login”: { … } ] “Database”: “OK”, “DMS”: “OK”, … } } Hiermee ligt de kennis van de status bij de applicatie zelf en kan in een keer een overzicht opgevraagd van de status van alle applicatie componenten. Deze informatie wordt door de monitoring gebruikt om de status van de applicatie componenten te monitoren en te waarschuwen bij afwijkingen. VM06 De health service kan informatie over een component als geheel aanleveren (http://acc.ienm.nl/lavs/v1/health/check/simple) of gedetailleerde informatie zoals beschreven in VM05 (http://acc.ienm.nl/lavs/v1/health/check/full). VM07 Een applicatie dient ook een webpagina beschikbaar te stellen waarmee de health service informatie direct opgevraagd kan worden door een beheerder. Zie hoofdstuk 3 voor een verdere toelichting van de VM images. Pagina 10 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 2.4 Scheiden van omgevingsspecifieke configuratie Omgevingsspecifieke configuratie instellingen zijn instellingen die verschillen per omgeving (ONT, TST, INT, ACC, PRE en PRD). ID Eis SO01 De omgevingsspecifieke instellingen worden in aparte configuratiebestanden geplaatst. Deze configuratiebestanden worden in de GR gezet. SO02 Een applicatie haalt de omgevingsspecifieke instelling op uit de GR met behulp van de ConfigurationLoader API. 2.4.1 Onderscheid vertrouwelijke en niet vertrouwelijke configuratie Bij omgevingsspecifieke configuratie instellingen wordt onderscheid gemaakt tussen vertrouwelijke en niet vertrouwelijke instellingen. Vertrouwelijke configuratie instellingen zijn parameters die vanuit informatie beveiligingsoogpunt als gevoelig worden beschouwd. Denk hierbij aan gebruikersnamen, wachtwoorden en interne IP adressen. Vertrouwelijke instellingen worden door TB beheerd en niet vertrouwelijke door FB. De ConfigurationLoader API zorgt dat vertrouwelijke en niet vertrouwelijke instellingen transparant voor de webapplicatie afgehandeld worden. ID Eis VO01 Bij omgevingsspecifieke configuratie instellingen wordt onderscheid gemaakt tussen vertrouwelijke en niet vertrouwelijke instellingen die in verschillende bestanden worden opgeslagen. 2.4.2 Cachen van omgevingsspecifieke configuratie instellingen Vanuit performance oogpunt is het niet gewenst dat de omgevingsspecifieke configuratie instellingen bij elke aanroep uit de GR worden ingelezen. Om dit te voorkomen worden de omgevingsspecifieke configuratie instellingen gecached. Cachen van de omgevingsspecifieke configuratie instellingen wordt door de ConfigurationLoader API zelf geregeld. De ConfigurationLoader API zal de omgevingsspecifieke configuratie instellingen na een configureerbare periode automatisch opnieuw inlezen. Het is ook mogelijk om via de ConfigurationLoader API het opnieuw inlezen te forceren. ID Eis CO01 Het is niet toegestaan om omgevingsspecifieke configuratie instellingen in de applicatie zelf te cachen in welk vorm dan ook. 2.5 Databases Applicatiedata staat in een database die in een databasecompartiment staat. Dit databasecompartiment is onderdeel van het Standaard Platform. Het Standaard Platform stelt als enige eis dat de gebruikte database door Liquibase ondersteund wordt. Pagina 11 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 ID Eis DB01 De volgende databaseplatformen zijn beschikbaar: PostgreSQL, SQL Server en Oracle. DB02 De voorkeur gaat uit naar PostgreSQL dan naar SQL Server en als laatste optie Oracle. 2.6 Database wijzigingen Liquibase wordt gebruikt voor de definitie van het initiële databasestructuur en eventuele initiële gegevens. Ook wijzigingen in de databasestructuur of de gegevens en migreren van gegevens worden middels Liquibase scripts doorgevoerd. Hierdoor wordt het mogelijk om database wijzigingen als onderdeel van de applicatie te packagen en automatisch uit te voeren als onderdeel van het automatische uitrolmechanisme. ID Eis DW01 Liquibase wordt gebruikt voor de definitie van het initiële databasestructuur en eventuele initiële gegevens (stamgegevens). DW02 Wijzigingen in de databasestructuur of de gegevens en migreren van gegevens worden middels Liquibase scripts doorgevoerd. DW03 Het eenmalig inladen van data mag handmatig gebeuren. DW04 Voor het terugkerend inladen van data dient de applicatie zelf voorzieningen treffen. 2.6.1 Initiëren Liquibase scripts Het uitvoeren van de Liquibase scripts wordt via de Servlet Listener geïnitieerd. Hierdoor wordt de Liquibase script als eerste actie na het starten van de webapplicatie uitgevoerd. Dit zorgt er bovendien voor dat het uitrollen van de applicatie faalt als de Liquibase scripts falen. 2.6.2 ID Eis LI01 Een applicatie stelt een Servlet Lister beschikbaar om Liquibase te initiëren. Database wijzigingen zijn niet-destructief De kern van het maken van niet-destructieve wijzigingen is het opdelen van wijzigingen in zo klein mogelijke refactorings. Zo is het splitsen van een tabel een aaneenschakeling van de kleinere refactorings: toevoegen tabel en een aantal keer verplaats kolom. ID Eis ND01 Het is mogelijk dat meerdere versies van dezelfde applicaties hetzelfde databaseschema gebruiken. ND02 Bij het doorvoeren van database wijzigingen met Liquibase scripts moet worden gewaarborgd dat alle gemaakt wijzigingen niet-destructief zijn, zodat verschillende versie van de applicaties blijven functioneren. ND03 Database wijzigingen zijn opgedeeld in kleine aangeschakelde refactorings. Pagina 12 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 Hieronder worden een aantal niet-destructieve database refactorings beschreven. Deze zijn gebaseerd op het boek Database Refactoring [2]. De volgende tabel geeft een lijst met mogelijke refactorings weer. Een complete lijst van refactorings is te vinden in het boek Database Refactoring [2]. 2.6.3 Refactoring Uitleg Drop Column http://www.databaserefactoring.com/RemoveColumn.html Merge Tables http://www.databaserefactoring.com/MergeTables.html Move Column http://www.databaserefactoring.com/MoveColumn.html Rename Column http://www.databaserefactoring.com/RenameColumn.html Replace One-To-Many With Associative Table http://www.databaserefactoring.com/ReplaceOneToMany.html Split Table http://www.databaserefactoring.com/SplitTable.html Merge Columns http://www.databaserefactoring.com/MergeColumns.html Add Lookup Table http://www.databaserefactoring.com/AddLookupTable.html WSO2 DSS Bij het gebruik van Data Services Server (DSS) zijn aanvullende instructies nodig om Liquibase te gebruiken om database wijzigingen automatisch uit te rollen. Er dient een minimale webapplicatie te zijn die enkel als doel heeft de Liquibase scripts uit te voeren. De webapplicatie artefact wordt samen met het DSS artefact als applicatie artefact aangeboden en uitgerold. 2.7 2.8 ESB ID Eis KE01 Het gebruik van custom mediators is alleen toegestaan in overleg met architectuur. KE02 Zie voor de overige eisen het document IenM - ESB Koppelingen - Eisen. Applicatie Server (AS) containers Er zijn per applicatie twee type Applicatie Server (AS) containers beschikbaar. Eén stateful en één stateless. Een stateful container houdt tussen aanroepen door sessie informatie bij en wordt voor de front-end (UI) gebruikt. De stateless container houdt geen sessie informatie bij en wordt gebruikt voor de backend en webservices1. ID Eis AS01 De front-end draait in een stateful container. Dit is een “domme” gebruikersinterface die geen business logica bevat. AS02 De backend draait in een stateless container. De backend bevat de business logica en ontsluit de applicatiegegevens. 1. Dit zijn de webservices die de backend functionaliteit ontsluiten. Pagina 13 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 De containers zijn geoptimaliseerd voor het doel waar deze voor dienen, o.a. door het beperken van het beschikbare geheugen. 2.8.1 Container Geheugen Geclusterd (HA) Java EE profiel Stateful 4 GB Ja Web Stateless 1 GB Nee Full Gedeeld of dedicated Een AS container kan door een aantal applicaties gedeeld worden of dedicated zijn voor een enkele applicatie. Dit wordt per applicatie bepaald aan de hand van het verwachte gebruik, vereiste schaalbaarheid en het bedrijfsrisico bij verstoring van de dienstverlening. Een applicatie kan bestaan uit meerdere componenten. Deze componenten kunnen een AS container delen of verdeeld worden over verschillende containers. Hoe applicatie componenten worden verdeeld wordt bepaald aan de hand van het verwacht gebruik, vereiste schaalbaarheid en het bedrijfsrisico bij verstoring van de dienstverlening. ID Eis GD01 De componenten van een applicatie worden in overleg met Architectuur bepaald. GD02 De deployment model van applicatie componenten wordt in overleg met Architectuur bepaald. 2.8.2 Capaciteit Het is mogelijk dat er meerdere instanties van een container type op een server draaien voor een applicatie om de verwerkingscapaciteit te vergroten. De inrichtingskeuze is afhankelijk van de benodigde capaciteitseis, vereiste schaalbaarheid en verwacht gebruik van de applicatie. 2.9 ID Eis CA01 Het aantal applicatie containers wordt in overleg met Architectuur bepaald. Performance Applicaties dienen gebruik te maken van de caching mechanisme van de applicatiecontainer om te voorkomen dat de database wordt belast met veelvoorkomende verzoeken. Het SP biedt een gedistribueerde cache mechanisme dat over geclusterde containers heen werkt. ID Eis PE01 Applicaties maken gebruik van caching door gebruik te maken van JPA 2 en object type (entities) zijn cache enabled. PE02 De cache periode is per object type (entity) instelbaar door een functioneel beheerder. Pagina 14 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 2.10 Applicaties zijn clusterbaar Alle Standaard Platform componenten zijn geclusterd. Een applicatie moet om kunnen gaan met een geclusterde omgeving. Een applicatie mag er niet vanuit gaan dat verschillende aanroepen door dezelfde server worden afgehandeld. Hier moet bij het ontwikkelen rekening mee gehouden worden. 2.10.1 ID Eis CL01 Een applicatie moet kunnen draaien met een geclusterde omgeving. De HTTP sessie is serializable ID Eis SE01 Gegevens van de front-end die in de HTTP sessie worden opgeslagen moeten serializable zijn, zodat deze tussen de containers in een cluster uitgewisseld kunnen worden. 2.10.2 Grootte van de HTTP sessie ID Eis GR01 Bij clustering worden gegevens van de front-end in de HTTP sessie uitgewisseld tussen de containers in een cluster. Om dit snel en betrouwbaar te kunnen doen moet de grootte van de sessie beperkt worden tot maximaal 10MB. 2.10.3 Persisteren van gegevens Voor het persisteren van gegevens tussen verschillende aanroepen wordt gebruik gemaakt van de database, de HTTP sessie of een gedeeld bestandssysteem. ID Eis PG01 Het is niet toegestaan om gegevens op het lokaal bestandssysteem op te slaan, omdat het niet gegarandeerd is dat dezelfde server een volgende aanroep afhandelt. PG02 2.11 Het bestandssysteem moet configureerbaar zijn. Applicaties zijn Java EE 6 compliant ID Eis EE01 Alleen features van de Java EE 6 specificatie uit het profile behorende bij het type applicatie (zie paragraaf 2.7) mogen gebruikt worden. 2.12 Webservices zijn stateless ID Eis WS01 Een webservice is altijd stateless. Dit betekent dat binnen de webservice zelf, in de applicatiecontainer, geen state mag worden bijgehouden in een HTTP of EJB sessie. Pagina 15 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 WS02 De enige state die een webservice mag gebruiken is state uit een database of gedeeld bestandssysteem. 2.13 Versioneren 2.13.1 Applicaties ID Eis VA01 Applicaties worden geversioneerd conform de standaard beschreven in paragraaf 4.3.1.1. 2.13.2 ESB resources Er kunnen één of meerdere actieve productie versies van een koppeling zijn. Hierdoor kunnen afnemers van een koppeling in eigen tempo en gecontroleerd overgaan naar een nieuwe versie. Er wordt geen maximum gesteld aan het aantal actieve versies van een koppeling. Dit aantal dient tot een minimum beperkt te worden. Dit wordt gedaan door een maximum periode te hanteren dat een oude koppelvlak ondersteund wordt na het beschikbaar komen van een nieuwe versie (standaard 1 jaar). Daarnaast worden wijzigingen waar mogelijk als non breaking wijziging doorgevoerd. Het versioneren van koppelingen en de hiervoor benodigde ESB resources vereist specifieke aandacht, om het mogelijk te maken om meerdere actieve versies van een koppeling naast elkaar te draaien. De volgende regels gelden hierbij. 2.13.2.1 Major en minor versie ID Eis MM01 Er wordt bij de ESB onderscheid gemaakt tussen de koppeling zelf (proxy) en de ondersteunende ESB resources. Een koppeling is het koppelvlak en ondersteunende ESB resources zijn (herbruikbare) functionaliteiten die door verschillende koppelingen gebruikt kunnen worden, zoals de generieke foutafhandeling sequence. MM02 Ook bij herbruikbare ESB resources, zoals de generieke foutafhandeling sequence, moet het mogelijk zijn om een nieuwe versie in gebruik te nemen zonder dat alle afhankelijk koppelingen van de voorgaande versie in één keer over moeten. Deze koppelingen kunnen door het versioneren gecontroleerd en in eigen tempo over. Ook hier geldt dat de oude versie voor een beperkt periode ondersteund wordt (standaard 1 jaar). MM03 Bij applicatiebeheer afspraken dient rekening gehouden te worden met aanpassingen door nieuwe releases van een koppelvlak en herbruikbare ESB resources. MM04 ESB resources worden geversioneerd op major en minor versie. Dit geldt in ieder geval voor de volgende resources: Proxies Pagina 16 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 Sequences Endpoints Custom mediators Resources in de GR zoals: MM05 o XSD o WSDL o XSLT o Configuratieparameters o Configuratiebestanden De identificerende naamgeving van ESB resources moeten een versieaanduiding bevatten om onderscheid te kunnen maken tussen versies. Deze ESB resources worden geversioneerd op bestandsnaam, bijvoorbeeld “VoorbeeldProxy-v1_4.xml”. Hierdoor is het mogelijk om versies waarvan de major- en/of minornummer verschillen gelijktijdig te draaien en testen. Het is niet wenselijk om versies, waarvan alleen het patchnummer verschilt, naast elkaar te kunnen testen. Het gaat in dit laatste geval namelijk om een actieve versie waarop een patch is doorgevoerd. In onderstaand voorbeeld maakt een proxy gebruik van een ondersteunende ESB resource (foutafhandeling sequence). <proxy xmlns="http://ws.apache.org/ns/synapse" name="BagProxy-v1_1" transports="https,http" serviceGroup="nl.ienm.ca" statistics="disable" trace="disable" startOnLoad="true"> <target> <inSequence> … <sequence key="FoutAfhandelingSeq-v2_1"/> … Voorbeeld 1. Proxy 2.13.3 GR resources ID Eis VG01 Resources in de GR worden van major en minor versie voorzien in de bestandsnaam. In onderstaand voorbeeld is de versie af te leiden uit de bestandsnaam: _system/governance/VoorbeeldApplicatie/xsd/Voorbeeld-v1_0.xsd VG02 De resources die tot dezelfde koppeling behoren worden gegroepeerd door deze in een aparte folder te zetten. Bijvoorbeeld: _system/governance/VoorbeeldApplicatie/v1_0/xsd/Voorbeeld-v1_0.xsd Pagina 17 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 2.13.4 Koppelvlak ID Eis VK01 Naast het versioneren van de resources, WSDL en XSD, dient ook het koppelvlak zelf van een versie voorzien te zijn. 2.13.4.1 Namespace ID Eis VN01 Koppelvlakken worden geversioneerd door een versienummer toe te voegen aan de namespace. De service zelf (WSDL) en de berichtstructuur (XSD) worden voorzien van een namespace waarin enkel de major versie is opgenomen. Bijvoorbeeld: “nl.minienm.example.v1”. 2.13.4.2 URL’s Uniform Resource Locators (URL’s), bij koppelingen ook wel aangeduid als een Endpoint (EP), zijn een belangrijk onderdeel bij het versioneren van een applicatie of een koppeling. Dit geldt zowel voor webapplicaties als ook voor koppelingen die een koppelvlak op een URL beschikbaar stellen. ID Eis VN02 Koppelvlakken worden geversioneerd door een versienummer toe te voegen aan de namespace. De service zelf (WSDL) en de berichtstructuur (XSD) worden voorzien van een namespace waarin enkel de major versie is opgenomen. Bijvoorbeeld: “nl.minienm.example.v1”. VN03 URL’s van webservices voldoen aan de standaard zoals beschreven in paragraaf 5.3 Endpoints in het document IMEA – Katern – Service Gerichte Architectuur voor koppelingen. VN04 Bij applicaties kunnen maximaal twee versies van een applicatie gelijktijdig in een omgeving in gebruik zijn: de actieve versie en de nieuwe versie. Om dit mogelijk te maken worden er eisen gesteld aan het versioneren van de URL’s. Er zijn standaard URL’s zonder versienummers die naar deze twee versies wijzen. Dit wordt geregeld met behulp van een reverse proxy. Dit wordt bij het automatisch uitrollen ingesteld. Op productie is maar één standaard URL beschikbaar en deze wijst naar de actieve versie. Dit betekent dat op alle omgevingen behalve PRD getest worden door naar een specifieke URL te navigeren. 2.13.4.3 Koppelvlak versie ID Eis VK01 Bij koppelingen is er sprake is van een major versie indien er sprake is van niet backward compatible (breaking) wijzigingen in het koppelvlak. Een koppelvlak wordt alleen op major versie geversioneerd. De minor versie wordt opgenomen in het bericht zelf. Pagina 18 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 2.13.5 Proxy services ID Eis VP01 Het moet mogelijk zijn om meerdere versies van proxy services gelijktijdig te testen. Proxy service URL’s zijn daarom geversioneerd op major en minor versienummer. 2.13.6 Webapplicaties ID Eis VW01 Webapplicaties hebben als context root de naam van het software artefact, bijvoorbeeld erru-1.0.0. Webapplicaties worden uitgerold op basis van een software artefact waar de major, minor en patch versie in de applicatienaam is opgenomen. Hierdoor draait de webapplicatie onder de context root waarin het versienummer is opgenomen. De erru-1.2.3.war zal bijvoorbeeld beschikbaar zijn op http://host:port/erru-1.2.3/. Middels een reverse proxy wordt de actuele versie van de applicatie beschikbaar gesteld, in dit geval: http://erru.host en de nieuwe release als http://erru-new.host. 2.14 Omgevingsspecifieke configuratiebestanden ID Eis OC01 De omgevingsspecifieke configuratie staat in aparte configuratiebestanden. Deze worden in de GR gezet. OC02 Het Standaard Platform biedt een standaard API (ConfigLoader) waarmee de omgevingsspecifieke configuratiebestanden ingelezen kunnen worden. Deze API zorgt ervoor, transparant voor de applicatie, dat de juiste omgevingsspecifieke configuratie wordt ingelezen afhankelijk van de omgeving (ACC, PRE, PRD). Applicaties maken gebruik van ConfigLoader om de omgevingsspecifieke instellingen op te vragen/ OC03 Een template configuratiebestand wordt bij oplevering van een applicatie meegeleverd voor zowel de vertrouwelijke als niet vertrouwelijke omgevingsspecifieke configuratie instellingen. TB en FB gebruiken deze template om de omgevingsspecifieke configuratiebestanden te maken. OC04 Indien het een aanlevering betreft van een bestaande applicatie dan dienen de wijzigingen ten opzichte van de bestaande omgevingsspecifieke configuratiebestanden aangegeven te worden. Op basis hiervan kunnen TB en FB de bestaande omgevingsspecifieke configuratiebestanden aanpassen. 2.15 Aanlever formaat van artefact(en) ID Eis AF01 De verschillende onderdelen van een applicatie worden als package aangeleverd (applicatie artefact). Dit package is een zipbestand met de verschillende applicatie onderdelen (software artefacten) en een metadatabestand (applicationdeployment-meta.xml). Dit metadatabestand identificeert de applicatie en geeft aan naar welke Standaard Platform componenten de verschillende applicatie Pagina 19 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 onderdelen uitgerold moeten worden. Het uitrolmechanisme bepaald tevens op basis van de informatie in het metadatabestand naar welke infrastructuur de applicatie onderdelen uitgerold moeten worden. AF02 De applicatie package is omgevingsonafhankelijk en wordt ‘as is’ en volledig geautomatiseerd naar de verschillende omgevingen uitgerold. De omgevingsspecifieke configuratie instellingen zorgen er voor dat de applicatie correct werkt op deze omgevingen. AF03 Het applicatie artefact wordt als zipbestand aangeleverd. In de hoofddirectory van het zipbestand staan de software artefacten waaruit de applicatie artefact bestaat en een application-deployment-meta.xml. Het metadatabestand voldoet aan de in bijlage 2 beschreven XSD. AF04 De source code en geautomatiseerde tests worden als aparte QA zip bestand meegeleverd in de applicatie package. 2.16 Uitrollen De GR biedt functionaliteit om applicaties automatisch uit te rollen. Met deze functionaliteit kan een applicatie automatisch en gecontroleerd door de verschillende omgevingen van een OTAP straat worden uitgerold en teruggerold. Een applicatie doorloopt alle omgevingen en eindigt uiteindelijk in de PRD omgeving. Om een applicatie van de ene omgeving naar de andere omgeving door te zetten vindt een promote plaats. Het omgekeerde gebeurt door middel van een demote. ID Eis UR01 In de eigen omgeving maakt de leverancier gebruik van de beschikbaar gestelde VM images om aan te tonen dat de applicatie op het Standaard Platform draait en geautomatiseerd uitgerold kan worden. UR02 Bij het uitrollen dient in het bijzonder aandacht besteed te worden aan database wijzigingen. Het handmatig uitvoeren of terugdraaien van database wijzigingen is niet toegestaan. Pagina 20 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 3 Leveranciersomgeving Er worden een leveranciersomgeving beschikbaar gesteld aan softwareleveranciers. Deze leveranciersomgeving bestaat uit twee omgevingen die zijn ingericht conform het Standaard Platform. De leverancier gebruikt deze leveranciersomgeving om zelf te testen of een maatwerkapplicatie draait op het SP en automatisch uitgerold kan worden. Daarnaast wordt deze leveranciersomgeving gebruikt om een release van de applicatie geautomatiseerd op te leveren aan IenM. 3.1 Eisen Om de leveranciersomgeving te gebruiken dient de leverancier te beschikken over een eigen PKIoverheid certificaat. 3.2 PKIoverheid certificaat PKI certificaten worden gebruikt om te authentiseren en autoriseren. IenM stelt self signed certificaten beschikbaar om netwerkverkeer te beveiligen tussen de eigen omgeving van de leverancier en de leveranciersomgeving voor zowel applicatie- als berichtenverkeer. Daarnaast dient de leverancier over een eigen geldige PKIoverheid certificaat te beschikken voor communicatie tussen de leveranciersomgeving en het Centraal Aansluitpunt (CA). ID Eis PO01 Een leverancier dient over een eigen en geldig PKIoverheid certificaat te beschikken. PO02 IenM stelt een self signed certificaat beschikbaar aan de leverancier. De leverancier is verantwoordelijk om dit certificaat vertrouwelijk te behandelen. 3.3 Opzet De leveranciersomgeving bestaat uit twee omgevingen (TST en INT). Een leverancier maakt gebruik van deze omgevingen om aan te tonen dat de applicatie op het Standaard Platform draait en geautomatiseerd uitgerold kan worden. In de onderstaand figuur wordt het uitrolproces in de tijd weergegeven. Pagina 21 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 Figuur 1. Applicatie wordt automatisch uitgerold door de OTAP straat De getallen geven de volgorde van de stappen aan: De applicatie wordt toegevoegd aan de GR met behulp van de CLI. De applicatie wordt uitgerold naar TST. De applicatie wordt uitgerold naar INT. De applicatie wordt na de interne kwaliteitscontrole doorgezet naar IenM. De applicatie wordt in een staging locatie gezet en de verantwoordelijke functioneel beheerder wordt automatisch per email geïnformeerd. Als de documentatie volledig is en goedgekeurd wordt dan wordt de applicatie uitgerold naar ACC. Na acceptatie in ACC wordt de release doorgezet naar PRE waar een smoke test wordt uitgevoerd om te controleren of deze correct werkt. Na succesvol afronden van de smoke test in PRE wordt de applicatie uitgerold naar PRD. 3.4 Databases PostgreSQL wordt als database meegeleverd als onderdeel van de VM images. ID Eis DB01 Per omgeving is een databaseschema nodig. DB02 Er zijn per databaseschema twee database accounts nodig. Een account voor de applicatie met lees, schrijf en verwijder rechten (volledige DML2 rechten) op het databaseschema en een account voor het uitrollen met beheerdersrechten op het databaseschema (volledige DML en DDL3 rechten). 2. DML = Data Modification Language. 3. DDL = Data Definition Language. Pagina 22 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 DB03 Naamgeving van schema’s en database accounts voldoen aan de hieronder beschreven standaard. Omgeving 3.5 Databaseschema User BPO-V User uitrol (DML) (DML en DDL) ACC ACC_<APPL> ACC_<APPL>_APP ACC_<APPL>_UITROL INR PRE_<APPL> ACC_<APPL>_APP PRE_<APPL>_UITROL PRD PRD_<APPL> PRD_<APPL>_APP PRD_<APPL>_UITROL Ingebruikname Om de leveranciersomgeving in gebruik te nemen moet door de leverancier nog een laatste configuratie plaatsvinden. Deze configuratie bestaat uit o.a.: - het installeren van de leveranciers PKIoverheid certificaat - aanmaken van databases - aanmaken van JNDI databases - toevoegen van configuratiebestanden aan de GR Er is een apart document beschikbaar waar de ingebruikname is beschreven. 3.6 Command line client Het Standaard Platform stelt een Command Line Client (CLI) beschikbaar waarmee een applicatie aan de DeploymentWebservice aangeboden kan worden. De CLI maakt gebruik van tweezijdig SSL op basis van PKIoverheid certificaten voor authenticatie en autorisatie doeleinden. Deze client wordt gebruikt om de ontwikkel build pipeline aan de leveranciersomgeving te koppelen. Er is een apart document beschikbaar waarin het gebruik van de CLI is beschreven. 3.7 Black box Behalve de configuratie aanpassing uit de vorige paragraaf moeten de leveranciersomgevingen worden beschouwd en gebruikt als een black box. Problemen bij het gebruik of vragen over het gebruik dienen aan de beheerder van het Standaard Platform gericht te worden (zie volgende paragraaf). ID Eis BB01 Het inloggen via SSH op de leveranciersomgeving en het uitvoeren welke command line acties dan ook is niet toegestaan en is een teken dat de applicatie niet conform het Standaard Platform functioneert. BB02 De applicatie mag alleen via de command line client naar de leveranciersomgeving worden uitgerold. BB03 Uitrollen naar de verschillende omgevingen van de leveranciersomgeving wordt gedaan via de GR inclusief het doorzetten naar de staging omgeving bij IenM. BB04 Andere acties in de beheer consoles van de WSO2 producten of JBoss die de functionaliteit of dimensionering van het platform veranderen zijn niet toegestaan. Pagina 23 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 3.8 Ondersteuning IenM levert ondersteuning bij het gebruik van de leveranciersomgeving en ontwikkeling op basis van het Standaard Platform. Hiervoor dient contact opgenomen te worden met de beheerder van het Standaard Platform. Pagina 24 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 4 Bijlage 1 XSD’s 4.1 common.xsd Gedeeld schema, wordt door andere schema’s gebruikt en definieert de verschillende platform componenten waar naartoe uitgerold kan worden. 4.1.1 XSD <?xml version="1.0" encoding="UTF-8"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="ServerType"> <xs:restriction> <xs:enumeration value="wso2-esb"/> <xs:enumeration value="wso2-dss"/> <xs:enumeration value="wso2-bam"/> <xs:enumeration value="jboss-app"/> </xs:restriction> </xs:simpleType> </xs:schema> 4.1.2 XML voorbeeld Niet van toepassing. Zie overige XML voorbeelden. Pagina 25 van 26 Definitief | Standaard Platform - Aansluitvoorwaarden Applicaties en Componenten | Versie 1.0 4.2 application-deployment-meta.xsd Schema voor de application-deployment-meta.xml bestanden die in de root van het application artefact zip bestand aanwezig moeten zijn. Koppelt software artefacten aan logische middleware componenten. 4.2.1 XSD <?xml version="1.0" encoding="UTF-8"?> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:include schemaLocation="common.xsd" /> <xs:element name="application" type="applicationType"/> <xs:complexType name="artifactType"> <xs:sequence> <xs:element name="name"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:pattern value=".*-[0-9]\.[0-9]\.[0-9]\..+"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="target" type="ServerType"/> </xs:sequence> </xs:complexType> <xs:complexType name="applicationType"> <xs:sequence> <xs:element type="xs:string" name="name"/> <xs:element type="artifactType" name="artifact" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:schema> 4.2.2 XML voorbeeld <?xml version='1.0'?> <application> <name>ERRU Application</name> <artifact> <name>erru_application-1.1.0.war</name> <target>jboss-application-server</target> </artifact> <artifact> <name>erru_proxies-1.1.0.car</name> <target>wso2-esb-server</target> </artifact> </application> Pagina 26 van 26
© Copyright 2024 ExpyDoc
