DescribeStacksCommand

Suggest an Edit

Returns the description for the specified stack; if no stack name was specified, then it returns the description for all the stacks created. For more information about a stack's event history, see Understand CloudFormation stack creation events  in the CloudFormation User Guide.

If the stack doesn't exist, a ValidationError is returned.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { CloudFormationClient, DescribeStacksCommand } from "@aws-sdk/client-cloudformation"; // ES Modules import
// const { CloudFormationClient, DescribeStacksCommand } = require("@aws-sdk/client-cloudformation"); // CommonJS import
const client = new CloudFormationClient(config);
const input = { // DescribeStacksInput
  StackName: "STRING_VALUE",
  NextToken: "STRING_VALUE",
};
const command = new DescribeStacksCommand(input);
const response = await client.send(command);
// { // DescribeStacksOutput
//   Stacks: [ // Stacks
//     { // Stack
//       StackId: "STRING_VALUE",
//       StackName: "STRING_VALUE", // required
//       ChangeSetId: "STRING_VALUE",
//       Description: "STRING_VALUE",
//       Parameters: [ // Parameters
//         { // Parameter
//           ParameterKey: "STRING_VALUE",
//           ParameterValue: "STRING_VALUE",
//           UsePreviousValue: true || false,
//           ResolvedValue: "STRING_VALUE",
//         },
//       ],
//       CreationTime: new Date("TIMESTAMP"), // required
//       DeletionTime: new Date("TIMESTAMP"),
//       LastUpdatedTime: new Date("TIMESTAMP"),
//       RollbackConfiguration: { // RollbackConfiguration
//         RollbackTriggers: [ // RollbackTriggers
//           { // RollbackTrigger
//             Arn: "STRING_VALUE", // required
//             Type: "STRING_VALUE", // required
//           },
//         ],
//         MonitoringTimeInMinutes: Number("int"),
//       },
//       StackStatus: "CREATE_IN_PROGRESS" || "CREATE_FAILED" || "CREATE_COMPLETE" || "ROLLBACK_IN_PROGRESS" || "ROLLBACK_FAILED" || "ROLLBACK_COMPLETE" || "DELETE_IN_PROGRESS" || "DELETE_FAILED" || "DELETE_COMPLETE" || "UPDATE_IN_PROGRESS" || "UPDATE_COMPLETE_CLEANUP_IN_PROGRESS" || "UPDATE_COMPLETE" || "UPDATE_FAILED" || "UPDATE_ROLLBACK_IN_PROGRESS" || "UPDATE_ROLLBACK_FAILED" || "UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS" || "UPDATE_ROLLBACK_COMPLETE" || "REVIEW_IN_PROGRESS" || "IMPORT_IN_PROGRESS" || "IMPORT_COMPLETE" || "IMPORT_ROLLBACK_IN_PROGRESS" || "IMPORT_ROLLBACK_FAILED" || "IMPORT_ROLLBACK_COMPLETE", // required
//       StackStatusReason: "STRING_VALUE",
//       DisableRollback: true || false,
//       NotificationARNs: [ // NotificationARNs
//         "STRING_VALUE",
//       ],
//       TimeoutInMinutes: Number("int"),
//       Capabilities: [ // Capabilities
//         "CAPABILITY_IAM" || "CAPABILITY_NAMED_IAM" || "CAPABILITY_AUTO_EXPAND",
//       ],
//       Outputs: [ // Outputs
//         { // Output
//           OutputKey: "STRING_VALUE",
//           OutputValue: "STRING_VALUE",
//           Description: "STRING_VALUE",
//           ExportName: "STRING_VALUE",
//         },
//       ],
//       RoleARN: "STRING_VALUE",
//       Tags: [ // Tags
//         { // Tag
//           Key: "STRING_VALUE", // required
//           Value: "STRING_VALUE", // required
//         },
//       ],
//       EnableTerminationProtection: true || false,
//       ParentId: "STRING_VALUE",
//       RootId: "STRING_VALUE",
//       DriftInformation: { // StackDriftInformation
//         StackDriftStatus: "DRIFTED" || "IN_SYNC" || "UNKNOWN" || "NOT_CHECKED", // required
//         LastCheckTimestamp: new Date("TIMESTAMP"),
//       },
//       RetainExceptOnCreate: true || false,
//       DeletionMode: "STANDARD" || "FORCE_DELETE_STACK",
//       DetailedStatus: "CONFIGURATION_COMPLETE" || "VALIDATION_FAILED",
//     },
//   ],
//   NextToken: "STRING_VALUE",
// };

DescribeStacksCommand Input

See DescribeStacksCommandInput for more details

Parameter
Type
Description
NextToken
string | undefined

A string that identifies the next page of stacks that you want to retrieve.

StackName
string | undefined

If you don't pass a parameter to StackName, the API returns a response that describes all resources in the account, which can impact performance. This requires ListStacks and DescribeStacks permissions.

Consider using the ListStacks API if you're not passing a parameter to StackName.

The IAM policy below can be added to IAM policies when you want to limit resource-level permissions and avoid returning a response when no parameter is sent in the request:

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Deny", "Action": "cloudformation:DescribeStacks", "NotResource": "arn:aws:cloudformation:*:*:stack/*/*" }] }

The name or the unique stack ID that's associated with the stack, which aren't always interchangeable:

  • Running stacks: You can specify either the stack's name or its unique stack ID.

  • Deleted stacks: You must specify the unique stack ID.

DescribeStacksCommand Output

See DescribeStacksCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
NextToken
string | undefined

If the output exceeds 1 MB in size, a string that identifies the next page of stacks. If no additional page exists, this value is null.

Stacks
Stack[] | undefined

A list of stack structures.

Throws

Name
Fault
Details
CloudFormationServiceException
Base exception class for all service exceptions from CloudFormation service.