Stage

Provides an API Gateway Stage.

Example Usage

using Pulumi;
using Aws = Pulumi.Aws;

class MyStack : Stack
{
    public MyStack()
    {
        var testRestApi = new Aws.ApiGateway.RestApi("testRestApi", new Aws.ApiGateway.RestApiArgs
        {
            Description = "This is my API for demonstration purposes",
        });
        var testDeployment = new Aws.ApiGateway.Deployment("testDeployment", new Aws.ApiGateway.DeploymentArgs
        {
            RestApi = testRestApi.Id,
            StageName = "dev",
        }, new CustomResourceOptions
        {
            DependsOn = 
            {
                "aws_api_gateway_integration.test",
            },
        });
        var testStage = new Aws.ApiGateway.Stage("testStage", new Aws.ApiGateway.StageArgs
        {
            Deployment = testDeployment.Id,
            RestApi = testRestApi.Id,
            StageName = "prod",
        });
        var testResource = new Aws.ApiGateway.Resource("testResource", new Aws.ApiGateway.ResourceArgs
        {
            ParentId = testRestApi.RootResourceId,
            PathPart = "mytestresource",
            RestApi = testRestApi.Id,
        });
        var testMethod = new Aws.ApiGateway.Method("testMethod", new Aws.ApiGateway.MethodArgs
        {
            Authorization = "NONE",
            HttpMethod = "GET",
            ResourceId = testResource.Id,
            RestApi = testRestApi.Id,
        });
        var methodSettings = new Aws.ApiGateway.MethodSettings("methodSettings", new Aws.ApiGateway.MethodSettingsArgs
        {
            MethodPath = Output.Tuple(testResource.PathPart, testMethod.HttpMethod).Apply(values =>
            {
                var pathPart = values.Item1;
                var httpMethod = values.Item2;
                return $"{pathPart}/{httpMethod}";
            }),
            RestApi = testRestApi.Id,
            Settings = new Aws.ApiGateway.Inputs.MethodSettingsSettingsArgs
            {
                LoggingLevel = "INFO",
                MetricsEnabled = true,
            },
            StageName = testStage.StageName,
        });
        var testIntegration = new Aws.ApiGateway.Integration("testIntegration", new Aws.ApiGateway.IntegrationArgs
        {
            HttpMethod = testMethod.HttpMethod,
            ResourceId = testResource.Id,
            RestApi = testRestApi.Id,
            Type = "MOCK",
        });
    }

}

package main

import (
    "fmt"

    "github.com/pulumi/pulumi-aws/sdk/v2/go/aws/apigateway"
    "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        testRestApi, err := apigateway.NewRestApi(ctx, "testRestApi", &apigateway.RestApiArgs{
            Description: pulumi.String("This is my API for demonstration purposes"),
        })
        if err != nil {
            return err
        }
        testDeployment, err := apigateway.NewDeployment(ctx, "testDeployment", &apigateway.DeploymentArgs{
            RestApi:   testRestApi.ID(),
            StageName: pulumi.String("dev"),
        }, pulumi.DependsOn([]pulumi.Resource{
            "aws_api_gateway_integration.test",
        }))
        if err != nil {
            return err
        }
        testStage, err := apigateway.NewStage(ctx, "testStage", &apigateway.StageArgs{
            Deployment: testDeployment.ID(),
            RestApi:    testRestApi.ID(),
            StageName:  pulumi.String("prod"),
        })
        if err != nil {
            return err
        }
        testResource, err := apigateway.NewResource(ctx, "testResource", &apigateway.ResourceArgs{
            ParentId: testRestApi.RootResourceId,
            PathPart: pulumi.String("mytestresource"),
            RestApi:  testRestApi.ID(),
        })
        if err != nil {
            return err
        }
        testMethod, err := apigateway.NewMethod(ctx, "testMethod", &apigateway.MethodArgs{
            Authorization: pulumi.String("NONE"),
            HttpMethod:    pulumi.String("GET"),
            ResourceId:    testResource.ID(),
            RestApi:       testRestApi.ID(),
        })
        if err != nil {
            return err
        }
        _, err = apigateway.NewMethodSettings(ctx, "methodSettings", &apigateway.MethodSettingsArgs{
            MethodPath: pulumi.All(testResource.PathPart, testMethod.HttpMethod).ApplyT(func(_args []interface{}) (string, error) {
                pathPart := _args[0].(string)
                httpMethod := _args[1].(string)
                return fmt.Sprintf("%v%v%v", pathPart, "/", httpMethod), nil
            }).(pulumi.StringOutput),
            RestApi: testRestApi.ID(),
            Settings: &apigateway.MethodSettingsSettingsArgs{
                LoggingLevel:   pulumi.String("INFO"),
                MetricsEnabled: pulumi.Bool(true),
            },
            StageName: testStage.StageName,
        })
        if err != nil {
            return err
        }
        _, err = apigateway.NewIntegration(ctx, "testIntegration", &apigateway.IntegrationArgs{
            HttpMethod: testMethod.HttpMethod,
            ResourceId: testResource.ID(),
            RestApi:    testRestApi.ID(),
            Type:       pulumi.String("MOCK"),
        })
        if err != nil {
            return err
        }
        return nil
    })
}

