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

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

建立 Canary Release 部署

部署將 Canary 設定做為部署建立操作額外輸入的 API 時，請建立 Canary Release 部署。

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

建立非 Canary Release 部署時，您可以指定非現有階段名稱。如果指定的階段不存在，則 API Gateway 會建立階段。不過，建立 Canary Release 部署時，您無法指定任何非現有階段名稱。您將會收到錯誤，而且 API Gateway 不會建立 Canary Release 部署。

您可以使用 API Gateway 主控台、AWS CLI 或 AWS 軟體開發套件，在 API Gateway 中建立 Canary 版本部署。

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

若要使用 API Gateway 主控台來建立 Canary Release 部署，請遵循下面的說明：

建立初始 Canary Release 部署

  1. 登入 API Gateway 主控台。

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

  3. 在主導覽窗格中，選擇資源，然後選擇部署 API。請遵循 Deploy API (部署 API) 中的畫面說明，將 API 部署至新階段。

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

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

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

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

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

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

  9. 如有需要，請選取階段快取以開啟 Canary 版本的快取功能。除非啟用 API 快取，否則快取不適用於 Canary Release。

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

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

將最新的 API 版本部署至 Canary

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

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

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

  4. 選擇 Deploy (部署)，將最新的 API 版本推送至 Canary Release。

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

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

使用 AWS CLI 建立 Canary 部署

先建立具有兩個階段變數的基準部署，但不需要任何 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 識別 Canary Release 的 API 測試版本。因此，相關聯的階段是已啟用 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": {}
}

因為我們只會在現有 API 版本上啟用 Canary，所以生產版本 (Stage) 和 Canary Release (canarySettings) 指向相同的部署，即 API 的相同版本 (deploymentId)。在您變更 API 並將它再次部署至此階段之後，新的版本將會在 Canary Release 中，而基本版本仍然在生產版本中。Canary Release 中的 deploymentId 更新為新部署 id 而生產版本中的 deploymentId 保持不變時，這是在階段發展中體現。