Private und öffentliche APIs aus einer VPC via API Gateway aufrufen

API Gateway Domain Name

Der API Gateway Domain Name ist ein von AWS verwalteter Endpoint, der angelegt wird, sobald Sie für Ihre API einen Custom Domain Name konfigurieren. Er ist ein Alias für den Standard-Endpoint Ihrer API apiID.execute-api.REGION.amazonaws.com und ermöglicht TLS-Terminierung sowie sprechende URLs.

So funktioniert das im Detail:

1. Aufbau des API Gateway Domain Name für die beiden Typen öffentlicher API-Endpoints

• Edge-Optimized:

Verwendet eine CloudFront-Distribution (z. B. d123.cloudfront.net) für globalen Zugriff mit niedriger Latenz.

• Regional:

Verwendet einen regionsspezifischen Endpoint (z. B. d-abc123.execute-api.us-east-1.amazonaws.com).

2. DNS-Konfiguration

• Ihr DNS-Anbieter (z. B. GoDaddy):

Sie legen einen CNAME-Record an, der Ihren Custom Domain Name (api.mydomain.com) auf den API Gateway Domain Name (z. B. d-abc123.execute-api.us-east-1.amazonaws.com) verweist.

• Beispiel für einen GoDaddy-DNS-Record:

Name: api.mydomain.com

Typ: CNAME

Wert: d-abc123.execute-api.us-east-1.amazonaws.com

• Dieser Record sorgt dafür, dass Traffic an api.mydomain.com an den Endpoint des API Gateway weitergeleitet wird.

3. Zertifikatszuordnung

• AWS Certificate Manager (ACM) Zertifikat:

Wenn Sie im API Gateway einen Custom Domain Name definieren, verknüpfen Sie ihn mit einem ACM-Zertifikat (z. B. *.mydomain.com).

• Der Subject Alternative Name (SAN) des Zertifikats muss Ihren Custom Domain Name enthalten (z. B. api.mydomain.com oder die Top-Level-Wildcard *.mydomain.com).
• Das API Gateway nutzt dieses Zertifikat für die TLS-Terminierung am Edge.

4. Wie alles zusammenspielt — der Request-Flow

• Ein Client ruft https://api.mydomain.com. auf.
• DNS löst den Namen auf den API Gateway Domain Name auf (z. B. d-abc123.execute-api.us-east-1.amazonaws.com).
• Das DNS von AWS löst den API Gateway Domain Name auf die öffentlichen IPs des AWS-Gateway-Service auf, der TLS-Terminierung (mit Ihrem ACM-Zertifikat) und Load Balancing für Ihren Traffic übernimmt.
• Der API-Gateway-Service ruft die API und Stage auf, der Sie Ihren Custom Domain Name zugeordnet haben.

Im Kern dreht sich das Problem um den API Gateway VPC Endpoint, der für den Zugriff auf private APIs benötigt wird. Ist bei diesem VPC Endpoint Private DNS aktiviert, kann es beim Aufruf öffentlicher APIs zu Komplikationen kommen. Konkret können Aufrufe öffentlicher APIs an SSL-Zertifikatsproblemen scheitern. Um das zu verstehen, muss man wissen, wie die DNS-Auflösung in dieser Architektur abläuft (siehe Anhang A).

Eine öffentliche API ohne Custom Domain Name verfügt nur über eine öffentliche Endpoint-URL, die jeder aus dem Internet erreichen kann.

Da öffentliche APIs nur aus dem Internet aufgerufen werden können, versucht ein Aufruf dieser URL aus einer VPC mit API Gateway VPC Endpoint und aktiviertem Private DNS, die API innerhalb der VPC statt aus dem Internet aufzurufen — und liefert einen HTTP-403-Fehler (Forbidden) zurück.

Sobald öffentliche APIs auf einen Custom Domain Name abgebildet werden, benötigen sie ein Zertifikat.

