MuleSoft upgrade guide
Sinds februari 2024 heeft MuleSoft Runtime versie 4.6 officieel uitgebracht als de nieuwe LTS (Long Term Support) versie. De standaard support voor de veelgebruikte versie 4.4 eindigde op 8 oktober 2024 (met uitgebreid support dan nog loopt tot oktober 2025). Dit betekent dat er tot oktober nog support is voor productiefouten, maar dat support daarna echt eindigt. Verder details hierover kun je hier vinden. Het doel van dit artikel is het geven van een leidraad hoe deze upgrade aangepakt kan worden en wat er allemaal bij komt kijken.
Strategie
Belangrijk om te vermelden is dat hier om een ‘minor’ upgrade gaat, dus niet van Runtime versie 4.X naar 5.X, maar van versie 4.4 naar 4.6. Er is echter wel additionele complexiteit in de zin dat de Runtime ook met een geüpgraded Java-versie gebruikt kan worden, te weten Java 17 ( dit dus naast Java 8). De voordelen van Java 17 zitten op performance (geheugen gebruik) en beveiliging, maar ook dat de gebruikte Java beter ondersteunt wordt. Je kan dus echter ook de keus maken om te wachten met de upgrade naar Java 17 tot de release van Runtime 4.9 (nieuwe LTS-versie), die gelanceerd wordt in februari 2025. Daarmee blijf je met Runtime 4.6 op Java 8 en is de impact minder groot. In deze blog gaan we wel uit van deze upgrade.
Deployments
MuleSoft biedt verschillend hosting mogelijkheden:
- Standalone (On-premise)
- CloudHub (1.0 en 2.0)
- Runtime Fabric (RTF)
Bij CloudHub en RTF heb je het voordeel dat elke API (applicatie) in zijn eigen instantie draait, te weten een container of EC2. Hiermee is het mogelijk de upgrade dus per applicatie uit te voeren en is er geen nood om een ‘big bang’ upgrade uit te voeren. Bij de standalone werkt dit anders en maken de APIs gebruik van dezelfde geconfigureerde (gedeelde) Runtime van de server. Mijn advies zou dan ook zijn dat dit ook het moment is om na te denken om naar een RTF-installatie te gaan, maar dat is natuurlijk ook een grote stap met veel impact. Als dit niet tot de mogelijkheden behoort is de beste (of eigenlijk enige) strategie om een upgrade (‘U) omgeving neer te zetten met Java 17 en Runtime 4.6. Hier implementeer je de geüpgraded APIs en na de benodigde testen kun je (meestal door een wijziging in de load balancer live gaan; daarbij heb je hiermee een rollback mogelijkheid als zich calamiteiten voordoen.
Zoals aangegeven heb je hier bij CloudHub of RTF geen last van en kun je gradueel, per API de upgrades uitvoeren. Wat dit concreet inhoudt zetten we in de volgende alinea’s met een voorbeeld uiteen.
Benodigdheden
In principe kun je al beginnen door de nieuwste versie van Anypoint studio te downloaden (momenteel 7.19), deze komt verpakt met de juiste Java, Apache Maven en Runtime versies (7.19 is standaard met Runtime 4.8, dus 4.6 moet je er even zelf bij installeren). Dit werkt prima, maar als je vaak in een terminal of powershell je Maven commando zelf uitvoert moet je zelf ook de nieuwe versies van Java en Maven downloaden. Voor deze upgrade heb je minimaal Maven 3.9.X nodig, daarbij gebruik je ook minimaal de Mule Maven plugin 4.2. Zelf adviseer ik om deze versies allemaal naast elkaar te draaien (Anypoint Studio, Maven, Java) zodat je in transitie gemakkelijk kan wisselen. Om op je systeem te wisselen tussen de verschillende versies kun je gebruik maken van het volgende simpele script (Windows):
@echo off
if “%~1” == “17” (
set “JAVA_HOME=<dir>\Java\jdk17”
set “MAVEN_HOME= <dir>\apache-maven-3.9.9”
) else (
set “JAVA_HOME=v\Java\jdk1.8”
set “MAVEN_HOME= <dir>\apache-maven-3.6.6”
)
set “Path=%JAVA_HOME%\bin;%MAVEN_HOME%\bin;%Path%”
mvn -version
Door dit .bat bestand uit te voeren met argument ‘17’ wordt je Java en Maven versie beide op de gewenste versie gezet in je terminal.
De upgrade van je project
Het upgraden van een project is niet heel complex. Als je gebruikt maakt van de standaard MuleSoft componenten en weinig ‘custom’ connectoren of bibliotheken gebruikt dan is de complexiteit niet zo hoog, maar er zijn wel een aantal zaken waar je rekening mee moet houden. Laten we hier stap voor stap doorheen gaan.
Stap 1: importeer je project
Het begint met het importen van je project in je nieuwe Workspace. Gebruik hier de file à import à Anypoint Studio project van File System.
Stap 2: Upgrade naar nieuwste Runtime en Java-versie
In principe zal Anypoint studio niet verpakt zijn met Mule 4.4 en zal het project automatisch de standaard Runtime pakken. Voor Java geldt echter dat je ook Java 8 kan gebruiken. Als je niet naar Java 17 gaat ben je hier eigenlijk al klaar. Je kan het project runnen en deze zou moeten werken omdat alle connectoren en modules voorheen al met Java 8 werkten. Wij willen echter verder, en daarom gaan we de Java-versie aanpassen naar 17. Dit doen we door een rechtermuisklik op het project à build path te drukken. Hier kun je vervolgens kiezen welke Java-versie je wil gebruiken. Selecteer de Java-bibliotheek en druk op Edit. Nu kun je als het goed is kiezen voor Java 17:
Druk op Finish à Apply en je project zal wijzigen naar Java 17. Anypoint Studio zal nu automatisch herkennen welke connectoren en modules in je project Java 17 niet ondersteunen en biedt meteen de mogelijkheid deze te upgraden naar een juiste versie:
Dit wordt dan ook direct aangepast on je pom.xml. Dit werkt wel handig, maar let op dat niet geldt voor alle afhankelijkheden. Als je project nog andere bibliotheken (.jar bestanden) gebruikt, bijvoorbeeld voor een JMS-implementatie, dan zul je deze (wellicht) zelf ook nog moeten upgraden. Bekijk hiervoor de documentatie van de desbetreffende bibliotheek. Hiermee zijn we eigenlijk al klaar en kun je het project lokaal kunnen draaien. Het is echter ook handig om je mule-artifact.json aan te passen voor je packaging configuratie:
{
“minMuleVersion”: “4.6.9”,
“javaSpecificationVersions”: [“17”],
“secureProperties”: []
}
Stap 3: Update API Manager
Voordat we daadwerkelijk de applicatie gaan uitrollen is het ook nog belangrijk om de versies van de (eventuele) toegepaste policies te updaten. Deze draaien immers ook in de Mule Runtime en moeten dus ook voldoen aan de (vernieuwde) eisen. Sommige hiervan zijn natuurlijk een tijd geleden geconfigureerd en daarmee alleen Java 8 zouden kunnen ondersteunen. Login bij Anypoint platform en update de policies van je API Manager entry. Tegenwoordig kun je met 1 druk op de knop checken op updates en deze toepassen:
Overigens geeft API en Runtime manager ook een waarschuwing (in de UI) wanneer je een API uitrolt waarvan de policy niet de juiste versie heeft (maar dan ben je eigenlijk te laat).
Stap 4: Deployment
Nu we alle zaken naar de juiste versies hebben gebracht kunnen we de applicatie uitrollen naar de target. We gaan ervan uit dat dit gebeurt door gebruik te maken van de Maven plugin die veel gebruikt wordt in geautomatiseerde (CI/CD) pipelines. Handig om te weten is dat deze plugin ook geüpdatet moet worden naar minimaal versie 4.X. Met een kleine configuratie in je pom.xml kun je vervolgens de applicatie onder de nieuwe Runtime en Java-versie uitrollen. Zie hieronder een voorbeeld van de Cloudhub 1.0 configuratie:
<cloudHubDeployment>
<uri>https://anypoint.mulesoft.com</uri>
<muleVersion>${anypoint.runtime}</muleVersion>
<releaseChannel>${app.release.channel}</releaseChannel>
<javaVersion>${app.java.version}</javaVersion>
<environment>Sandbox</environment>
<applicationName>countries</applicationName>
…
</cloudHubDeployment>
Met name de muleVersion en javaVersion dienen geconfigureerd te worden:
- muleVersion: 4.6-java17
- releaseChannel: LTS
- javaVersion: 17
Dit uiteraard naast de overige configuratie elementen; hiermee kun je vervolgens met een simpele mvn deploy -DmuleDeploy commando je applicatie uitrollen. Bovenstaand wordt trouwens op deze pagina stap voor stap uitgelegd.
Tips
In de bovenstaande beschrijving gaan we uit van een op zichzelf staand project, maar uiteraard werken (corporate) organisaties met de nodige templates, Git en CI/CD tools en heb je te maken met kritische integraties en APIs welke natuurlijk niet mogen uitvallen vanwege een upgrade. Daarom hieronder nog een aantal tips en aandachtsgebieden waar je aan kan denken bij deze activiteiten.
Parent POM
De meeste organisaties gebruiken één of meerdere ‘parent poms’ waarin de standaard configuraties en afhankelijkheden in zitten. Voordeel van deze aanpak is dat je hiermee een veel meer gestandaardiseerd project kan bouwen en onderhouden met (Apache) Maven. Hierin neem je vaak dan al de standaard afhankelijkheden op voor (bijvoorbeeld) je RESTful projecten. Je hebt in het van de upgrade verschillende mogelijkheden, maar je zou kunnen kiezen voor een strategie dat je de parent pom met een minor versie ophoogt en hierin alleen de Runtime versie ophoogt naar 4.6 en dat je daarnaast een major versie aanmaakt waarin je ook de Java 17 upgrade meeneemt (Runtime versie en afhankelijkheden). Je teamleden hoeven dan alleen de paren pom verwijzing naar de nieuwe versie te wijzigen om direct het project geüpgraded te hebben.
API Manager
Zoals aangegeven kunnen de policies die toegepast zijn op je API vrij oud zijn. Als dit als manuele taak wordt uitgevoerd moet dit goed zijn beschreven in de upgrade guide. Een alternatief is het geautomatiseerd updaten van je policy door gebruikt te maken van de Anypoint CLI of Anypoint platform APIs. Hoe je deze kan gebruiken wordt uitgelegd op developer.mulesoft.com. Vervolgens kun je met de volgende call je policy upgraden
curl
‘https://anypoint.mulesoft.com/apimanager/api/v1/organizations/<orgId>/environments/<envId>/apis/<apiVersionId>/policies/<policyId>’ \
-X ‘PATCH’ \
-H ‘Accept: application/json, text/plain, */*’ \
-H ‘Authorization: <token>’ \
–data-raw ‘{“groupId”:<policyGroupId>, “assetId”:<policyAssetId>,”assetVersion”:
<latestPolicyVersion>,”apiId”:<apiVersionId>}’
Door dit in je CI/CD pipeline op te nemen kun je het risico mitigeren dat je policies niet geüpdatet zijn tijdens de uitrol.
Error object
Een belangrijke observatie bij deze upgrade is het feit dat niet zomaar meer je de waardes uit je error object kan halen. Waar je voorheen nog iets als ‘error.errorType.toString()’ kon doen zal dit nu een fout opleveren dat je de juiste ‘getter’ methode moet gebruiken. En dit geldt ook voor verschillende connectors. Let bij de upgrade dus met name goed op hoe je omgaat met excepties en of je waardes uit het error object extraheert.
Testen & Monitoring
Tenslotte mag een goede teststrategie niet ontbreken. Hierin kan onderscheid gemaakt worden tussen de meer kritische of minder kritische applicaties waarbij er in meer-of mindere mate getest wordt. Belangrijk advies is om een issue log bij te houden waar issues die gerelateerd zijn aan de upgrade gelogd worden zodat deze bekend zijn en ook in andere APIs (applicaties) aangepast of opgelost worden.
Tenslotte is het ook aan te raden om goed te monitoren na een eventuele release. Indien er meer fouten zichtbaar zijn dan voor de uitrol (uitgaande van een as-is upgrade zonder wijzigingen) dan zou dit een teken kunnen zijn dat er toch iets mis is. Zet eventueel alerts om hier actief op gealarmeerd te worden, met name bij kritische APIs kun je dan proactief een rollback doen en verdere business impact voorkomen.