import pulumi
import pulumi_aws as aws

test_rest_api = aws.apigateway.RestApi("testRestApi", description="This is my API for demonstration purposes")
test_deployment = aws.apigateway.Deployment("testDeployment",
    rest_api=test_rest_api.id,
    stage_name="dev",
    opts=ResourceOptions(depends_on=["aws_api_gateway_integration.test"]))
test_stage = aws.apigateway.Stage("testStage",
    deployment=test_deployment.id,
    rest_api=test_rest_api.id,
    stage_name="prod")
test_resource = aws.apigateway.Resource("testResource",
    parent_id=test_rest_api.root_resource_id,
    path_part="mytestresource",
    rest_api=test_rest_api.id)
test_method = aws.apigateway.Method("testMethod",
    authorization="NONE",
    http_method="GET",
    resource_id=test_resource.id,
    rest_api=test_rest_api.id)
method_settings = aws.apigateway.MethodSettings("methodSettings",
    method_path=pulumi.Output.all(test_resource.path_part, test_method.http_method).apply(lambda path_part, http_method: f"{path_part}/{http_method}"),
    rest_api=test_rest_api.id,
    settings={
        "loggingLevel": "INFO",
        "metricsEnabled": True,
    },
    stage_name=test_stage.stage_name)
test_integration = aws.apigateway.Integration("testIntegration",
    http_method=test_method.http_method,
    resource_id=test_resource.id,
    rest_api=test_rest_api.id,
    type="MOCK")

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

const testRestApi = new aws.apigateway.RestApi("test", {
    description: "This is my API for demonstration purposes",
});
const testResource = new aws.apigateway.Resource("test", {
    parentId: testRestApi.rootResourceId,
    pathPart: "mytestresource",
    restApi: testRestApi.id,
});
const testMethod = new aws.apigateway.Method("test", {
    authorization: "NONE",
    httpMethod: "GET",
    resourceId: testResource.id,
    restApi: testRestApi.id,
});
const testIntegration = new aws.apigateway.Integration("test", {
    httpMethod: testMethod.httpMethod,
    resourceId: testResource.id,
    restApi: testRestApi.id,
    type: "MOCK",
});
const testDeployment = new aws.apigateway.Deployment("test", {
    restApi: testRestApi.id,
    stageName: "dev",
}, { dependsOn: [testIntegration] });
const testStage = new aws.apigateway.Stage("test", {
    deployment: testDeployment.id,
    restApi: testRestApi.id,
    stageName: "prod",
});
const methodSettings = new aws.apigateway.MethodSettings("s", {
    methodPath: pulumi.interpolate`${testResource.pathPart}/${testMethod.httpMethod}`,
    restApi: testRestApi.id,
    settings: {
        loggingLevel: "INFO",
        metricsEnabled: true,
    },
    stageName: testStage.stageName,
});

Managing the API Logging CloudWatch Log Group

