API Gateway canary deployment with Terraform



We would like to deploy API changes with Terraform to the canary-enabled stage, something similar to "Canary deployment" section here: https://aws.amazon.com/blogs/compute/performing-canary-deployments-for-service-integrations-with-amazon-api-gateway/

Our simplified Terraform configuration looks like this:

resource "aws_api_gateway_rest_api" "canary" {
  name = "canary-poc"
  endpoint_configuration {
    types = ["REGIONAL"]
  body = jsonencode({
    openapi = "3.0.1"
    info = {
      title   = "canary-poc"
      version = "1.0"
    paths = {
      "/path" = {
        get = {
          x-amazon-apigateway-integration = {
            httpMethod           = "POST"
            payloadFormatVersion = "1.0"
            type                 = "AWS_PROXY"
            uri                  = ...

resource "aws_api_gateway_deployment" "canary" {
  rest_api_id = aws_api_gateway_rest_api.canary.id
  triggers = {
    redeployment = sha1(jsonencode(aws_api_gateway_rest_api.canary.body))
  lifecycle {
    create_before_destroy = true

resource "aws_api_gateway_stage" "canary" {
  deployment_id = aws_api_gateway_deployment.canary.id
  rest_api_id   = aws_api_gateway_rest_api.canary.id
  stage_name    = ...
  canary_settings {
    percent_traffic = 50.0

resource "aws_api_gateway_base_path_mapping" "canary" {
  api_id      = aws_api_gateway_rest_api.canary.id
  stage_name  = aws_api_gateway_stage.canary.stage_name
  domain_name = aws_api_gateway_domain_name.canary.domain_name

If I load API changes and deploy manually in AWS Console to the canary-enabled stage the previous deploy is correctly attached to the current stage and newly deployed one to the canary: manual deployment

I can then promote canary: canary promoted

However when I deploy API changes to the canary-enabled stage with TF, AWS does not correctly attach the deployment -- it is not attached to the canary: next TF deploy

The deployment history in the stage is not kept -- every time I deploy with Terraform, the previous deployment is deleted (due to deployment resource create_before_destroy lifecycle rule in TF):next TF deploy

Deployment resource create_before_destroy lifecycle rule in TF is recommended to avoid cycle errors: https://github.com/hashicorp/terraform-provider-aws/issues/11344 https://registry.terraform.io/providers/hashicorp/aws/4.38.0/docs/resources/api_gateway_deployment

Is there any way to configure deployment in Terraform to have IaC canary deployments?

1 Answer


I understand that you have a query regarding canary deployments using Terraform. By looking at the details provided, I believe that the set up works without any issues when deployed using the AWS API Gateway console, and you are facing issues while trying to do the same with Terraform.

Being an AWS Premium Support Engineer, I would like to kindly inform you that, unfortunately Terraform is a third party tool (owned by Hashicorp), and thus it is not supported by AWS. The deployment behavior from Terraform may differ from how AWS CloudFormation handles deployments, and I would highly recommend you to reach out to the Terraform community if you have any questions on the issues that you face. As it is working correct when done using API gateway console manually, you could reach out to the support team of Terraform or their community on this link for more information about your issue and use-case.

[+] https://www.terraform.io/community

Additionally, I would also suggest you to create an issue on the Terraform GitHub page, so that they can assist you better with your requirements and issues.

[+] https://github.com/hashicorp/terraform/issues

[+] https://github.com/hashicorp/terraform-provider-aws/issues

I sincerely apologize for not being able to address your query as we are not knowledgeable with the issues that are encountered or regarding the features while using terraform, as it is a third party tool, and beyond our scope of support. I hope you understand our limitations here and believe you would reach out to the Terraform team regarding your concern.

answered a year ago
profile picture
reviewed 2 months ago

You are not logged in. Log in to post an answer.

A good answer clearly answers the question and provides constructive feedback and encourages professional growth in the question asker.

Guidelines for Answering Questions