Einführung privater APIs bei AWS AppSync

von Ozioma Uzoegwu, übersetzt durch Matt Pawelcyzk

AWS AppSync erstellt Serverless-GraphQL- und -Pub/Sub-APIs, die die Anwendungsentwicklung über einen einzigen Endpunkt vereinfachen, um Daten sicher abzufragen, zu aktualisieren oder zu veröffentlichen. Wenn Sie eine GraphQL-API auf AWS AppSync erstellen, wird ein öffentlicher Endpunkt generiert, der verwendet werden kann, um Abfragen, Mutationen und Abonnementanfragen an die API zu senden. Clients in einem privaten Netzwerk, wie einer Amazon Virtual Private Cloud (VPC) oder einem lokalen Netzwerk, benötigen hierbei eine Netzwerkroute über das Internet, um den öffentlichen AppSync-Endpunkt zu erreichen. Dies kann eine Herausforderung für Kunden sein, die ihre Sicherheitsrichtlinien und Firewallregeln ändern müssen, um Anfragen an die AppSync-API zu senden.

Seit Anfang Mai sind private APIs bei AWS AppSync nun generell verfügbar. Mit privaten APIs können Sie den Zugriff auf Ihre GraphQL-APIs auf Clients innerhalb eines privaten Netzwerks einschränken, z. B. einer VPC oder eines lokalen Rechenzentrums. Anfragen an Ihre private API werden über das private Netzwerk von AWS anstatt über das öffentliche Internet gesendet. Zunächst können Sie Ihre API bei der Erstellung Ihrer GraphQL-API auf AWS AppSync als privat festlegen und an jede der VPCs im selben AWS-Konto, von dem aus Sie die API aufrufen, einen Schnittstellen-VPC-Endpunkt anhängen. Sie können auch AWS Direct Connect oder AWS Site-to-Site VPN verwenden, um eine private Verbindung von Ihrem lokalen Netzwerk zur VPC herzustellen, die den Schnittstellenendpunkt hostet. Mit dieser Verbindung können Kunden auch in Ihrem lokalen Rechenzentrum die private API aufrufen.

Das folgende Diagramm zeigt, wie Sie von einer, im VPC ausgeführten, Anwendung aus, eine Verbindung zu Ihrer privaten API in AWS AppSync herstellen können.

Architekturbild mit zwei Amazon EC2 Instanzen, einem NAT-Gataway, einem Internet-Gateway, einem Schnittstellenendpunkt für AWS AppSync sowie AWS PrivateLink und AWS AppSync

Bild 1: Beispielarchitektur für die Verbindung zur private AppSync-API von Amazon VPC

In diesem Beispiel verwenden Sie Amazon Elastic Compute Cloud (EC2) als Rechenplattform, von der aus die API aufgerufen wird. Die Architektur wird eine ähnliche Konfiguration haben, wenn andere Rechenplattformen wie AWS Lambda oder AWS Fargate zum Aufrufen der API verwendet werden. GraphQL-Anfragen von Ihrer Anwendung werden über den Schnittstellenendpunkt an AWS AppSync weitergeleitet. Der Schnittstellenendpunkt verwendet AWS PrivateLink, eine hochverfügbare, skalierbare Technologie, mit der Sie Ihre VPC privat mit Services wie AWS AppSync (und anderen Services von AWS sowie Drittanbietern) verbinden können, als ob sich diese in Ihrer VPC befinden. Ein AWS PrivatLink Endpunkt kann in jedem der Subnetze Ihrer VPC bereitgestellt werden. Es wird empfohlen, mindestens einen Endpunkt in jeder Availability Zone (AZ) bereitzustellen, um Hochverfügbarkeit zu gewährleisten.

Erstellen und verbinden zu einer privaten AppSync-API

In diesem Abschnitt erstellen Sie eine private API auf AWS AppSync und rufen die API dann von einer EC2-Instanz aus auf, die in einer VPC ausgeführt wird. Sie werden Folgendes tun:

Erstellen einer einfachen ToDo-API mit einer privaten API
Erstellen eines VPC, verteilt auf zwei Availability Zones (AZs), mit jeweils öffentlichen und privaten Subnetzen
Anhängen eines Schnittstellenendpunkt für AWS AppSync an die privaten VPC-Subnetze
Aufrufen der API von EC2-Instanzen aus auf, die in den privaten Subnetzen bereitgestellt werden

Erstellen einer privaten AppSync-API