Coming soon!

import pulumi
import pulumi_aws as aws

config = pulumi.Config()
stage_name = config.get("stageName")
if stage_name is None:
    stage_name = "example"
example_rest_api = aws.apigateway.RestApi("exampleRestApi")
example_stage = aws.apigateway.Stage("exampleStage", name=stage_name,
opts=ResourceOptions(depends_on=["aws_cloudwatch_log_group.example"]))
example_log_group = aws.cloudwatch.LogGroup("exampleLogGroup", retention_in_days=7)

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

const config = new pulumi.Config();
const stageName = config.get("stageName") || "example";

const exampleRestApi = new aws.apigateway.RestApi("example", {});
const exampleLogGroup = new aws.cloudwatch.LogGroup("example", {
    retentionInDays: 7,
});
const exampleStage = new aws.apigateway.Stage("example", {
    name: stageName,
}, { dependsOn: [exampleLogGroup] });

Create a Stage Resource

new Stage(name: string, args: StageArgs, opts?: CustomResourceOptions);

def Stage(resource_name, opts=None, access_log_settings=None, cache_cluster_enabled=None, cache_cluster_size=None, client_certificate_id=None, deployment=None, description=None, documentation_version=None, rest_api=None, stage_name=None, tags=None, variables=None, xray_tracing_enabled=None, __props__=None);

func NewStage(ctx *Context, name string, args StageArgs, opts ...ResourceOption) (*Stage, error)

public Stage(string name, StageArgs args, CustomResourceOptions? opts = null)

name string: The unique name of the resource.
args StageArgs: The arguments to resource properties.
opts CustomResourceOptions: Bag of options to control resource's behavior.

resource_name str: The unique name of the resource.
opts ResourceOptions: A bag of options that control this resource's behavior.

ctx Context: Context object for the current deployment.
name string: The unique name of the resource.
args StageArgs: The arguments to resource properties.
opts ResourceOption: Bag of options to control resource's behavior.

name string: The unique name of the resource.
args StageArgs: The arguments to resource properties.
opts CustomResourceOptions: Bag of options to control resource's behavior.

Stage Resource Properties

To learn more about resource properties and how to use them, see Inputs and Outputs in the Programming Model docs.

Inputs

The Stage resource accepts the following input properties:

Deployment string: The ID of the deployment that the stage points to
RestApi string: The ID of the associated REST API
StageName string: The name of the stage
AccessLogSettings StageAccessLogSettingsArgs: Enables access logs for the API stage. Detailed below.
CacheClusterEnabled bool: Specifies whether a cache cluster is enabled for the stage
CacheClusterSize string: The 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.
ClientCertificateId string: The identifier of a client certificate for the stage.
Description string: The description of the stage
DocumentationVersion string: The version of the associated API documentation
Tags Dictionary<string, string>: A map of tags to assign to the resource.
Variables Dictionary<string, string>: A map that defines the stage variables
XrayTracingEnabled bool: Whether active tracing with X-ray is enabled. Defaults to false.

Deployment interface{}: The ID of the deployment that the stage points to
RestApi interface{}: The ID of the associated REST API
StageName string: The name of the stage
AccessLogSettings StageAccessLogSettings: Enables access logs for the API stage. Detailed below.
CacheClusterEnabled bool: Specifies whether a cache cluster is enabled for the stage
CacheClusterSize string: The 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.
ClientCertificateId string: The identifier of a client certificate for the stage.
Description string: The description of the stage
DocumentationVersion string: The version of the associated API documentation
Tags map[string]string: A map of tags to assign to the resource.
Variables map[string]string: A map that defines the stage variables
XrayTracingEnabled bool: Whether active tracing with X-ray is enabled. Defaults to false.

