建立 Canary Release 部署 - Amazon API Gateway
使用 API Gateway 主控台建立 Canary 部署使用 建立 Canary 部署 AWS CLI

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

建立 Canary Release 部署

當您API使用 Canary 設定部署 作為部署建立操作的額外輸入時，您可以建立 Canary 版本部署。

您也可以提出在階段上新增 Canary 設定的 stage:update 請求，以從現有非 Canary 部署建立 Canary Release 部署。

建立非 Canary Release 部署時，您可以指定非現有階段名稱。API 如果指定的階段不存在，閘道會建立一個。不過，建立 Canary Release 部署時，您無法指定任何非現有階段名稱。您會收到錯誤，APIGateway 不會建立任何 Canary Release 部署。

您可以使用 API Gateway 主控台、 AWS CLI或 ，在 API Gateway 中建立 Canary Release 部署 AWS SDK。

使用 API Gateway 主控台建立 Canary 部署

若要使用 API Gateway 主控台建立 Canary 版本部署，請遵循下列指示：

建立初始 Canary Release 部署

  1. 登入API閘道主控台。

  2. 選擇現有的 RESTAPI或建立新的 REST API。

  3. 在主導覽窗格中，選擇資源 ，然後選擇部署 API。遵循 部署API中的螢幕指示，將 部署API到新的階段。

    到目前為止，您已將 部署API到生產版本階段。接下來，您可以在階段上設定 Canary 設定，並視需要啟用快取、設定階段變數或設定API執行或存取日誌。

  4. 若要啟用快取或建立 AWS WAF Web API ACL與階段的關聯，請在階段詳細資訊區段中，選擇編輯 。如需詳細資訊，請參閱 API Gateway RESTAPIs中的 的快取設定 或 使用 API Gateway 主控台將 AWS WAF 網頁 ACL 與 API Gateway API 階段建立關聯。

  5. 若要設定執行或存取記錄，請在日誌和追蹤區段中選擇編輯，並依照畫面上的指示進行。如需詳細資訊，請參閱在 API Gateway RESTAPIs中設定 CloudWatch 的記錄。

  6. 若要設定階段變數，請選擇階段變數索引標籤，並依照畫面上的指示新增或修改階段變數。如需詳細資訊，請參閱RESTAPI在API閘道中使用階段變數。

  7. 選擇 Canary 索引標籤，然後選擇建立 Canary。您可能需要選擇向右箭頭按鈕才能顯示 Canary 索引標籤。

  8. 在 Canary 設定下，針對 Canary 輸入要轉移至 Canary 的請求百分比。

  9. 如有需要，請選取階段快取以開啟 Canary 版本的快取功能。在啟用快取之前， Canary API 版本無法使用快取。

  10. 若要覆寫現有的階段變數，請針對 Canary 覆寫輸入新的階段變數值。

在部署階段初始化 Canary Release 之後，您會變更 API並想要測試變更。您可以將 重新部署API到相同的階段，以便透過相同的階段存取更新版本和基礎版本。下列步驟說明如何執行這項操作。

將API最新版本部署到 Canary

  1. 每次更新 時API，選擇部署 API。

  2. 在部署 API中，從部署階段下拉式清單中選擇包含 Canary 的階段。

  3. (選用) 在部署描述中輸入描述。

  4. 選擇部署，將API最新版本推送至 Canary 版本。

  5. 如有需要，請重新設定階段設定、日誌或 Canary 設定，如「建立初始 Canary Release 部署」中所述。

因此， Canary Release 會指向最新版本，而生產版本仍會指向 的初始版本API。canarySettings 現在 具有新的deploymentId值，而階段仍然具有初始deploymentId值。在幕後，主控台會呼叫 stage:update。

使用 建立 Canary 部署 AWS CLI

先建立具有兩個階段變數的基準部署，但不需要任何 Canary：

aws apigateway create-deployment \
    --variables sv0=val0,sv1=val1 \
    --rest-api-id abcd1234 \
    --stage-name 'prod' \

此命令會傳回所產生 Deployment 的呈現，與下列類似：

{
    "id": "du4ot1", 
    "createdDate": 1511379050
}

產生的部署會id識別 的快照 （或版本）API。

現在在 prod 階段上建立 Canary 部署：

aws apigateway create-deployment  --rest-api-id abcd1234 \
    --canary-settings \ 
    '{
        "percentTraffic":10.5,
        "useStageCache":false,
        "stageVariableOverrides":{
            "sv1":"val2", 
            "sv2":"val3"
        } 
    }' \
    --stage-name 'prod'

如果指定的階段 (prod) 不存在，上述命令會傳回錯誤。否則，它會傳回新建的部署資源呈現，與下列類似：

{
    "id": "a6rox0", 
    "createdDate": 1511379433
}

產生的部署會id識別 API Canary 版本的 測試版本。因此，相關聯的階段是已啟用 Canary。您可以呼叫 get-stage 命令來檢視此階段呈現，與下列類似：

aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod

以下顯示 Stage 作為命令輸出的呈現：

{
    "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": {}
}

在此範例中， 的基本版本API會使用 的階段變數{"sv0":val0", "sv1":val1"}，而測試版本會使用 的階段變數{"sv1":val2", "sv2":val3"}。生產版本和 Canary Release 使用相同的階段變數 sv1，但分別具有不同的值 val1 和 val2。階段變數 sv0 單獨用於生產版本，而階段變數 sv2 用於 Canary Release 中。

您可以更新階段以啟用 Canary，以從現有一般部署建立 Canary Release 部署。為了示範這項操作，請先建立一般部署：

aws apigateway create-deployment \
    --variables sv0=val0,sv1=val1 \  
    --rest-api-id abcd1234 \
    --stage-name 'beta'

此命令會傳回基本版本部署呈現：

{
    "id": "cifeiw", 
    "createdDate": 1511380879
}

相關聯的 Beta 階段沒有任何 Canary 設定：

{
    "stageName": "beta", 
    "variables": {
        "sv0": "val0", 
        "sv1": "val1"
    }, 
    "cacheClusterEnabled": false, 
    "cacheClusterStatus": "NOT_AVAILABLE", 
    "deploymentId": "cifeiw", 
    "lastUpdatedDate": 1511380879, 
    "createdDate": 1511380879, 
    "methodSettings": {}
}

現在，在階段上連接 Canary，以建立新的 Canary Release 部署：

aws apigateway update-stage \
    --rest-api-id abcd1234 \
    --stage-name 'beta' \
    --patch-operations '[{
            "op": "replace",
            "value": "0.0",
            "path": "/canarySettings/percentTraffic"
        }, {
            "op": "copy",
            "from": "/canarySettings/stageVariableOverrides",
            "path": "/variables"
        }, {
            "op": "copy",
            "from": "/canarySettings/deploymentId",
            "path": "/deploymentId"
        }]'

更新過的階段呈現如下：

{
    "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": {}
}

由於我們剛在 的現有版本上啟用 CanaryAPI，生產版本 （Stage） 和 Canary 版本 （canarySettings） 都指向相同的部署，即 的相同版本 （deploymentId）API。在您變更 API並再次將其部署到此階段之後，新版本將位於 Canary 版本中，而基礎版本將保留在生產版本中。Canary Release 中的 deploymentId 更新為新部署 id 而生產版本中的 deploymentId 保持不變時，這是在階段發展中體現。