Navigieren Sie zur AppSync-Konsole und klicken Sie auf API erstellen.
Wählen Sie in Schritt 1 des Assistenten zur API-Erstellung die Optionen GraphQL APIs sowie Design from scratch (deutsch: „von Grund auf erstellen“) aus und klicken Sie auf Weiter. Hinweis: Sie können bei Auswahl von Import aus DynamoDB sowie Create a real-time API (deutsch: Erstellen einer Echtzeit-API) ebenfalls private APIs erstellen.

Bild 2 — Select API Type (Wählen Sie den API-Typ)
Geben Sie in Schritt 2 einen Namen für die API ein und aktivieren Sie das Kontrollkästchen Verwenden von privaten API-Funktionen im Abschnitt Private API-Konfigurationen und klicken Sie auf Weiter. Mit der Auswahl dieses Kontrollkästchen wird Ihre API privat.

Bild 3 — Angeben von API-Metadaten
Wählen Sie in Schritt 3 unter GraphQL-Typs erstellen die Option Erstellen Sie jetzt einen Typ mit Unterstützung einer DynamoDB-Tabelle, und geben Sie unter Modellinformationen einen Namen für den GraphQL-Typ (Modellname) ein und geben Sie dann die Felder und den entsprechenden Datentyp für jedes Feld an. Geben Sie dann einen Namen für die DynamoDB-Tabelle, den Primärschlüssel (Primary Key) und den Sortierschlüssel (Sort Key) ein und klicken Sie anschließend auf Weiter.

Bild 4 — Angeben von GraphQL-Ressourcen
Überprüfen Sie in Schritt 4 die API-Details und klicken Sie dann auf API erstellen. Die Erstellung der API- und DynamoDB-Tabelle beginnt. Sobald der Vorgang abgeschlossen ist, navigieren Sie zur Seite mit den API-Einstellungen, um den neuen Status Private API Ein zu sehen. Dieser Status gib an, dass die API privat ist. Ferner sehen Sie an privaten APIs in der Liste der AppSync-APIs, die Sie in der Region erstellt haben, ein Vorhängeschloss-Symbol.

Bild 5: AppSync-Einstellungsseite mit eingeschalteter privater API

Erstellen Sie ein VPC mit öffentlichen und privaten Subnetzen

Sie können eine VPC mithilfe des VPC-Assistenten auf der VPC-Konsole erstellen. Sie können die VPC-Einstellungen konfigurieren, um eine VPC mit zwei öffentlichen und privaten Subnetzen, Routing-Tabellen, Internet-Gateway und NAT-Gateway zu erstellen, wie unten gezeigt. In den Vorschauabschnitten werden die Ressourcen angezeigt, die erstellt werden. Stellen Sie sicher, dass die Optionen DNS-Auflösung aktivieren und DNS-Hostname aktivierenausgewählt sind (weitere Informationen zu diesen beiden Werten finden Sie in der VPC-Dokumentation (zur Zeit der Publikation noch nicht ins Deutsche übersetzt)).

Bildschirmfoto der Erstellungsseite für VPCs in der AWS Management-Konsole

Bild 6: Erstellung eines vordefinierten VPC-Layout

Erstellen Sie eine Sicherheitsgruppe für den Schnittstellenendpunkt

Navigieren Sie zur Amazon EC2-Konsole und wählen Sie im linken Navigationsbereich Sicherheitsgruppen und anschließend Sicherheitsgruppe erstellen aus.
Wählen Sie einen Namen für die Sicherheitsgruppe, z. B. appsync-private-api-endpunkt-sg.
Für den VPC wählen Sie das zuvor erstellte VPC aus.
Bei den Regeln für eingehenden Datenverkehrund Regeln für ausgehenden Datenverkehr, erlauben Sie HTTPS für alle eingehenden Verbindungen aus dem VPC. Sie können die Sicherheitsgruppe so konfigurieren, dass sie auf den Subnetz-IP-Adressbereich oder die IP-Adresse der Ressource beschränkt wird, die die API aufruft.

Bild 7: Erstellungsseite der Sicherheitsgruppe für den Schnittstellenendpunkt

Erstellen Sie einen Schnittstellenendpunkt für AWS AppSync

Navigieren Sie zur Amazon VPC-Konsole und wählen Sie im linken Navigationsbereich Endpunkte und dann Endpunkte erstellen aus.
Sie können ein Namens-Tag für den Endpunkt angeben, z. B. appsync-privater-api-endpunkt.
Behalten Sie für die Servicekategorie die Option AWS-Services bei.

