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

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.

Tópicos

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

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:

Para criar a implantação da versão canary inicial

Inicie uma sessão no console do API Gateway.
Selecione uma API REST existente ou crie uma API REST.
No painel de navegação principal, selecione Recursos e, depois, Implantar API. Siga as instruções na tela em Deploy API para implantar a API em um novo estágio.

Até agora, você implantou a API em um estágio da versão de produção. Em seguida, configure as configurações do canary no estágio e, se necessário, também ative o armazenamento em cache, defina variáveis de estágio ou configure a execução da API ou registros de acesso.
Para habilitar o armazenamento em cache da API ou associar uma ACL da web do AWS WAF ao estágio, na seção Detalhes do estágio, escolha Editar. Para obter mais informações, consulte Configurações de cache para APIs REST no API Gateway ou Associar uma ACL da web do AWS WAF a um estágio da API do API Gateway usando o console do API Gateway.
Para configurar a execução ou o registro em log do acesso, na guia Logs e rastreamento, selecione Editar e siga as instruções na tela. Para ter mais informações, consulte Configurar o registro em log do CloudWatch para APIs REST no API Gateway.
Para definir variáveis de estágio, escolha a guia Variáveis de estágio e siga as instruções na tela para adicionar ou modificar as variáveis de estágio. Para ter mais informações, consulte Configurar variáveis de estágio para a implantação de uma API REST.
Escolha a guia Canário e selecione Criar canário. Talvez seja necessário escolher o botão de seta para a direita para mostrar a guia Canário.
Em Configurações de canário, em Canário, insira a porcentagem de solicitações a serem desviadas para o canário.
Se desejar, selecione Cache de estágio para ativar o armazenamento em cache da versão de canário. O cache não estará disponível para a versão canary até o armazenamento em cache da API ser ativado.
Para substituir variáveis de estágio existentes, em Substituição do canário, insira um novo valor de variável de estágio.

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:

Para implantar a última versão da API em um canary

Com cada atualização da API, selecione Implantar API.
Em Implantar API, escolha o estágio que contém um canário na lista suspensa Estágio de implantação.
(Opcional) Insira uma descrição em Descrição da implantação.
Escolha Deploy para enviar a última versão da API para a versão canary.
Se desejar, reconfigure as configurações do estágio, registros ou as configurações do canary, conforme descrito em Para criar a implantação da versão canary inicial.

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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Definir uma implantação da versão canary

Atualizar uma versão canary