deployment string | Deployment: The ID of the deployment that the stage points to
restApi string | RestApi: The ID of the associated REST API
stageName string: The name of the stage
accessLogSettings StageAccessLogSettings: Enables access logs for the API stage. Detailed below.
cacheClusterEnabled boolean: Specifies whether a cache cluster is enabled for the stage
cacheClusterSize string: The 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.
clientCertificateId string: The identifier of a client certificate for the stage.
description string: The description of the stage
documentationVersion string: The version of the associated API documentation
tags {[key: string]: string}: A map of tags to assign to the resource.
variables {[key: string]: string}: A map that defines the stage variables
xrayTracingEnabled boolean: Whether active tracing with X-ray is enabled. Defaults to false.

deployment string | str: The ID of the deployment that the stage points to
rest_api string | str: The ID of the associated REST API
stage_name str: The name of the stage
access_log_settings Dict[StageAccessLogSettings]: Enables access logs for the API stage. Detailed below.
cache_cluster_enabled bool: Specifies whether a cache cluster is enabled for the stage
cache_cluster_size str: The 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.
client_certificate_id str: The identifier of a client certificate for the stage.
description str: The description of the stage
documentation_version str: The version of the associated API documentation
tags Dict[str, str]: A map of tags to assign to the resource.
variables Dict[str, str]: A map that defines the stage variables
xray_tracing_enabled bool: Whether active tracing with X-ray is enabled. Defaults to false.

Outputs

All input properties are implicitly available as output properties. Additionally, the Stage resource produces the following output properties:

Arn string: Amazon Resource Name (ARN)
ExecutionArn string: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
Id string: The provider-assigned unique ID for this managed resource.
InvokeUrl string: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod

Arn string: Amazon Resource Name (ARN)
ExecutionArn string: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
Id string: The provider-assigned unique ID for this managed resource.
InvokeUrl string: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod

arn string: Amazon Resource Name (ARN)
executionArn string: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
id string: The provider-assigned unique ID for this managed resource.
invokeUrl string: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod

arn str: Amazon Resource Name (ARN)
execution_arn str: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
id str: The provider-assigned unique ID for this managed resource.
invoke_url str: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod

Look up an Existing Stage Resource

Get an existing Stage resource’s state with the given name, ID, and optional extra properties used to qualify the lookup.

public static get(name: string, id: Input<ID>, state?: StageState, opts?: CustomResourceOptions): Stage

static get(resource_name, id, opts=None, access_log_settings=None, arn=None, cache_cluster_enabled=None, cache_cluster_size=None, client_certificate_id=None, deployment=None, description=None, documentation_version=None, execution_arn=None, invoke_url=None, rest_api=None, stage_name=None, tags=None, variables=None, xray_tracing_enabled=None, __props__=None);

func GetStage(ctx *Context, name string, id IDInput, state *StageState, opts ...ResourceOption) (*Stage, error)

public static Stage Get(string name, Input<string> id, StageState? state, CustomResourceOptions? opts = null)

name: The unique name of the resulting resource.
id: The unique provider ID of the resource to lookup.
state: Any extra arguments used during the lookup.
opts: A bag of options that control this resource's behavior.

resource_name: The unique name of the resulting resource.
id: The unique provider ID of the resource to lookup.

name: The unique name of the resulting resource.
id: The unique provider ID of the resource to lookup.
state: Any extra arguments used during the lookup.
opts: A bag of options that control this resource's behavior.

name: The unique name of the resulting resource.
id: The unique provider ID of the resource to lookup.
state: Any extra arguments used during the lookup.
opts: A bag of options that control this resource's behavior.

The following state arguments are supported:

AccessLogSettings StageAccessLogSettingsArgs: Enables access logs for the API stage. Detailed below.
Arn string: Amazon Resource Name (ARN)
CacheClusterEnabled bool: Specifies whether a cache cluster is enabled for the stage
CacheClusterSize string: The 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.
ClientCertificateId string: The identifier of a client certificate for the stage.
Deployment string: The ID of the deployment that the stage points to
Description string: The description of the stage
DocumentationVersion string: The version of the associated API documentation
ExecutionArn string: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
InvokeUrl string: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod
RestApi string: The ID of the associated REST API
StageName string: The name of the stage
Tags Dictionary<string, string>: A map of tags to assign to the resource.
Variables Dictionary<string, string>: A map that defines the stage variables
XrayTracingEnabled bool: Whether active tracing with X-ray is enabled. Defaults to false.

