1.204.0

class Deployment (construct)

LanguageType name
.NETAmazon.CDK.AWS.APIGateway.Deployment
Javasoftware.amazon.awscdk.services.apigateway.Deployment
Pythonaws_cdk.aws_apigateway.Deployment
TypeScript (source)@aws-cdk/aws-apigateway » Deployment

Implements IConstruct, IConstruct, IDependable, IResource

A Deployment of a REST API.

An immutable representation of a RestApi resource that can be called by users using Stages. A deployment must be associated with a Stage for it to be callable over the Internet.

Normally, you don't need to define deployments manually. The RestApi construct manages a Deployment resource that represents the latest model. It can be accessed through restApi.latestDeployment (unless deploy: false is set when defining the RestApi).

If you manually define this resource, you will need to know that since deployments are immutable, as long as the resource's logical ID doesn't change, the deployment will represent the snapshot in time in which the resource was created. This means that if you modify the RestApi model (i.e. add methods or resources), these changes will not be reflected unless a new deployment resource is created.

To achieve this behavior, the method addToLogicalId(data) can be used to augment the logical ID generated for the deployment resource such that it will include arbitrary data. This is done automatically for the restApi.latestDeployment deployment.

Furthermore, since a deployment does not reference any of the REST API resources and methods, CloudFormation will likely provision it before these resources are created, which means that it will represent a "half-baked" model. Use the node.addDependency(dep) method to circumvent that. This is done automatically for the restApi.latestDeployment deployment.

Example

// production stage
const prdLogGroup = new logs.LogGroup(this, "PrdLogs");
const api = new apigateway.RestApi(this, 'books', {
  deployOptions: {
    accessLogDestination: new apigateway.LogGroupLogDestination(prdLogGroup),
    accessLogFormat: apigateway.AccessLogFormat.jsonWithStandardFields()
  }
})
const deployment = new apigateway.Deployment(this, 'Deployment', {api});

// development stage
const devLogGroup = new logs.LogGroup(this, "DevLogs");
new apigateway.Stage(this, 'dev', {
  deployment,
  accessLogDestination: new apigateway.LogGroupLogDestination(devLogGroup),
  accessLogFormat: apigateway.AccessLogFormat.jsonWithStandardFields({
    caller: false,
    httpMethod: true,
    ip: true,
    protocol: true,
    requestTime: true,
    resourcePath: true,
    responseLength: true,
    status: true,
    user: true
  })
});

Initializer

new Deployment(scope: Construct, id: string, props: DeploymentProps)

Parameters

Construct Props

NameTypeDescription
apiIRestApiThe Rest API to deploy.
description?stringA description of the purpose of the API Gateway deployment.
retainDeployments?booleanWhen an API Gateway model is updated, a new deployment will automatically be created.

api

Type: IRestApi

The Rest API to deploy.

description?

Type: string (optional, default: No description.)

A description of the purpose of the API Gateway deployment.

retainDeployments?

Type: boolean (optional, default: false)

When an API Gateway model is updated, a new deployment will automatically be created.

If this is true, the old API Gateway Deployment resource will not be deleted. This will allow manually reverting back to a previous deployment in case for example

Properties

NameTypeDescription
apiIRestApi
deploymentIdstring
envResourceEnvironmentThe environment this resource belongs to.
nodeConstructNodeThe construct tree node associated with this construct.
stackStackThe stack in which this resource is defined.

api

Type: IRestApi

deploymentId

Type: string

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

node

Type: ConstructNode

The construct tree node associated with this construct.

stack

Type: Stack

The stack in which this resource is defined.

Methods

NameDescription
addToLogicalId(data)Adds a component to the hash that determines this Deployment resource's logical ID.
applyRemovalPolicy(policy)Apply the given removal policy to this resource.
toString()Returns a string representation of this construct.

addToLogicalId(data)

public addToLogicalId(data: any): void

Parameters

  • data any

Adds a component to the hash that determines this Deployment resource's logical ID.

This should be called by constructs of the API Gateway model that want to invalidate the deployment when their settings change. The component will be resolve()ed during synthesis so tokens are welcome.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

toString()

public toString(): string

Returns

  • string

Returns a string representation of this construct.

← PreviousNext →