Wenn Sie in Route 53 einen Alias-Record vom Typ A anlegen, um Ihre öffentliche API über Ihren Custom Domain Name aufzurufen, können Sie sowohl private als auch öffentliche APIs aus Ihrer VPC heraus erreichen — selbst dann, wenn ein API Gateway VPC Endpoint mit Private DNS konfiguriert ist.

Hosten Sie Ihre Domain bei einem externen Anbieter, können Sie dort einen CNAME-Record anlegen.

Genau dieser CNAME-Record ist die Ursache des Problems.

Wenn Sie eine öffentliche API mit einem Custom Domain Name aufrufen, wird ein DNS-Lookup ausgelöst, um den Record zu finden, der diesen Namen auf den API Gateway Domain Name abbildet. Daraufhin folgt ein zweiter DNS-Lookup, um die IP-Adresse des aus dem ersten Lookup zurückgegebenen API Gateway Domain Name zu ermitteln.

Ohne aktiviertes Private DNS liefert der Lookup die öffentliche IP Ihrer öffentlichen API zurück — genau das, was wir wollen.

Diese öffentliche IP gehört zum AWS-Gateway-Service, der dann in den Subject Alternative Names (SAN) des mit Ihrem Custom Domain Name verknüpften Zertifikats nach Ihrem Domain-Namen sucht. Da das Zertifikat Ihres Custom Domain Name (z. B. mydomain.com) mit dem API Gateway Domain Name verknüpft ist, gelingt der SSL-Handshake, und Ihre öffentliche API wird aufgerufen.

Hat eine VPC einen API Gateway VPC Endpoint mit aktiviertem Private DNS, fängt dieses Private DNS den Lookup für den API Gateway Domain Name ab (denn es fängt alle Subdomains von execute-api.REGION.amazonaws.com ) und liefert die private IP zurück, die der Elastic Network Interface (ENI) des VPC Endpoints zugewiesen ist.

Diese private IP repräsentiert die Adresse des API-Gateway-Service, der jedoch nur interne URL-Endpoints akzeptiert, die zur Endpoint-URL einer privaten API gehören und das Format apiID.execute-api.REGION.amazonaws.com haben.

Das Ergebnis sieht in etwa so aus:

Ergebnis eines Aufrufs einer öffentlichen API, wenn ein API Gateway VPC Endpoint mit aktiviertem Private DNS vorhanden ist

Folglich endet jeder Versuch, die öffentliche API aus der VPC heraus aufzurufen, in einem fehlgeschlagenen SSL-Handshake — die Verbindung wird blockiert.

Wie eben erläutert, lösen sich bei einem API VPC Endpoint für API Gateway mit aktiviertem Private DNS alle DNS-Lookups für execute-api.REGION.amazonaws.com auf private IPs auf — und Aufrufe öffentlicher APIs (über Custom Domain Names) scheitern an der SSL-Validierung. Die Lösung liegt in einer DNS-Priorisierung über Private Hosted Zones in Route 53 — auch bekannt als Split-Horizon- bzw. Split-View-DNS.

Die Idee dahinter: Bei einer Private Hosted Zone (PHZ) prüfen DNS-Lookups aus der VPC zuerst die PHZ, bevor sie andere öffentliche DNS-Server konsultieren.

Nehmen wir an, wir haben einen GoDaddy-DNS-Server, der unsere Domain auf der obersten Ebene hostet: mydomain.com.

Bilden wir api.mydomain.com auf unsere öffentliche API ab, hosten wir diese Subdomain in unserer PHZ-DNS, um Split-View-DNS umzusetzen.

So werden Lookups für api.mydomain.com, die aus unserer VPC stammen, von unserer PHZ beantwortet — während Aufrufe anderer Subdomains, die nicht über das API Gateway laufen (z. B. solche, die auf einen anderen Service zeigen, der nicht von einem VPC Endpoint abgefangen wird), das öffentliche DNS verwenden.