AccessLogSettings StageAccessLogSettings: Enables access logs for the API stage. Detailed below.
Arn string: Amazon Resource Name (ARN)
CacheClusterEnabled bool: Specifies whether a cache cluster is enabled for the stage
CacheClusterSize string: The 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.
ClientCertificateId string: The identifier of a client certificate for the stage.
Deployment interface{}: The ID of the deployment that the stage points to
Description string: The description of the stage
DocumentationVersion string: The version of the associated API documentation
ExecutionArn string: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
InvokeUrl string: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod
RestApi interface{}: The ID of the associated REST API
StageName string: The name of the stage
Tags map[string]string: A map of tags to assign to the resource.
Variables map[string]string: A map that defines the stage variables
XrayTracingEnabled bool: Whether active tracing with X-ray is enabled. Defaults to false.

accessLogSettings StageAccessLogSettings: Enables access logs for the API stage. Detailed below.
arn string: Amazon Resource Name (ARN)
cacheClusterEnabled boolean: Specifies whether a cache cluster is enabled for the stage
cacheClusterSize string: The 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.
clientCertificateId string: The identifier of a client certificate for the stage.
deployment string | Deployment: The ID of the deployment that the stage points to
description string: The description of the stage
documentationVersion string: The version of the associated API documentation
executionArn string: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
invokeUrl string: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod
restApi string | RestApi: The ID of the associated REST API
stageName string: The name of the stage
tags {[key: string]: string}: A map of tags to assign to the resource.
variables {[key: string]: string}: A map that defines the stage variables
xrayTracingEnabled boolean: Whether active tracing with X-ray is enabled. Defaults to false.

access_log_settings Dict[StageAccessLogSettings]: Enables access logs for the API stage. Detailed below.
arn str: Amazon Resource Name (ARN)
cache_cluster_enabled bool: Specifies whether a cache cluster is enabled for the stage
cache_cluster_size str: The 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.
client_certificate_id str: The identifier of a client certificate for the stage.
deployment string | str: The ID of the deployment that the stage points to
description str: The description of the stage
documentation_version str: The version of the associated API documentation
execution_arn str: The execution ARN to be used in lambda_permission’s source_arn when allowing API Gateway to invoke a Lambda function, e.g. arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j/prod
invoke_url str: The URL to invoke the API pointing to the stage, e.g. https://z4675bid1j.execute-api.eu-west-2.amazonaws.com/prod
rest_api string | str: The ID of the associated REST API
stage_name str: The name of the stage
tags Dict[str, str]: A map of tags to assign to the resource.
variables Dict[str, str]: A map that defines the stage variables
xray_tracing_enabled bool: Whether active tracing with X-ray is enabled. Defaults to false.

Supporting Types

StageAccessLogSettings

See the input and output API doc for this type.

DestinationArn string: The Amazon Resource Name (ARN) of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with amazon-apigateway-. Automatically removes trailing :* if present.
Format string: The formatting and values recorded in the logs. For more information on configuring the log format rules visit the AWS documentation

DestinationArn string: The Amazon Resource Name (ARN) of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with amazon-apigateway-. Automatically removes trailing :* if present.
Format string: The formatting and values recorded in the logs. For more information on configuring the log format rules visit the AWS documentation

destinationArn string: The Amazon Resource Name (ARN) of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with amazon-apigateway-. Automatically removes trailing :* if present.
format string: The formatting and values recorded in the logs. For more information on configuring the log format rules visit the AWS documentation

destination_arn str: The Amazon Resource Name (ARN) of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with amazon-apigateway-. Automatically removes trailing :* if present.
format str: The formatting and values recorded in the logs. For more information on configuring the log format rules visit the AWS documentation

Package Details

Repository: https://github.com/pulumi/pulumi-aws
License: Apache-2.0
Notes: This Pulumi package is based on the aws Terraform Provider.

The Pulumi Platform

Get Started

Migrate to Pulumi

Solutions for All Teams and Engineers

Any Code

Any Cloud