Stage class

Manages an API Gateway Stage. A stage is a named reference to a deployment, which can be done via the aws.apigateway.Deployment resource. Stages can be optionally managed further with the aws.apigateway.BasePathMapping resource, aws.apigateway.DomainName resource, and aws.apigateway.MethodSettings resource. For more information, see the API Gateway Developer Guide.

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.LogGroup resource can be used where the name matches the API Gateway naming convention. If the CloudWatch Log Group previously exists, import the aws.cloudwatch.LogGroup resource into Pulumi as a one time operation. You can recreate the environment without import.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const config = new pulumi.Config();
const stageName = config.get("stageName") || "example";
const example = new aws.apigateway.RestApi("example", {});
const exampleLogGroup = new aws.cloudwatch.LogGroup("example", {
    name: pulumi.interpolate`API-Gateway-Execution-Logs_${example.id}/${stageName}`,
    retentionInDays: 7,
});
const exampleStage = new aws.apigateway.Stage("example", {stageName: stageName}, {
    dependsOn: [exampleLogGroup],
});
import pulumi
import pulumi_aws as aws

config = pulumi.Config()
stage_name = config.get("stageName")
if stage_name is None:
    stage_name = "example"
example = aws.apigateway.RestApi("example")
example_log_group = aws.cloudwatch.LogGroup("example",
    name=example.id.apply(lambda id: f"API-Gateway-Execution-Logs_{id}/{stage_name}"),
    retention_in_days=7)
example_stage = aws.apigateway.Stage("example", stage_name=stage_name,
opts = pulumi.ResourceOptions(depends_on=[example_log_group]))
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() =>
{
    var config = new Config();
    var stageName = config.Get("stageName") ?? "example";
    var example = new Aws.ApiGateway.RestApi("example");

    var exampleLogGroup = new Aws.CloudWatch.LogGroup("example", new()
    {
        Name = example.Id.Apply(id => $"API-Gateway-Execution-Logs_{id}/{stageName}"),
        RetentionInDays = 7,
    });

    var exampleStage = new Aws.ApiGateway.Stage("example", new()
    {
        StageName = stageName,
    }, new CustomResourceOptions
    {
        DependsOn =
        {
            exampleLogGroup,
        },
    });

});
package main

import (
	"fmt"

	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/apigateway"
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/cloudwatch"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		cfg := config.New(ctx, "")
		stageName := "example"
		if param := cfg.Get("stageName"); param != "" {
			stageName = param
		}
		example, err := apigateway.NewRestApi(ctx, "example", nil)
		if err != nil {
			return err
		}
		exampleLogGroup, err := cloudwatch.NewLogGroup(ctx, "example", &cloudwatch.LogGroupArgs{
			Name: example.ID().ApplyT(func(id pulumi.ID) (string, error) {
				return fmt.Sprintf("API-Gateway-Execution-Logs_%v/%v", id, stageName), nil
			}).(pulumi.StringOutput),
			RetentionInDays: pulumi.Int(7),
		})
		if err != nil {
			return err
		}
		_, err = apigateway.NewStage(ctx, "example", &apigateway.StageArgs{
			StageName: pulumi.String(stageName),
		}, pulumi.DependsOn([]pulumi.Resource{
			exampleLogGroup,
		}))
		if err != nil {
			return err
		}
		return nil
	})
}
pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

resource "aws_apigateway_restapi" "example" {
}
resource "aws_apigateway_stage" "example" {
  depends_on = [aws_cloudwatch_loggroup.example]
  stage_name = var.stageName
}
resource "aws_cloudwatch_loggroup" "example" {
  name              ="API-Gateway-Execution-Logs_${aws_apigateway_restapi.example.id}/${var.stageName}"
  retention_in_days = 7
}
variable "stageName" {
  type    = string
  default = "example"
}
package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.apigateway.RestApi;
import com.pulumi.aws.cloudwatch.LogGroup;
import com.pulumi.aws.cloudwatch.LogGroupArgs;
import com.pulumi.aws.apigateway.Stage;
import com.pulumi.aws.apigateway.StageArgs;
import com.pulumi.resources.CustomResourceOptions;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var config = ctx.config();
        final var stageName = config.get("stageName").orElse("example");
        var example = new RestApi("example");

        var exampleLogGroup = new LogGroup("exampleLogGroup", LogGroupArgs.builder()
            .name(example.id().applyValue(_id -> String.format("API-Gateway-Execution-Logs_%s/%s", _id,stageName)))
            .retentionInDays(7)
            .build());

        var exampleStage = new Stage("exampleStage", StageArgs.builder()
            .stageName(stageName)
            .build(), CustomResourceOptions.builder()
                .dependsOn(exampleLogGroup)
                .build());

    }
}
configuration:
  stageName:
    type: string
    default: example
