Criar uma implantação da versão canary

Crie uma implantação da versão canary ao implantar a API com configurações do canary como uma entrada adicional para a operação de criação de implantação.

Você também pode criar uma implantação da versão canary a partir de uma implantação não canary existente fazendo uma solicitação stage:update para adicionar as configurações do canary no estágio.

Ao criar uma implantação da versão não canary, você pode especificar um nome de estágio não existente. O API Gateway criará um se o estágio especificado não existir. No entanto, você não pode especificar um nome de estágio não existente ao criar uma implantação da versão canary. Você receberá um erro e o API Gateway não criará qualquer implantação da versão canary.

Você pode criar uma implantação do lançamento canary no API Gateway usando o console do API Gateway, a CLI AWS CLI ou um SDK da AWS.

Criar uma implantação canary usando o console do API Gateway

Para usar o console do API Gateway para criar uma implantação da versão canary, siga as instruções abaixo:

Depois que a versão canary for inicializada no estágio de implantação, altere a API e teste as alterações. Reimplante a API no mesmo estágio para que a versão atualizada e a versão base possam ser acessadas através do mesmo estágio. As etapas a seguir descrevem como fazer isso:

Como resultado, a versão canary aponta para a versão mais recente enquanto a versão de produção ainda aponta para a versão inicial da API. As canarySettings agora têm um novo valor deploymentId, enquanto o estágio ainda mantém o valor inicial deploymentId. Enquanto isso, o console chama stage:update.

Criar uma implantação do canary usando a AWS CLI

Primeiro, crie uma implantação de linha de base com duas variáveis de estágio, mas sem qualquer canary:

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

O comando retorna uma representação do Deployment resultante, similar ao seguinte:

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

O id da implantação resultante identifica um snapshot (ou versão) da API.

Agora, crie uma implantação do canary no estágio prod:

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

Se o estágio especificado (prod) não existir, o comando anterior retornará um erro. Caso contrário, ele retornará a representação recém-criada do recurso deployment, semelhante à seguinte:

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

O id de implantação resultante identifica a versão de teste da API para a versão canary. Como resultado, o estágio associado é ativado para canary. Você pode visualizar esta representação do estágio chamando o comando get-stage, similar ao seguinte:

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

A seguir está uma representação do Stage como resultado de um comando:

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

Neste exemplo, a versão base da API usará as variáveis de estágio do {"sv0":val0", "sv1":val1"}, enquanto a versão de teste usa as variáveis de estágio do {"sv1":val2", "sv2":val3"}. A versão de produção e a versão canary usam a mesma variável de estágio do sv1, mas com valores diferentes, val1 e val2, respectivamente. A variável de estágio do sv0 é usada somente na versão de produção e a variável de estágio do sv2 é usada somente na versão canary.

Você pode criar uma implantação da versão canary a partir de uma implantação normal, atualizando o estágio para ativar um canary. Para demonstrar isso, crie uma implantação normal primeiro:

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

O comando retorna uma representação de implantação da versão base:

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

O estágio beta associado não possui configurações do canary:

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

Agora, crie uma nova implantação da versão canary anexando um canary ao estágio:

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"
        }]'

Uma representação de um estágio atualizado é semelhante ao seguinte:

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

Como acabamos de ativar um canary em uma versão existente da API, a versão de produção (Stage) e a versão canary (canarySettings) apontam para a mesma implantação, ou seja, a mesma versão (deploymentId) da API. Depois de alterar a API e implantá-la nesse estágio novamente, a nova versão ficará na versão canary, enquanto a versão base permanecerá na versão de produção. Isso se manifesta na evolução do estágio quando o deploymentId na versão canary é atualizado para a nova implantação do id e o deploymentId na versão de produção permanece inalterado.