Bild 8: Oberer Ausschnitt der Erstellungsseite für den VPC-Endpunkt
Geben Sie den Service-Name com.amazonaws.{region}.appsync-api an, wobei Sie {region} durch die aktuelle Region, in der Sie gerade arbeiten, ersetzen.
Wählen Sie bei VPC das zuvor erstellte VPC aus.
Erweitern Sie den Abschnitt Zusätzliche Einstellungen und stellen Sie sicher, dass das Kontrollkästchen DNS-Namen aktivieren ausgewählt ist. Dies verknüpft eine private gehostete Zone mit dem VPC, welche einen Datensatz enthält, der es Ihnen ermöglicht, die private Netzwerkkonnektivität von Amazon zum AppSync-Dienst zu nutzen, während Sie Anfragen über die AppSync-API-URL stellen (z. B. https://{api_url_identifizierer}.appsync-api).{region}.amazonaws.com/graphql).

Bild 9: VPC-Endpunkt erstellen — Dienstnamen auswählen
Wählen Sie die beiden AZs (Verfügbare Zone) und ein Subnetz in jedem AZ aus, um den Endpunkt bereitzustellen. Sie können z.B. die privaten Subnetze dort auswählen.
Für Sicherheitsgruppen wählen Sie die zuvor erstellte Sicherheitsgruppe appsync-private-api-endpunkt aus.
Für die VPC Endpunktrichtlinie wählen Sie Vollzugriff aus, damit jeder AWS-Principle die private API aufrufen kann. Wenn Sie den Identity and Access Management (IAM)-Autorisierungsmodus für Ihre AppSync-API verwenden, ist es empfehlenswert, die benutzerdefinierte Richtlinie so zu erweitern, dass die erforderlichen Berechtigungen nur den erforderlichen IAM-Benutzern und -Rollen gewährt werden.
Belassen Sie die anderen Optionen wie voreingestellt und wählen Sie Endpunkt erstellen aus.

Bild 10: Wählen Sie Subnetze, Sicherheitsgruppen und Endpunktrichtlinien aus

Aufrufen der privaten API von den EC2-Instanzen aus

Um die API aufzurufen, werden Sie eine EC2-Instanz im privaten Subnetz verwenden. Sie können AWS System Manager Session Manager verwenden, um eine Verbindung zur EC2-Instanz herzustellen, und VPC Reachability Analyzer zur Behebung von Verbindungsproblemen.

Um nun die private API aufzurufen, können Sie zwei verschiedene DNS-Namen (Domain Name System) verwenden:

Private DNS-Namen (wenn Sie DNS-Namen aktivieren bei der Erstellung des VPC-Endpunktes ausgewählt haben)
DNS-Namen des VPC-Endpunkt

Auf der Detailseite der VPC-Endpunkte werden diese beiden DNS-Namen wie unten dargestellt angezeigt.

Bildschirmfoto zur Übersicht der DNS Daten zum erstellten privaten Endpunkt.

Bild 11: VPC-Detailseite

Bei Private DNS-Namen hat die Basis-URL zum Aufrufen der API das Format https://{api_url_identifizierer}.appsync-api.{region}.amazonaws.com/graphql. Das ist dieselbe API-URL, die von AWS AppSync generiert wurde, als die private API erstellt wurde (weitere Informationen finden Sie auf der AppSync-API-Einstellungsseite in der AppSync-Konsole). Bei der Verwendung von privatem DNS müssen Sie keine Änderungen an Ihrer Anwendung vornehmen, wenn diese bereits die von AWS AppSync generierte API-URL verwendet.

Bei der Schnittstelle VPC-Endpunkt, öffentliche DNS-Hostnamen, hat die Basis-URL zum Aufrufen der API das Format https://{vpc_endpunkt_id}-{endpunkt_dns_identifizierer}.appsync-api.{region}.vpce.amazonaws.com/graphql oder Sie können auch den AZ-spezifischen DNS-Hostnamen verwenden, wenn Sie einen Endpunkt in der AZ bereitgestellt haben mit https://{vpc_endpunkt_id}-{endpunkt_dns_identifizierer}-{az_id}.appsync-api.{region}.vpce.amazonaws.com/graphql.

Wenn Sie den öffentlichen Hostnamen des VPC-Endpoints verwenden, muss der AppSync-API-Endpunkt-Hostname als Host-Header oder x-appsync-domain-Header an die Anfrage übergeben werden (siehe Beispiel unten).

$ curl -v https://{vpc_endpunkt_id}-{endpoint_dns_identifizierer}.appsync-api.{region}.vpce.amazonaws.com/graphql \
-H "Content-Type:application/graphql" \
-H "x-api-key:da2-{xxxxxxxxxxxxxxxxxxxxxxxxxx}" \
-H "Host:{api_url_identifizierer}.appsync-api.{region}.amazonaws.com" \
-d '{"query": "mutation createTodo($createtodoinput: CreateTodoInput!) {createTodo(input: $createtodoinput) {id Titel Beschreibung Prioritaet}}","variables":"{\"createtodoinput\": {\"Titel\": \"Hello, world!\",\"Beschreibung\": \"Hello, world!\",\"Prioritaet\": 4}}"}'

Um die ToDo-Beispiel-API zu testen, verwende Sie die Private DNS, um die API aufzurufen. Sie können jedes Befehlszeilentool Ihrer Wahl verwenden, beispielweise können Sie curl nutzen, um Abfragen und Mutationen zu senden, und wscat, um ein Abonnement einzurichten. Auf Amazon EC2 Linux müssen Sie npm installieren, das für die Installation von wscat erforderlich ist. Ersetzen Sie alle Werte in der geschweiften Klammer durch die entsprechenden Werte aus Ihrem AWS-Konto. Den x-api-key finden Sie auf der Einstellungsseite der API auf AWS AppSync.

Mutations-Befehl testen — CreateToDo-Anfrage

$ curl -v https://{vpc_endpunkt_id}-{endpoint_dns_identifizierer}.appsync-api.{region}.vpce.amazonaws.com/graphql \
-H "Content-Type:application/graphql" \
-H "x-api-key:da2-{xxxxxxxxxxxxxxxxxxxxxxxxxx}" \
-H "Host:{api_url_identifizierer}.appsync-api.{region}.amazonaws.com" \
-d '{"query": "mutation createTodo($createtodoinput: CreateTodoInput!) {createTodo(input: $createtodoinput) {id Titel Beschreibung Prioritaet}}","variables":"{\"createtodoinput\": {\"Titel\": \"Emails lesen!\",\"Beschreibung\": \" Emails lesen!\",\"Prioritaet\": 4}}"}'

Mutations-Befehl testen — CreateToDo-Antwort

{
	"data": {
		"createTodo": {
		"id": "bf6025a3-d0ea-46f6-91f8-96c9726f4e22",
		"Titel": "Emails lesen!",
		"Beschreibung": " Emails lesen!",
		"Prioritaet": "4"
		}
	}
}

Query-Befehl testen — ListToDos-Anfrage

$ curl -v https://{api_url_identifier}.appsync-api.{region}.amazonaws.com/graphql \
-H "Content-Type:application/graphql" \
-H "x-api-key:da2-{xxxxxxxxxxxxxxxxxxxxxxxxxx}" \
-d '{"query": "query listTodos {listTodos {items {id Titel Beschreibung Prioritaet}}}","variables":"{}"}'

Query-Befehl testen — ListToDos-Antwort

{
	"data": {
		"listTodos": {
			"items": [
				{
				"id": "0df53f0d-d9b1-4f06-98e9-311d68f642b1",
				"Titel": "Hello, world!",
				"Beschreibung": "Hello, world!",
				"Prioritaet": "4"
				},
				{
				"id": "bf6025a3-d0ea-46f6-91f8-96c9726f4e22",
				"Titel": "Emails lesen!",
				"Beschreibung": " Emails lesen!",
				"Prioritaet": "4"
				}
			]
		}
	}
}

Abonnement-Befehl testen — CreateToDo-Änderungen abonnieren

Einzelheiten zum Einrichten von GraphQL-Abonnements auf AppSync finden Sie unter Aufbau eines WebsSocket Echtzeit-Clients. Verwenden Sie die EC2-Instanz im privaten Subnetz in AZ1 als Client, welche die Abonnementanfrage für das OnCreateToDo-Abonnement initiiert, und die EC2-Instanz im privaten Subnetz in AZ2 als den Client, der die createToDo-Mutation aufruft.

Führen Sie folgenden Befehl auf der EC2-Instanz im privaten Subnetz in AZ1 aus:

$ header=`echo '{"host":"{api_url_identifier}.appsync-api.{region}.amazonaws.com","x-api-key":"da2-{xxxxxxxxxxxxxxxxxxxxxxxxxx}"}' | base64 -w0`
$ wscat -p 13 -s graphql-ws -c  "wss://{api_url_identifier}.appsync-realtime-api.{region}.amazonaws.com/graphql?header=$header&payload=e30="
Connected (press CTRL+C to quit)
> a
< {"type":"connection_ack","payload":{"connectionTimeoutMs":300000}}
< {"type":"ka"}
> {"id":"f7a49717","payload":{"data":"{\"query\":\"subscription onCreateTodo {onCreateTodo {Beschreibung id Prioritaet Titel}}\",\"variables\":{}}","extensions":{"authorization":{"x-api-key":"da2-{xxxxxxxxxxxxxxxxxxxxxxxxxx}","host":"{api_url_identifier}.appsync-api.{region}.amazonaws.com"}}},"type":"start"}
< {"id":"f7a49717","type":"start_ack"}

Führen Sie auf der EC2-Instanz im privaten Subnetz in AZ2 die folgende createToDo-Mutation aus:

$ curl -v https://{api_url_identifier}.appsync-api.{region}.amazonaws.com/graphql \
-H "Content-Type:application/graphql" \
-H "x-api-key:da2-{xxxxxxxxxxxxxxxxxxxxxxxxxx}" \
-d '{"query": "mutation createTodo($createtodoinput: CreateTodoInput!) {createTodo(input: $createtodoinput) {id Titel Beschreibung Prioritaet}}","variables":"{\"createtodoinput\": {\"Titel\": \"Gehe ins Geschaeft\",\"Beschreibung\": \"Gehe ins Geschaeft\",\"Prioritaet\": 5}}"}'

Auf der EC2-Instanz im privaten Subnetz in AZ1 sehen Sie, dass die Abonnementbenachrichtigung ausgelöst wurde und die Nachrichtenbenachrichtigung wie unten gezeigt angezeigt wird

< {"id":"f7a49717","type":"data","payload":{"data":{"onCreateTodo":{"Beschreibung":"Gehe ins Geschaeft","id":"b1369924-27d1-449f-b1d8-3daecea7f4e7","Prioritaet":"5","Titel":"Gehe ins Geschaeft"}}}}

Wichtige Dinge, die Sie wissen sollten

APIs können nur zum Zeitpunkt der Erstellung als privat eingerichtet werden. Eine API kann nicht nachträglich privat gemacht werden, und eine private API kann nicht geändert werden, nachdem sie erstellt wurde.
Wenn Sie den VPC-Schnittstellenendpunkt für AWS AppSync mit aktiviertem DNS-Namen einrichten, wird verhindert, dass Ressourcen in dem VPC andere öffentliche AppSync-APIs mithilfe der von AWS AppSync generierten API-URL aufrufen können. Dies liegt daran, dass die Anfrage an die öffentliche API über den Schnittstellenendpunkt weitergeleitet wird, was für öffentliche APIs nicht zulässig ist. Um in diesem Szenario öffentliche APIs aufzurufen, wird empfohlen, benutzerdefinierte Domainnamen auf öffentlichen APIs zu konfigurieren, die dann von Ressourcen in der VPC verwendet werden können, um die öffentliche API aufzurufen.
Mit einem VPC-Schnittstellenendpunkt für AWS AppSync können Sie auf jede private API in demselben AWS-Konto und derselben Region zugreifen. Um den Zugriff auf eine private API weiter einzuschränken, können Sie Folgendes in Betracht ziehen:
- Stellen Sie sicher, dass nur die erforderlichen Administratoren eine VPC-Endpunktschnittstelle für AWS AppSync erstellen können
- Verwenden Sie eine benutzerdefinierte VPC-Endpunktrichtlinie, um einzuschränken, welche APIs von Ressourcen in der VPC aus aufgerufen werden können
- Für Ressourcen in der VPC wird empfohlen, die IAM-Autorisierung zu verwenden, um AppSync-APIs aufzurufen. Denken Sie daran, sicherzustellen, dass den Ressourcen begrenzte Rollen für die APIs zugewiesen werden.
Um Ihre private API zu testen, muss der Testclient oder der Abfrage-Editor Anfragen über den VPC-Schnittstellenendpunkt für AWS AppSync an die API senden. Sie können Ihren Testclient entweder in Ihrer VPC oder im lokalen Rechenzentrum mit einer Netzwerkroute zum Schnittstellenendpunkt einrichten.

Fangen Sie noch heute an!

Private AppSync-APIs sind in allen AWS-Regionen verfügbar, in denen AWS AppSync heute verfügbar ist. In der Liste der verfügbaren AWS-Services nach Regionen finden Sie Informationen zu den Regionen, in denen AppSync verfügbar ist. Weitere Informationen zu privaten APIs finden Sie in der AppSync-Dokumentation.

AWS Germany – Amazon Web Services in Deutschland