Diese Lösung basiert auf drei Kernkonzepten:

1. VPC Endpoint: für den Zugriff auf private APIs (Private DNS aktiviert)
2. Private Hosted Zone: für den Aufbau des Split-View-DNS
3. Ein Alias-Record vom Typ A in der PHZ: leitet den Traffic an den öffentlichen API Gateway Domain Name weiter

Voraussetzungen

• Ein öffentliches API Gateway mit einem außerhalb von Route 53 gehosteten Custom Domain Name, das aus dem Internet erreichbar ist — oder ein in Route 53 gehosteter Custom Domain Name, der jedoch über einen CNAME-Record statt eines Alias-A-Records darauf verweist.
• Ein API Gateway VPC Endpoint mit aktiviertem Private DNS, definiert in der VPC, aus der wir unsere öffentliche API aufrufen möchten.

Wenn Sie diesen VPC Endpoint bereits haben, beginnen Sie unten bei Schritt 2.

Ohne ihn lassen sich keine privaten APIs aufrufen.

1. VPC Endpoint für API Gateway konfigurieren, um auf private APIs zuzugreifen

Wenn Sie diesen Endpoint bereits haben, springen Sie zu Schritt "2".

• Navigieren Sie in der AWS-Konsole zur VPC-Konsole > Endpoints.
• Erstellen Sie einen Interface-Endpoint für com.amazonaws.REGION.execute-api.
• Aktivieren Sie Private DNS (Standardeinstellung).
• Hängen Sie eine Security Group an, die eingehenden HTTPS-Traffic (Port 443) aus der VPC zulässt (oder von den IPs der konkreten Ressourcen in Ihrer VPC, die private API-Gateway-APIs aufrufen können sollen).

2. Private Hosted Zone anlegen

• Erstellen Sie in der Route-53-Konsole eine PHZ, die zum API-Pfad Ihres öffentlichen Custom Domain Name passt (z. B. api.mydomain.com).

Hinweis: Wenn Sie in Ihrer öffentlichen Domain URLs aufrufen möchten, die nicht auf ein API Gateway abgebildet sind (wenn z. B. dev.mydomain.com auf einen Load Balancer und nicht auf das API Gateway zeigt), sollten Sie als Domain-Name Ihrer Private Hosted Zone den vollständigen Custom Domain Name Ihrer API verwenden (etwa api.mydomain.com).

Sind alle Subdomains Ihrer Domain auf API-Gateway-APIs abgebildet, verwenden Sie als Domain-Name die Top-Level-Domain mydomain.com.

• Verknüpfen Sie die Zone mit Ihrer VPC.

Erstellen Sie eine PHZ für Ihren Custom Domain Name und verknüpfen Sie sie mit der VPC, die Zugriff auf diese Domain benötigt

3. DNS-Records einrichten

• Sie müssen für jede von einer API genutzte Domain einen Alias-Record vom Typ A erstellen.

Wenn Sie z. B. api.mydomain.com und special-api.mydomain.com haben, müssen Sie für jede einen Record anlegen — einen für api und einen für special-api. Wählen Sie also als Record-Typ "A".

• Für den Record-Namen gilt:

- Stimmt der Name Ihres Custom Domain Name mit dem vollständigen Domain-Namen Ihrer API überein, geben Sie die Subdomain ("api") im Feld "Record Name" nicht ein (lassen Sie es leer). Beispiel: Wenn Sie die PHZ für api.mydomain.com erstellt haben, weil dies die einzige mit dem API Gateway verwendete Subdomain ist, lassen Sie das Feld "Record Name" leer.

- Verwenden Sie die Top-Level-Domain — mydomain.com —, weil mehrere Subdomains auf das API Gateway abgebildet sind, dann tragen Sie für jeden Record den Namen Ihrer API als "Record Name" ein. Also z. B. "api" für einen Record und "special-api" für einen anderen.

