Configurar uma implantação de versão canary do API Gateway

A versão canary é uma estratégia de desenvolvimento de software em que uma nova versão de uma API (e outros softwares) é implantada para fins de teste, e a versão base permanece implantada como uma versão de produção para operações normais no mesmo estágio. Para fins de discussão, nós nos referimos à versão base como uma versão de produção nesta documentação. Embora isso seja razoável, você pode aplicar a versão canary a qualquer versão de não produção para testes.

Em uma implantação da versão canary, o tráfego total da API é separado aleatoriamente em uma versão de produção e uma versão canary com uma proporção pré-configurada. Geralmente, a versão canary recebe uma pequena porcentagem do tráfego da API e a versão de produção obtém o resto. Os recursos de API atualizados são visíveis para o tráfego da API apenas por meio do canary. Você pode ajustar a porcentagem do tráfego do canary para otimizar a cobertura ou a performance do teste.

Ao manter o tráfego canary pequeno e a seleção aleatória, a maioria dos usuários não é afetada negativamente a qualquer momento por potenciais erros na nova versão, e nenhum usuário único é afetado negativamente o tempo todo.

Depois que as métricas de teste aprovarem seus requisitos, você poderá promover a versão canary para a versão de produção e desativar o canary da implantação. Isso disponibiliza os novos recursos na etapa de produção.

Implantação da versão canary no API Gateway

No API Gateway, uma implantação da versão canary usa o estágio de implantação para a versão de produção da versão base de uma API e atribui ao estágio uma versão canary para as novas versões, em relação à versão base, da API. O estágio é associado à implantação inicial e o canary às implantações subsequentes. No início, tanto o estágio quanto o canary apontam para a mesma versão da API. Utilizamos estágio e versão de produção como sinônimos e usamos canary e versão canary também como sinônimos nesta seção.

Para implantar uma API com uma versão canary, crie uma implantação da versão canary adicionando configurações do canary ao estágio de uma implantação normal. As configurações do canary descrevem a versão canary subjacente e o estágio representa a versão de produção da API nesta implantação. Para adicionar as configurações do canary, defina canarySettings no estágio da implantação e especifique o seguinte:

Depois que uma versão canary é ativada, o estágio de implantação não pode ser associado a outra implantação da versão não canary até que a versão canary seja desativada e as suas configurações sejam removidas do estágio.

Quando você ativa o log de execução da API, a versão canary possui seus próprios registros e métricas geradas para todas as solicitações do canary. Eles são relatados a um grupo de logs do CloudWatch Logs do estágio de produção e a um grupo de logs do CloudWatch Logs específico ao canary. O mesmo se aplica ao registro de acesso. Os registros específicos do canary separados são úteis para validar novas alterações na API e decidir se aceitam as alterações e promovem a versão canary para o estágio de produção ou se descartam as alterações e revertem a versão canary do estágio de produção.

O grupo de logs de execução do estágio de produção é chamado API-Gateway-Execution-Logs/{rest-api-id}/{stage-name} e o grupo de logs de execução da versão canary é chamado API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary. Para o registro de acesso, você deve criar um novo grupo de logs ou escolher um existente. O nome do grupo de logs de acesso da versão canary tem o sufixo /Canary anexado ao nome do grupo de logs selecionado.

Uma versão canary pode usar o cache do estágio, se ativado, para armazenar respostas e usar entradas em cache para retornar resultados para as próximas solicitações canary, dentro de um período de TTL (Time-to-Live) pré-configurado.

Em uma implantação da versão canary, a versão de produção e a versão canary da API podem ser associadas a mesma versão ou a versões diferentes. Quando elas são associadas a versões diferentes, as respostas para produção e solicitações do canary são armazenadas em cache separadamente e o cache do estágio retorna resultados correspondentes para a produção e solicitações do canary. Quando a versão de produção e a versão canary são associadas a mesma implantação, o cache do estágio usa uma única chave de cache para ambos os tipos de solicitações e retorna a mesma resposta para as mesmas solicitações da versão de produção e versão canary.