Erstellen einer Canary-Release-Bereitstellung
Sie erstellen eine Canary-Release-Bereitstellung bei der Bereitstellung der API mit Canary-Einstellungen als zusätzliche Eingabe für die Bereitstellungserstellung.
Sie können auch aus einer bestehenden Nicht-Canary-Bereitstellung eine Canary-Release-Bereitstellung erstellen, indem Sie eine stage:update-Anforderung erstellen, um die Canary-Einstellungen für die Stufe hinzuzufügen.
Beim Erstellen einer nicht-Canary-Release-Bereitstellung können Sie einen nicht existierenden Stufennamen angeben. API Gateway erstellt eine Stufe, wenn die angegebene Stufe nicht existiert. Sie können jedoch beim Anlegen einer Canary-Release-Bereitstellung keinen nicht existierenden Stufennamen angeben. Sie erhalten eine Fehlermeldung und API Gateway erstellt keine Canary-Release-Bereitstellung.
Sie können eine Canary-Release-Bereitstellung in API Gateway mit der API-Gateway-Konsole, der AWS CLI oder einem AWS SDK erstellen.
Themen
Erstellen einer Canary-Bereitstellung mithilfe der API Gateway-Konsole
Gehen Sie nach den Anweisungen unten vor, um eine Canary-Release-Bereitstellung mit der API Gateway-Konsole zu erstellen:
So erstellen Sie eine erste Canary-Release-Bereitstellung
-
Melden Sie sich bei der API Gateway-Konsole an.
-
Erstellen Sie eine neue API oder wählen Sie eine vorhandene API aus.
-
Ändern Sie ggf. die API oder richten Sie die gewünschten API-Methoden und -Integrationen ein.
-
Wählen Sie Deploy API im Dropdown-Menü Aktionen. Befolgen Sie die Anweisungen auf der Seite in Deploy API, um die API in einer neuen Stufe bereitzustellen.
Bislang haben Sie die API in einer Produktions-Release-Stufe bereitgestellt. Als Nächstes konfigurieren Sie Canary-Einstellungen für die Stufe und, falls erforderlich, auch das Caching. Sie legen Stufenvariablen fest oder konfigurieren die API-Ausführung oder die Zugriffsprotokolle.
-
Um das API-Caching zu aktivieren, wählen Sie im Stage Editor die Registerkarte Settings und folgen Sie den Anweisungen auf der Seite. Weitere Informationen finden Sie unter Aktivieren von API-Caching für verbesserte Reaktionsfähigkeit.
-
Um Stufenvariablen festzulegen, wählen Sie die Registerkarte Stage Variable im Stage Editor aus und folgen Sie den Anweisungen auf der Seite, um Stufenvariablen hinzuzufügen oder zu ändern. Weitere Informationen finden Sie unter Einrichten von Stufenvariablen für eine REST-API-Bereitstellung.
-
Um die Ausführung zu konfigurieren oder auf die Protokollierung zuzugreifen, wählen Sie die Registerkarte Logs im Stage Editor und folgen Sie den Anweisungen auf der Seite. Weitere Informationen finden Sie unter Einrichten der CloudWatch-Protokollierung für eine REST-API in API Gateway.
-
Wählen Sie im Stage Editor die Registerkarte Canary und wählen Sie dann Create Canary aus.
-
Wählen Sie im Abschnitt Stage's Request Distribution das Bleistift-Symbol neben Percentage of requests to Canary aus und geben Sie eine Zahl (z. B.
5.0) in das Eingabefeld ein. Klicken Sie auf das Häkchen-Symbol, um die Einstellung zu speichern. -
Um eine AWS WAF-Web-ACL mit der Stufe zu verknüpfen, wählen Sie aus der Dropdown-Liste Web ACL (Web-ACL) eine Web-ACL aus.
Anmerkung Falls erforderlich, klicken Sie auf Web-ACL erstellen, um die AWS WAF-Konsole in einer neuen Browser-Registerkarte zu öffnen, erstellen Sie die Web-ACL und kehren Sie zur API-Gateway-Konsole zurück, um die Web-ACL mit der Stufe zu verknüpfen.
-
Falls gewünscht, wählen Sie Block API Request if WebACL cannot be evaluated (Fail- Close) (API-Anforderung blockieren, wenn WebACL nicht ausgewertet werden kann (Fehler – Schließen)).
-
Wenn nötig, wählen Sie Add Stage Variables aus, um sie unter dem Abschnitt Canary Stage Variables hinzuzufügen, um vorhandene Stufenvariablen zu überschreiben oder neue Stufenvariablen für das Canary-Release hinzuzufügen.
-
Wenn gewünscht, wählen Sie Enable use of stage cache aus, um das Caching für das Canary-Release zu aktivieren, und speichern Sie Ihre Auswahl. Der Cache steht für das Canary-Release erst dann zur Verfügung, wenn das API-Caching aktiviert ist.
Nachdem das Canary-Release in der Bereitstellungsstufe initialisiert wurde, ändern Sie die API und testen die Änderungen. Sie können die API in derselben Stufe erneut bereitstellen, sodass sowohl die aktualisierte Version als auch die Basisversion über dieselbe Stufe zugreifbar sind. In den folgenden Schritten wird beschrieben, wie Sie dies tun.
So stellen Sie die neueste API-Version für ein Canary bereit
-
Wählen Sie bei jeder Aktualisierung der API im Dropdown-Menü Actions neben der Liste Resources die Option Deploy API aus.
-
Wählen Sie in Deploy API in der Dropdown-Liste Deployment stage die Canary-Stufe aus.
-
Geben Sie optional eine Beschreibung in die Deployment description ein.
-
Wählen Sie Deploy, um die neueste API-Version auf das Canary-Release zu übertragen.
-
Falls erwünscht, rekonfigurieren Sie die Stufeneinstellungen, Protokolle oder Canary-Einstellungen, wie in beschriebe So erstellen Sie eine erste Canary-Release-Bereitstellung.
Dadurch verweist das Canary-Release auf die neueste Version, während das Produktionsrelease noch auf die erste Version der API verweist. canarySettings hat jetzt einen neuen deploymentId-Wert, während die Stufe noch den ursprünglichen deploymentId-Wert aufweist. Hinter den Kulissen ruft die Konsole stage:update auf.
Erstellen einer Canary-Release-Bereitstellung mit der AWS CLI
Erstellen Sie zunächst eine Basisbereitstellung mit zwei Stufenvariablen, jedoch ohne Canary:
aws apigateway create-deployment --variables sv0=val0,sv1=val1 --rest-api-id 4wk1k4onj3 --stage-name prod
Der Befehl gibt eine Darstellung der resultierenden Deployment zurück, ähnlich der folgenden:
{ "id": "du4ot1", "createdDate": 1511379050 }
Die resultierende Bereitstellungs-id identifiziert einen Snapshot (oder eine Version) der API.
Erstellen Sie jetzt eine Canary-Bereitstellung in der prod-Stufe:
aws apigateway create-deployment --canary-settings '{ \ "percentTraffic":10.5, \ "useStageCache":false, \ "stageVariableOverrides":{ \ "sv1":"val2", \ "sv2":"val3" \ } \ }' \ --rest-api-id 4wk1k4onj3 \ --stage-name prod
Wenn die angegebene Stufe (prod) nicht existiert, gibt der vorhergehende Befehl einen Fehler zurück. Andernfalls wird die neu erstellte deployment-Ressourcenrepräsentation ähnlich der folgenden zurückgegeben:
{ "id": "a6rox0", "createdDate": 1511379433 }
Die resultierende Bereitstellungs-id identifiziert die Testversion der API für das Canary-Release. Dadurch ist die zugehörige Stufe für Canary aktiviert. Sie können sich diese Stufenrepräsentation ansehen, indem Sie den Befehl get-stage aufrufen, ähnlich wie im Folgenden beschrieben:
aws apigateway get-stage --rest-api-id 4wk1k4onj3 --stage-name prod
Nachfolgend ist eine Repräsentation der Stage als Ausgabe des Befehls zu sehen:
{ "stageName": "prod", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "du4ot1", "lastUpdatedDate": 1511379433, "createdDate": 1511379050, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "a6rox0", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} }
In diesem Beispiel verwendet die Basisversion der API die Stufenvariablen {"sv0":val0", "sv1":val1"}, während die Testversion die Stufenvariablen {"sv1":val2", "sv2":val3"} verwendet. Sowohl das Produktionsrelease als auch das Canary-Release verwenden die gleiche Stufenvariable sv1, jedoch mit unterschiedlichen Werten (val1 und val2). Die Stufenvariable sv0 wird ausschließlich im Produktionsrelease verwendet und die Stufenvariable sv2 wird nur im Canary-Release verwendet.
Sie können aus einer bestehenden, regulären Bereitstellung eine Canary-Release-Bereitstellung erstellen, indem Sie die Stufe aktualisieren, um Canary zu aktivieren. Um dies zu demonstrieren, erstellen Sie zunächst eine reguläre Bereitstellung:
aws apigateway create-deployment \ --variables sv0=val0,sv1=val1 \ --rest-api-id 4wk1k4onj3 \ --stage-name beta
Der Befehl gibt eine Repräsentation der Basisversionsbereitstellung zurück:
{ "id": "cifeiw", "createdDate": 1511380879 }
Die dazugehörige Beta-Stufe hat keine Canary-Einstellungen:
{ "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511380879, "createdDate": 1511380879, "methodSettings": {} }
Erstellen Sie jetzt eine neue Canary-Release-Bereitstellung, indem Sie ein Canary zur Stufe hinzufügen:
aws apigateway update-stage \ --patch-operations '[{ \ "op":"replace", \ "path":"/canarySettings/percentTraffic", \ "value":"10.5" \ },{ \ "op":"replace", \ "path":"/canarySettings/useStageCache", \ "value":"false" \ },{ \ "op":"replace", \ "path":"/canarySettings/stageVariableOverrides/sv1", \ "value":"val2" \ },{ \ "op":"replace", \ "path":"/canarySettings/stageVariableOverrides/sv2", \ "value":"val3" \ }]' \ --rest-api-id 4wk1k4onj3 \ --stage-name beta
Eine Repräsentation der aktualisierten Stufe sieht so aus:
{ "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511381930, "createdDate": 1511380879, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "cifeiw", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} }
Da wir gerade ein Canary für eine existierende Version der API aktiviert haben, zeigen sowohl das Produktions-Release (Stage) als auch das Canary-Release (canarySettings) auf die gleiche Bereitstellung – d. h. die gleiche Version (deploymentId) der API. Nachdem Sie die API geändert und für diese Stufe wieder bereitgestellt haben, ist die neue Version im Canary-Release. Die Basisversion verbleibt im Produktions-Release. Dies wirkt sich auf die Stufenentwicklung aus, wenn die deploymentId im Canary-Release auf die neue Bereitstellungs-id aktualisiert wird und die deploymentId im Produktions-Release unverändert bleibt.