• Markieren Sie ihn als Alias-Record, indem Sie das Häkchen bei "alias" setzen
• Wählen Sie "Alias to API Gateway API"
• Wählen Sie die Region Ihrer API
• Wählen Sie den regionalen Endpoint (den für Ihren Custom Domain Name erstellten API Gateway Domain Name) Ihrer öffentlichen API.

Er hat einen Namen wie:

d-abc123.execute-api.REGION.amazonaws.com

• Falls er dort nicht erscheint, kopieren Sie ihn aus der API-Gateway-Konsole unter "Custom Domain Names" -> API Gateway Domain Name.
• Speichern Sie den Record

Es kann etwas dauern, bis Ihre neu angelegte Private Hosted Zone in Route 53 für Ihre VPC verfügbar ist.

Die Architektur dieser Lösung finden Sie in Anhang B.

Sie benötigen eine EC2-Instanz in Ihrer VPC mit Internetverbindung, um öffentliche APIs zu erreichen.

Verbinden Sie sich mit Ihrer EC2-Instanz, ersetzen Sie die untenstehende URL durch Ihre eigene und führen Sie aus:

curl -v https://your-public-api.yourdomain.com/your-path

Die Ausgabe sollte ungefähr so aussehen:

Beachten Sie: Vor dem Anlegen und Konfigurieren der PHZ lieferte das Private DNS (das mit dem API Gateway VPC Endpoint verknüpft ist) für den Custom Domain Name eine private IP zurück (es war 10.0.3.79) — diese private IP gehört zur ENI des VPC Endpoints. Mit einer PHZ für den Custom Domain Name erhalten wir nun die öffentlichen IPs des API Gateway Domain Name, die in diesem Beispiel lauten:

IPv4: 44.221.197.141, 34.192.177.183, 34.232.190.93

Um mit privaten und öffentlichen APIs zu arbeiten, deaktivieren Sie das Private DNS Ihres API Gateway VPC Endpoints. Erstellen Sie anschließend eine PHZ namens execute-api.REGION.amazonaws.com und verknüpfen Sie sie mit allen VPCs, denen Sie Zugriff auf die VPC mit Ihren privaten APIs gewähren möchten. (Hinweis: Eine Verknüpfung mit einer VPC in einer anderen Region bezieht sich auf den "Bonus"-Teil dieses Artikels.)

Sie legen einen Wildcard-Record an, der alle API-IDs des API Gateway abfängt — etwa so:

Erstellen Sie die Hosted Zone für private APIs in dieser Region

Anschließend erstellen Sie einen "Catch-all"-Record, der auf das DNS des VPC Endpoints zeigt — etwa so:

Erstellen Sie einen Catch-all-Record für alle privaten APIs in dieser Region

So wird sichergestellt, dass alle URLs eines in us-east-1 definierten privaten API Gateway von dieser PHZ abgefangen werden und die private IP-Adresse des API Gateway VPC Endpoints zurückliefern.

Für öffentliche APIs mit Custom Domain Name haben wir bereits gesehen, wie das Anlegen einer PHZ für diesen Custom Domain Name das Problem löst.

Für öffentliche APIs ohne Custom Domain Name müssen wir einen Alias-Record mit der API-ID der API hinzufügen, der auf die öffentliche URL verweist.

Beispiel: Nehmen wir an, wir haben in us-east-1 eine öffentliche API mit der URL bmf11pk5je.execute-api.us-east-1.amazonaws.com.

Rufen wir sie aus der VPC heraus auf, erhalten wir "Forbidden (403)" — wie oben für das Szenario mit Custom Domain Name beschrieben. Zur Lösung legen wir einen Record namens "bmf11pk5je" an und verweisen ihn auf die Invoke-URL — etwa so:

Nun können wir die in diesem Record hinterlegte öffentliche API aus der VPC heraus aufrufen. Für jede weitere öffentliche API in dieser Region, die wir aufrufen möchten, ist ein zusätzlicher Alias-Record erforderlich — wie für diese hier.

