Skip to content

aws.apigatewayv2-stage resource

Description

Stage manages a stage of an API Gateway v2 API: a named deployment of the API, reachable at its own URL. A stage is addressed by the pair of its API id and its name, so a change to either replaces it; every other input is reconciled in place. The API's protocol type, HTTP or WebSocket, decides which route-setting members may be sent, so creates and updates first read the API itself.

Source: internal/service/apigatewayv2/stage_rsrc.go:26

Example usage:

imports: {
  aws: 'github.com/cloudboss/unobin-library-aws'
}

resources: {
  example: aws.apigatewayv2-stage {
    # Set input fields here.
  }
}

Inputs

api-id

string

required

ApiId is the identifier of the API the stage belongs to.

name

string

required

Name is the stage name: up to 128 characters of alphanumerics, hyphens, and underscores, or the literal $default (AWS enforces the form). The name becomes the path of the invoke URL.

access-log-settings

optional(object) 
optional(
  object({
    destination-arn: string
    format: string
  })
)

AccessLogSettings turns on access logging for the stage. Removing the block turns it off again.

auto-deploy

optional(boolean)

AutoDeploy makes every change to the API deploy to this stage automatically. It defaults to false and cannot combine with deployment-id, since AWS then chooses the deployment itself.

client-certificate-id

optional(string)

ClientCertificateId names the client certificate the stage presents to backend integrations. Supported only for WebSocket APIs. Removing the field detaches the certificate.

default-route-settings

optional(object) 
optional(
  object({
    data-trace-enabled: optional(boolean)
    detailed-metrics-enabled: optional(boolean)
    logging-level: optional(string)
    throttling-burst-limit: optional(integer)
    throttling-rate-limit: optional(number)
  })
)

DefaultRouteSettings applies to every route that has no settings of its own. Removing the block resets its members to their defaults, except logging-level, which AWS keeps until it is set again; send OFF explicitly to silence WebSocket execution logging.

deployment-id

optional(string)

DeploymentId pins the stage to one deployment of the API. It must be absent when auto-deploy is enabled. Once set, removing the field leaves the stage on its current deployment.

description

optional(string)

Description describes the stage, in up to 1024 characters. Removing it clears the stored description.

route-settings

list(object) 
list(
  object({
    route-key: string
    data-trace-enabled: optional(boolean)
    detailed-metrics-enabled: optional(boolean)
    logging-level: optional(string)
    throttling-burst-limit: optional(integer)
    throttling-rate-limit: optional(number)
  })
)

RouteSettings overrides the default route settings for individual routes, one entry per route key. Route keys must be unique. An entry may name a route key with no matching route, such as $disconnect on a WebSocket API.

stage-variables

map(string)

StageVariables are name-value pairs available to integrations. Values may use the characters [A-Za-z0-9-._~:/?#&=,] (AWS enforces the form). An empty value is not representable, because the API reads an empty string as an instruction to remove the variable.

tags

map(string)

Tags are the stage's tags.

Input Constraints

Auto deploy rules

deployment-id cannot be set when auto-deploy is enabled.

Rule logic
When
input.auto-deploy == true
Require
input.deployment-id == null

Default route settings rules

default-route-settings logging-level must be ERROR, INFO, or OFF.

Rule logic
When
input.default-route-settings.logging-level != null
Require
input.default-route-settings.logging-level == 'ERROR'
|| input.default-route-settings.logging-level == 'INFO'
|| input.default-route-settings.logging-level == 'OFF'

Route settings rules

route-settings logging-level must be ERROR, INFO, or OFF.

Rule logic
For each
input.route-settings
When
@each.value.logging-level != null
Require
@each.value.logging-level == 'ERROR'
|| @each.value.logging-level == 'INFO'
|| @each.value.logging-level == 'OFF'

Outputs

api-id

string

name

string

arn

string

invoke-url

string

deployment-id

string