resources:
  example:
    type: aws:apigateway:RestApi
  exampleStage:
    type: aws:apigateway:Stage
    name: example
    properties:
      stageName: ${stageName}
    options:
      dependsOn:
        - ${exampleLogGroup}
  exampleLogGroup:
    type: aws:cloudwatch:LogGroup
    name: example
    properties:
      name: API-Gateway-Execution-Logs_${example.id}/${stageName}
      retentionInDays: 7 # ... potentially other configuration ...

Import

Using pulumi import, import aws.apigateway.Stage using REST-API-ID/STAGE-NAME. For example:

$ pulumi import aws:apigateway/stage:Stage example 12345abcde/example

Constructors

Stage(String name, {StageArgs? args, CustomResourceOptions? options})
Creates a new Stage. name The Pulumi resource name. args Arguments used to configure this Stage. The set of arguments for Stage. options Resource options controlling this resource's behavior.
Stage.reference(String urn)
Creates a typed reference to an existing Stage resource.

Properties

accessLogSettings ↔ Output<StageAccessLogSettings?>
Enables access logs for the API stage. See Access Log Settings below.
latefinal
arn ↔ Output<String>
ARN
latefinal
cacheClusterEnabled ↔ Output<bool?>
Whether a cache cluster is enabled for the stage
latefinal
cacheClusterSize ↔ Output<String?>
Size of the cache cluster for the stage, if enabled. Allowed values include 0.5, 1.6, 6.1, 13.5, 28.4, 58.2, 118 and 237.
latefinal
canarySettings ↔ Output<StageCanarySettings?>
Configuration settings of a canary deployment. See Canary Settings below.
latefinal
childResources → Set<Resource>
finalinherited
clientCertificateId ↔ Output<String?>
Identifier of a client certificate for the stage.
latefinal
completionSources ↔ Map<String, IOutputCompletionSource>
latefinalinherited
deployment ↔ Output<String>
ID of the deployment that the stage points to
latefinal
description ↔ Output<String?>
Description of the stage.
latefinal
documentationVersion ↔ Output<String?>
Version of the associated API documentation.
latefinal
executionArn ↔ Output<String>
Execution ARN to be used in lambdaPermission's sourceArn when allowing API Gateway to invoke a Lambda function, e.g., arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
latefinal
hashCode → int
The hash code for this object.
no setterinherited
id ↔ Output<String>
getter/setter pairinherited
invokeUrl ↔ Output<String>
URL to invoke the API pointing to the stage, e.g., https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod
latefinal
isCustom → bool
Returns whether this resource is provider-managed.
no setterinherited
isProtected → bool
Returns whether this resource is protected from deletion.
no setterinherited
isRemote → bool
Whether this resource is registered as remote.
no setterinherited
isResourceReference → bool
Whether this instance represents a resource value returned over RPC.
finalinherited
region ↔ Output<String>
Region where this resource will be managed. Defaults to the Region set in the provider configuration.
latefinal
resourceTransforms → List<ResourceTransform>
Inherited/explicit async transforms.
no setterinherited
restApi ↔ Output<String>
ID of the associated REST API
latefinal
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stageName ↔ Output<String>
Name of the stage
latefinal
tags ↔ Output<Map<String, String>?>
Map of tags to assign to the resource. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
latefinal
tagsAll ↔ Output<Map<String, String>>
Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.
latefinal
transformations → List<ResourceTransformation>
Inherited/explicit legacy transformations.
no setterinherited
urn ↔ Output<String>
latefinalinherited
variables ↔ Output<Map<String, String>?>
Map that defines the stage variables.
latefinal
webAclArn ↔ Output<String>
ARN of the WebAcl associated with the Stage.
latefinal
xrayTracingEnabled ↔ Output<bool?>
Whether active tracing with X-ray is enabled. Defaults to false.
latefinal

Methods

failId(Object error) → void
Completes this resource ID with an error when registration fails.
inherited
failOutputs(Object error) → void
Completes all output properties with error.
inherited
failUrn(Object error) → void
Completes this resource URN with an error when registration fails.
inherited
getProvider(String moduleMember) → ProviderResource?
Returns provider for moduleMember's package, if configured.
inherited
getResourceName() → String
Returns this resource's logical name.
inherited
getResourceType() → String
Returns this resource's Pulumi type token.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
registerOutput<T>(String propertyName, {Object? decoder(Object?)?, bool isSecret = false}) → Output<T>
Registers a dynamic output property for this resource.
inherited
resolveId(String? value, {required bool isKnown}) → void
Resolves the provider-assigned ID for this resource.
inherited
resolveOutputs(Struct outputs) → void
Resolves all output properties from a monitor response payload.
inherited
resolveUrn(String value) → void
Resolves this resource's URN once assigned by the engine.
inherited
serializeProperties(Map<String, dynamic> properties) → Future<Struct>
Serializes resource properties for RPC transmission.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

get(String name, Input<String> id, {StageState? state, CustomResourceOptions? options}) → Stage
Gets an existing Stage resource's state with the given name and id.