创建 Canary 版本部署 - Amazon API Gateway
使用 API Gateway 控制台创建 Canary 版本部署使用 AWS CLI 创建 Canary 版本部署

创建 Canary 版本部署

在部署具有 Canary 设置的 API 作为对部署创建操作的额外输入时，您可以创建 Canary 版本部署。

您还可以通过发出 stage:update 请求在阶段上添加 Canary 版本设置，从现有非 Canary 版本部署创建 Canary 版本。

创建非 Canary 版本部署时，您可以指定非现有阶段名称。如果指定的阶段不存在，API Gateway 将创建一个。但是，在创建 Canary 版本部署时，您无法指定任何非现有阶段名称。您会收到错误，并且 API Gateway 不创建任何 Canary 版本部署。

您可以使用 API Gateway 控制台、AWS CLI 或AWS开发工具包在 API Gateway 中创建 Canary 版本部署。

使用 API Gateway 控制台创建 Canary 版本部署

要使用 API Gateway 控制台创建 Canary 版本部署，请按照以下说明操作：

创建初始 Canary 版本部署

  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 中针对 REST API 的缓存设置或使用 API Gateway 控制台将 AWS WAF Web ACL 与 API Gateway API 阶段相关联。

  5. 要配置执行或访问日志记录，请在日志和跟踪部分中选择编辑，并按照屏幕上的说明操作。有关更多信息，请参阅 为 API Gateway 中的 REST API 设置 CloudWatch 日志记录。

  6. 要设置阶段变量，请选择阶段变量选项卡，并按照屏幕上的说明添加或修改阶段变量。有关更多信息，请参阅 在 API Gateway 中对 REST API 使用阶段变量。

  7. 选择金丝雀选项卡，然后选择创建金丝雀。您可能需要选择右箭头按钮以显示金丝雀选项卡。

  8. 在金丝雀设置下，对于金丝雀，输入要转移到金丝雀的请求的百分比。

  9. 如果需要，请选择阶段缓存以便为金丝雀版本开启缓存。除非启用 API 缓存，否则缓存对 Canary 版本不可用。

  10. 要覆盖现有的阶段变量，对于金丝雀覆盖，请输入新的阶段变量值。

在部署阶段上初始化 Canary 版本之后，您更改了 API 并希望测试更改。您可以将 API 重新部署到相同阶段，这样可以通过同一个阶段访问更新后的版本和基础版本。以下步骤说明了如何完成此操作。

将最新 API 版本部署到 Canary

  1. 每次更新 API 时，请选择部署 API。

  2. 在部署 API 中，从部署阶段下拉列表中选择包含金丝雀的阶段。

  3. （可选）为部署描述输入描述。

  4. 选择 Deploy (部署) 将最新 API 版本推送到 Canary 版本。

  5. 如果需要，可重新配置阶段设置、日志或 Canary 设置，如创建初始 Canary 版本部署中所述。

此时，Canary 版本指向最新版本，而生产版本仍指向 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 版本的 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 版本均使用相同的阶段变量 sv1，但分别具有不同值 val1 和 val2。阶段变量 sv0 仅用于生产版本中，阶段变量 sv2 仅用于 Canary 版本中。

您可通过更新阶段来启用 Canary，从现有常规部署创建 Canary 版本部署。为了演示此操作，首先创建一个常规部署：

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

该命令返回基础版本部署的表示：

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

关联的测试版阶段没有任何 Canary 设置：

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

现在，通过在阶段上连接 Canary 创建新的 Canary 版本部署：

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 版本 (canarySettings) 指向相同的部署，即 API 的相同版本 (deploymentId)。在您更改 API 并将其再次部署到此阶段之后，新版本将为 Canary 版本，而基础版本保持为生产版本。在阶段演变中，Canary 的 deploymentId 更新为新部署 id，而生产版本的 deploymentId 保持不变，证明了这一点。