Eine private API in einer Region aus einer VPC in einer anderen AWS-Region aufrufen.

Das Problem

Private APIs lassen sich problemlos zwischen mehreren VPCs innerhalb derselben Region teilen. Sie benötigen lediglich API Gateway VPC Endpoints in jeder VPC, eine Resource Policy für Ihre Private API, die den Zugriff aus diesen VPCs erlaubt, und Sie müssen die VPC Endpoints zur Private API hinzufügen (über deren API Settings).

Das funktioniert nicht, wenn sich Ihre VPC in einer anderen Region befindet als die, in der die private API gehostet wird.

In diesem Fall sind folgende Schritte erforderlich:

1. Peeren Sie die beiden VPCs — die mit der privaten API und die, der Sie Zugriff gewähren möchten.

Für VPC Peering müssen Sie sicherstellen, dass sich die CIDR-Blöcke beider VPCs nicht überschneiden. 2. Falls Sie noch keine Private Hosted Zone für die API-Gateway-Region haben, in der Ihre private API liegt, müssen Sie eine anlegen. 3. Der Name der Private Hosted Zone (PHZ) sollte lauten:

execute-api.REGION.amazonaws.com 4. Diese PHZ müssen Sie sowohl mit dem API Gateway VPC Endpoint in der Region als auch mit der VPC verknüpfen, der Sie Zugriff gewähren möchten. 5. Fügen Sie der PHZ einen Alias-Record vom Typ A hinzu (markieren Sie ihn durch das Häkchen bei "alias" als Alias-Record) und wählen Sie dann im Dropdown "Alias to VPC Endpoint". 6. Wählen Sie die Region der VPC, der Sie Zugriff gewähren möchten. 7. Wählen Sie den VPC Endpoint für das API Gateway in dieser VPC. 8. Fügen Sie den CIDR-Block der gepeerten VPC zur Security Group des VPC Endpoints hinzu. Andernfalls wird die Kommunikation aus der gepeerten VPC blockiert. 9. Speichern Sie den Record.

Sobald Sie die obigen Schritte abgeschlossen haben, können Sie die private API aus der VPC in der anderen Region aufrufen.

Beachten Sie: Da Sie VPC Peering verwenden, muss die Resource Policy Ihres Private API Gateway den Traffic aus der gepeerten VPC nicht freigeben — sie muss lediglich den Traffic aus der Haupt-VPC zulassen, in der die API bereitgestellt ist. Das liegt daran, dass die Kommunikation zum API Gateway aus dem VPC Endpoint in dessen eigener VPC kommt, auch wenn sie ursprünglich aus der gepeerten VPC stammt.

Dieses regionsübergreifende Peering führt zu demselben SSL-Zertifikatsproblem, sobald Sie versuchen, eine in derselben VPC wie die private API definierte öffentliche API zu erreichen. Auch wenn sie sich in einer anderen Region befindet, ist sie nach wie vor mit einer PHZ für execute-api.REGION (REGION, in der die API bereitgestellt ist) verknüpft und versucht daher, die private IP des VPC Endpoints aufzurufen — es sei denn, es ist eine PHZ für Ihre öffentliche API definiert.

Möchten Sie sowohl private als auch öffentliche APIs aufrufen — ob regionsübergreifend oder nicht —, müssen Sie der Anleitung im ersten Teil dieses Artikels folgen.

Das folgende Diagramm zeigt, was passiert, wenn eine EC2-Instanz ein öffentliches API Gateway aufruft, während ein API Gateway VPC Endpoint mit aktiviertem Private DNS vorhanden ist.

Aufruf einer öffentlichen API aus einer VPC ohne PHZ

