Resource: aws_api_gateway_stage

Manages an API Gateway Stage. A stage is a named reference to a deployment, which can be done via the aws_api_gateway_deployment resource. Stages can be optionally managed further with the aws_api_gateway_base_path_mapping resource, aws_api_gateway_domain_name resource, and aws_api_method_settings resource. For more information, see the API Gateway Developer Guide.

Example Usage

An end-to-end example of a REST API configured with OpenAPI can be found in the /examples/api-gateway-rest-api-openapi directory within the GitHub repository.

resource "aws_api_gateway_rest_api" "example" {
  body = jsonencode({
    openapi = "3.0.1"
    info = {
      title   = "example"
      version = "1.0"
    }
    paths = {
      "/path1" = {
        get = {
          x-amazon-apigateway-integration = {
            httpMethod           = "GET"
            payloadFormatVersion = "1.0"
            type                 = "HTTP_PROXY"
            uri                  = "https://ip-ranges.amazonaws.com/ip-ranges.json"
          }
        }
      }
    }
  })

  name = "example"
}

resource "aws_api_gateway_deployment" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id

  triggers = {
    redeployment = sha1(jsonencode(aws_api_gateway_rest_api.example.body))
  }

  lifecycle {
    create_before_destroy = true
  }
}

resource "aws_api_gateway_stage" "example" {
  deployment_id = aws_api_gateway_deployment.example.id
  rest_api_id   = aws_api_gateway_rest_api.example.id
  stage_name    = "example"
}

resource "aws_api_gateway_method_settings" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = aws_api_gateway_stage.example.stage_name
  method_path = "*/*"

  settings {
    metrics_enabled = true
    logging_level   = "INFO"
  }
}

Managing the API Logging CloudWatch Log Group

API Gateway provides the ability to enable CloudWatch API logging. To manage the CloudWatch Log Group when this feature is enabled, the aws_cloudwatch_log_group resource can be used where the name matches the API Gateway naming convention. If the CloudWatch Log Group previously exists, import the aws_cloudwatch_log_group resource into Terraform as a one time operation. You can recreate the environment without import.

variable "stage_name" {
  default = "example"
  type    = string
}

resource "aws_api_gateway_rest_api" "example" {
  # ... other configuration ...
}

resource "aws_api_gateway_stage" "example" {
  depends_on = [aws_cloudwatch_log_group.example]

  stage_name = var.stage_name
  # ... other configuration ...
}

resource "aws_cloudwatch_log_group" "example" {
  name              = "API-Gateway-Execution-Logs_${aws_api_gateway_rest_api.example.id}/${var.stage_name}"
  retention_in_days = 7
  # ... potentially other configuration ...
}

Argument Reference

This resource supports the following arguments:

Access Log Settings

Canary Settings

Attribute Reference

This resource exports the following attributes in addition to the arguments above:

Import

In Terraform v1.5.0 and later, use an import block to import aws_api_gateway_stage using REST-API-ID/STAGE-NAME. For example:

import {
  to = aws_api_gateway_stage.example
  id = "12345abcde/example"
}

Using terraform import, import aws_api_gateway_stage using REST-API-ID/STAGE-NAME. For example:

% terraform import aws_api_gateway_stage.example 12345abcde/example