AWS lokal entwickeln mit Serverless Framework Offline Plugins

Wer mit dem Serverless Framework auf AWS entwickelt, kann dies mit ein wenig Aufwand auch lokal auf dem eigenen Rechner tun. Hierfür gibt es eine Vielzahl verfügbarer Plugins, um Services wie z. B. Lambdas, DynamoDB oder S3 lokal zu nutzen. Wie ihr damit einsteigen könnt, zeige ich in diesem Artikel über Serverless Framework Offline Plugins.

Ich beschränke mich in diesem Beispiel darauf, einen AWS Stack basierend auf Node.js , API Gateway, Lambdas und einer DynamoDB lokal aufzusetzen und zu starten. Das Beispiel ist auf das Wesentliche reduziert und ich werde nur auf die relevanten Stellen der Offline-Plugins eingehen.

Wozu Offline-Plugins?

Es gibt sehr viele gute Gründe, cloudbasierte Services einzusetzen. Unser Blog ist voll von tollen Beispielen dafür, was sich da so tun lässt. Ein paar Beispiele wären:

• Der Artikel Serverless done right. Von der Idee zum MVP in 7 Tagen. , in dem mein Kollege Philipp sein Serverless-Projekt beschreibt.
• Eigene Website in der AWS Cloud hosten: Tutorial für Anfänger zeigt euch, wie ihr eine eigene Website bei AWS hosten könnt.

Für Entwickler entstehen allerdings auch Hürden, die in klassischen Ansätzen weniger ausgeprägt waren. Wenn Entwicklungs-Umgebungen nur noch beim Cloud-Provider liegen, dauert es meist erheblich länger und ist mit deutlich mehr Aufwand verbunden, bis eine Änderung am Quellcode tatsächlich sichtbar wird.

Wenn ihr auf dem Serverless Framework unterwegs seid, könnt ihr die vielen verfügbaren Offline-Plugins nutzen, um euer Projekt lokal auf dem eigenen Rechner laufen lassen. Die Idee ist: Der gleiche Code, der lokal läuft, läuft auch in der Cloud.

Voraussetzungen

Ihr solltet zumindest Grundkenntnisse mit dem Serverless Framework mitbringen und dieses auch installiert haben. Ihr könnt leicht prüfen, ob dies der Fall ist, indem ihr

1$ serverless --version

ausführt und schaut, ob es eine gültige Version zurückliefert.

Darüber hinaus solltet ihr Node.js installiert haben und auch rudimentär verstehen.

Falls ihr euch dafür interessiert, Node.js Webanwendungen mit Express zu entwickeln, ist vielleicht der Artikel Rezepte für Webanwendungen mit Node.js, Express.js und TypeScript interessant für euch!

Vorbereitung

Wenn ihr das Projekt nachvollziehen möchtet, klont es zunächst aus diesem Repository . Wir benötigen außerdem einige Plugins. Die Statements:

1$ npm install aws-sdk
2$ npm install express
3$ npm install serverless-http
4$ npm install serverless-dynamodb-local
5$ npm install serverless-offline
6$ sls dynamodb install

installieren alle erforderlichen Plugins. serverless-dynamodb-local und serverless-offline sind die Kandidaten, die uns die lokale Nutzung ermöglichen.

Plugins konfigurieren

Wenn ihr die Plugins installiert habt, müssen sie nun im serverless Projekt eingebunden werden. Dies geschieht im plugins-Block

1plugins:
2  - serverless-dynamodb-local
3  - serverless-offline  # should be last in list

der serverless.yml-Datei. Hierdurch werden die Plugins unserem Projekt bekannt gemacht. Darüber hinaus benötigen wir ein wenig Konfiguration, die wir der custom-Sektion hinzufügen:

1tableNames:
2  persons: 'cc-persons'
3    
4dynamodb:
5  start:
6    migrate: true
7  stages:
8    - dev

tableNames definiert den Namen der DynamoDB-Tabelle, damit er an anderer Stelle wiederverwendet werden kann. migrate sorgt dafür, dass die benötigten DynamoDB-Tabellen direkt beim Start angelegt werden.

In Projekten, die keine lokalen Plugins verwenden, kümmert sich das AWS SDK automatisch um die AWS-Konfiguration. Für local Plugins gilt das nur eingeschränkt: Wir müssen dem SDK später den DynamoDB-Endpunkt mitteilen. Deswegen konfigurieren wir diesen über

1custom:
2  endpoints:
3    dynamodb-url: 'http://localhost:8000'

vorab und machen die benötigten Werte via

