# Configurar uma implantação de versão canary do API Gateway
A [versão canary](https://martinfowler.com/bliki/CanaryRelease.html) é 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.
**Topics**
+ [Implantação da versão canary no API Gateway](#api-gateway-canary-release-deployment-overview)
+ [Criar uma implantação da versão canary](create-canary-deployment.md)
+ [Atualizar uma versão canary](update-canary-deployment.md)
+ [Promover uma versão canary](promote-canary-deployment.md)
+ [Desativar uma versão de canário](delete-canary-deployment.md)
## 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) ao [estágio](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) de uma [implantação](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) 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:
+ Um ID de implantação inicialmente idêntico ao ID da implantação da versão base definido no estágio.
+ Uma [porcentagem do tráfego da API](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic), entre 0,0 e 100,0 (ambos incluídos), para a versão canary.
+ [Variáveis de estágio para a versão canary](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides) que podem substituir as variáveis de estágio da versão de produção.
+ O [uso do cache do estágio](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) para solicitações do canary, se o [useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) estiver definido e o armazenamento em cache da API estiver ativado no estágio.
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.