Erstellen einer Canary-Bereitstellung mithilfe der API Gateway-Konsole Erstellen einer Canary-Release-Bereitstellung mit der AWS CLI

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
Erstellen einer Canary-Release-Bereitstellung mit der AWS CLI

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:

Old REST API console

Anmerkung

Wir haben die API-Gateway-Konsole neu gestaltet. Die alte Konsolenerfahrung wird ab Dezember 2023 nicht mehr verfügbar sein.

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.

New REST API console

So erstellen Sie eine erste Canary-Release-Bereitstellung

Melden Sie sich bei der API Gateway-Konsole an.
Wählen Sie eine vorhandene REST API aus oder erstellen Sie eine neue REST API.
Klicken Sie im Hauptnavigationsbereich von auf Resources (Ressourcen) und auf Deploy API (API bereitstellen). 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 oder der Stufe eine AWS WAF Web-ACL zuzuordnen, wählen Sie im Abschnitt Stage details (Stufendetails) die Option Edit (Bearbeiten) aus. Weitere Informationen finden Sie unter Aktivieren von API-Caching für verbesserte Reaktionsfähigkeit oder So verknüpfen Sie eine regionale AWS WAF-Web-ACL mit einer API-Gateway-API-Stufe über die API-Gateway-Konsole:.
Um die Ausführung zu konfigurieren oder auf die Protokollierung zuzugreifen, wählen Sie im Abschnitt Logs and tracing (Protokolle und Nachverfolgung) die Option Edit (Bearbeiten) und folgen Sie den Anweisungen am Bildschirm. Weitere Informationen finden Sie unter Einrichten der CloudWatch-Protokollierung für eine REST-API in API Gateway.
Um Stufenvariablen festzulegen, wählen Sie die Registerkarte Stage variables (Stufenvariablen) und folgen Sie den Anweisungen am Bildschirm, um Stufenvariablen hinzuzufügen oder zu ändern. Weitere Informationen finden Sie unter Einrichten von Stufenvariablen für eine REST-API-Bereitstellung.
Wählen Sie die Registerkarte Canary und dann Create canary (Canary erstellen) aus. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte Canary anzuzeigen.
Geben Sie unter Canary settings (Canary-Einstellungen) für Canary den Prozentsatz der Anfragen ein, die an den Canary weitergeleitet werden sollen.
Wählen Sie bei Bedarf Stage Cache (Stufen-Cache) aus, um das Caching für die Canary-Version zu aktivieren. Der Cache steht für das Canary-Release erst dann zur Verfügung, wenn das API-Caching aktiviert ist.
Um bestehende Stufenvariablen zu überschreiben, geben Sie für Canary Override (Überschreibung des Canary) einen neuen Wert für die Stufenvariable ein.

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.

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.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Einrichten einer Canary-Release-Bereitstellung

Aktualisieren eines Canary-Releases

Erstellen einer Canary-Release-Bereitstellung

Themen

Erstellen einer Canary-Bereitstellung mithilfe der API Gateway-Konsole

Anmerkung

So erstellen Sie eine erste Canary-Release-Bereitstellung

Anmerkung

So erstellen Sie eine erste Canary-Release-Bereitstellung

Anmerkung

So stellen Sie die neueste API-Version für ein Canary bereit

So stellen Sie die neueste API-Version für ein Canary bereit

Erstellen einer Canary-Release-Bereitstellung mit der AWS CLI