1. EC2 versucht, https://api.mydomain.com aufzurufen, daher wird ein DNS-Lookup ausgelöst
2. Die Antwort des DNS ist der API Gateway Domain Name
3. Der zweite DNS-Lookup wird ausgelöst und vom Private DNS abgefangen, das mit dem API Gateway VPC Endpoint verknüpft ist.
4. Es liefert die private IP-Adresse des VPC Endpoints zurück
5. EC2 versucht, die API über die private IP-Adresse aufzurufen
6. Der API-Gateway-Service, erreichbar über die private IP-Adresse, liefert ein Zertifikat, das für *.execute-api.REGION.amazonaws.com gültig ist — nicht aber für api.mydomain.com. Daher wird ein Zertifikatsfehler zurückgegeben

Das folgende Diagramm zeigt, was passiert, wenn eine EC2-Instanz ein öffentliches API Gateway aufruft, während ein API Gateway VPC Endpoint mit aktiviertem Private DNS vorhanden ist. Diesmal ist zusätzlich eine Private Hosted Zone für den Custom Domain Name definiert.

Aufruf öffentlicher APIs aus einer VPC mit PHZ

Aufruf der öffentlichen API aus dem Internet

1. Beim externen Domain-Hosting-Anbieter (z. B. GoDaddy) wird ein DNS-Lookup für den Custom Domain Name der API durchgeführt (z. B. api.mydomain.com)
2. Die Abfrage liefert den API Gateway Domain Name für diesen Custom Domain Name zurück
3. Der API Gateway Domain Name wird in AWS Route 53 abgefragt
4. Es wird eine öffentliche IP-Adresse für den öffentlichen API-Gateway-Service zurückgegeben
5. Über die öffentliche IP wird der API-Gateway-Service aufgerufen — und da er mit den Zertifikaten von api.mydomain.com verknüpft ist, terminiert er die SSL-Verbindung und ruft das passende Ziel der API-Gateway-Stage auf

Aufruf einer privaten API aus der VPC

6. Private APIs haben eine URL im Format apiID.execute-api.REGION.amazonaws.com. Wird eine solche URL aus einer VPC mit einem VPC Endpoint für API Gateway und aktiviertem Private DNS aufgerufen, übernimmt dieses Private DNS die Anfrage.

7. Das Private DNS liefert die private IP der ENI des API Gateway VPC Endpoints zurück.

8. Der über diese private IP erreichbare API-Gateway-Service hat ein Zertifikat für *.execute-api.REGION.amazonaws.com — der private API-Aufruf über diese URL wird also authentifiziert und an das Ziel der privaten API weitergeleitet.

Aufruf einer öffentlichen API-Gateway-API aus der VPC

9. Die für den Custom Domain Name erstellte Private Hosted Zone fängt Anfragen ab, die unter ihren Domain-Namen fallen, und verarbeitet diese.

10. Die PHZ liefert dank ihres Alias-A-Records die öffentliche IP des mit dem Custom Domain Name verknüpften API Gateway Domain Name zurück.

11. Die öffentliche IP wird über das Internet Gateway aufgerufen und erreicht so die Adresse des API-Gateway-Service. Da der über die öffentliche IP erreichbare Service die Zertifikatszuordnung zwischen dem Custom Domain Name und dem API-Domain-Namen besitzt, gelingt der SSL-Handshake, und die TLS-Verbindung wird terminiert. Die Anfrage wird an das Ziel der entsprechenden Stage der öffentlichen API-Gateway-API weitergeleitet.

Ich hoffe, dieser Artikel hat Ihnen wertvolle Erkenntnisse geliefert. Wenn Sie mehr erfahren möchten oder Interesse an unseren Services haben, sprechen Sie uns gerne an. Sie erreichen uns hier.

• API Gateway Custom Domain Names
• API endpoint types for REST APIs in API Gateway
• Working with private hosted zones
• AWS Route 53 Split View DNS
• Choosing between alias and non-alias records

Enthält eine gute Erklärung zu Alias-Records in Route 53