1provider:
2  environment:
3    CONFIG_PERSONS_TABLE: ${self:custom.tableNames.persons}
4    CONFIG_DYNAMODB_ENDPOINT: ${self:custom.endpoints.dynamodb-url}

für die spätere Nutzung als Umgebungsvariablen bekannt. Zum Schluss müssen wir noch eine DynamoDB-Tabelle erzeugen. Hierzu fügen wir eine Ressource hinzu, die in der Datei resources/persons-table.yml beschrieben wird, und binden diese über

1resources:
2  - ${file(resources/persons-table.yml)}

in den resources-Block der serverless.yml-Datei ein.

Einbinden von DynamoDB im Node.js Lambda

Das Serverless Framework wird sich darum kümmern, die Tabelle anzulegen. Den Zugriff auf die Tabelle implementieren wir jedoch selbst in den Node.js Lambdas.
Hierzu beinhaltet das Projekt bereits zwei einfache Services, die in der serverless.yml im functions Block definiert sind:

• GET auf /persons
• POST auf /persons

Die Implementierung hierzu liegt unter handler/persons.js. Sie verwendet das Express Framework , die Details sind für uns aber nicht relevant.

Alle Aufrufe gegen die DynamoDB aus unseren Lambdas heraus werden durch das AWS SDK gekapselt. Allerdings weiß dieses noch nichts von unserer lokalen DynamoDB, und würde sich direkt gegen AWS verbinden. Wir müssen dem AWS SDK daher zunächst den zu nutzenden DynamoDB-Endpunkt mitteilen – zumindest wenn wir uns im Offline-Modus befinden.

Um herauszufinden, ob wir uns im Offline-Modus befinden, stellt das serverless Offline-Plugin eine Umgebungsvariable bereit, die wir abfragen können: IS_OFFLINE. Wir können die Variable nutzen, um eine Weiche zu bauen, die den Endpunkt im lokalen Modus überschreibt.

1const CONFIG_PERSONS_TABLE = process.env.CONFIG_PERSONS_TABLE;
2const CONFIG_DYNAMODB_ENDPOINT = process.env.CONFIG_DYNAMODB_ENDPOINT;
3const IS_OFFLINE = process.env.IS_OFFLINE;
4 
5let dynamoDb;
6if (IS_OFFLINE === 'true') {
7  dynamoDb = new AWS.DynamoDB.DocumentClient({
8    region: 'localhost',
9    endpoint: CONFIG_DYNAMODB_ENDPOINT,
10  });
11} else {
12  dynamoDb = new AWS.DynamoDB.DocumentClient();
13}

Über diesen Mechanismus wird im lokalen Modus ein anderer Endpunkt verwendet, als im normalen Modus, nämlich den, den wir in der serverless.yml als Umgebungsvariable CONFIG_DYNAMODB_ENDPOINT definiert haben.

Funktionstest

Alles andere an Quellcode in diesem Projekt unterscheidet sich nicht von der Entwicklung ohne Offline-Plugins, daher ist er an dieser Stelle nicht interessant. Wir haben soweit aber bereits alles angepasst und möchten das ganze nun gerne ausprobieren. Mit dem Statement

1$ serverless offline start

wird das ganze Projekt lokal gestartet. Ob alles funktioniert, erkennt ihr an der Log-Ausgabe, zum Beispiel

1Dynamodb Local Started, Visit: http://localhost:8000/shell
2Serverless: DynamoDB - created table cc-persons
3Serverless: Starting Offline: dev/eu-central-1.
4Serverless: Offline [HTTP] listening on http://localhost:3000

Es wurde also eine lokale DynamoDB gestartet, und die Tabelle cc-persons wurde angelegt. Probieren wir nun aus, ob unsere Services funktionieren, in dem wir die Statements:

1$ curl -XPOST localhost:3000/persons
2$ curl localhost:3000/persons

nacheinander ausführen. Dies sollte eine neue Person anlegen und diese dann ausgeben.

Mehr Möglichkeiten

Für das serverless Framework gibt es eine große Zahl weiterer Offline-Plugins, ich habe zum Beispiel serverless-offline-ssm und serverless-s3-local erfolgreich im Einsatz. Die Nutzung von Serverless Offline-Plugins ermöglicht es Entwicklern, einen kompletten AWS Stack lokal und isoliert zu entwickeln, ohne jederzeit die Cloud-Infrastruktur verfügbar zu haben. Hierdurch reduziert sich die Dauer der Entwicklungs-Zyklen, da Änderungen ohne Deployment direkt sichtbar werden.

Fragen, Wünsche, Anregungen? Lasst einfach einen Kommentar hier und ich sehe was ich tun kann 🙂