2017/07/25 - AWS CloudFormation - 13 new 2 updated api methods
Changes AWS CloudFormation StackSets enables you to manage stacks across multiple accounts and regions.
Deletes stack instances for the specified accounts, in the specified regions.
See also: AWS API Documentation
Request Syntax
client.delete_stack_instances(
StackSetName='string',
Accounts=[
'string',
],
Regions=[
'string',
],
OperationPreferences={
'RegionOrder': [
'string',
],
'FailureToleranceCount': 123,
'FailureTolerancePercentage': 123,
'MaxConcurrentCount': 123,
'MaxConcurrentPercentage': 123
},
RetainStacks=True|False,
OperationId='string'
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to delete stack instances for.
list
[REQUIRED]
The names of the AWS accounts that you want to delete stack instances for.
(string) --
list
[REQUIRED]
The regions where you want to delete stack set instances.
(string) --
dict
Preferences for how AWS CloudFormation performs this stack set operation.
RegionOrder (list) --
The order of the regions in where you want to perform the stack operation.
(string) --
FailureToleranceCount (integer) --
The number of accounts, per region, for which this operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage (but not both).
FailureTolerancePercentage (integer) --
The percentage of accounts, per region, for which this stack operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage , but not both.
MaxConcurrentCount (integer) --
The maximum number of accounts in which to perform this operation at one time. This is dependent on the value of FailureToleranceCount — MaxConcurrentCount is at most one more than the FailureToleranceCount .
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
MaxConcurrentPercentage (integer) --
The maximum percentage of accounts in which to perform this operation at one time.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number. This is true except in cases where rounding down would result is zero. In this case, CloudFormation sets the number as one instead.
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
boolean
[REQUIRED]
Removes the stack instances from the specified stack set, but doesn't delete the stacks. You can't reassociate a retained stack or add an existing, saved stack to a new stack set.
string
The unique identifier for this stack set operation.
If you don't specify an operation ID, the SDK generates one automatically.
The operation ID also functions as an idempotency token, to ensure that AWS CloudFormation performs the stack set operation only once, even if you retry the request multiple times. You can retry stack set operation requests to ensure that AWS CloudFormation successfully received them.
Repeating this stack set operation with a new operation ID retries all stack instances whose status is OUTDATED .
This field is autopopulated if not provided.
dict
Response Syntax
{
'OperationId': 'string'
}
Response Structure
(dict) --
OperationId (string) --
The unique identifier for this stack set operation.
Returns the description of the specified stack set operation.
See also: AWS API Documentation
Request Syntax
client.describe_stack_set_operation(
StackSetName='string',
OperationId='string'
)
string
[REQUIRED]
The name or the unique stack ID of the stack set for the stack operation.
string
[REQUIRED]
The unique ID of the stack set operation.
dict
Response Syntax
{
'StackSetOperation': {
'OperationId': 'string',
'StackSetId': 'string',
'Action': 'CREATE'|'UPDATE'|'DELETE',
'Status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'STOPPING'|'STOPPED',
'OperationPreferences': {
'RegionOrder': [
'string',
],
'FailureToleranceCount': 123,
'FailureTolerancePercentage': 123,
'MaxConcurrentCount': 123,
'MaxConcurrentPercentage': 123
},
'RetainStacks': True|False,
'CreationTimestamp': datetime(2015, 1, 1),
'EndTimestamp': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
StackSetOperation (dict) --
The specified stack set operation.
OperationId (string) --
The unique ID of a stack set operation.
StackSetId (string) --
The ID of the stack set.
Action (string) --
The type of stack set operation: CREATE , UPDATE , or DELETE . Create and delete operations affect only the specified stack set instances that are associated with the specified stack set. Update operations affect both the stack set itself, as well as all associated stack set instances.
Status (string) --
The status of the operation.
FAILED : The operation exceeded the specified failure tolerance. The failure tolerance value that you've set for an operation is applied for each region during stack create and update operations. If the number of failed stacks within a region exceeds the failure tolerance, the status of the operation in the region is set to FAILED . This in turn sets the status of the operation as a whole to FAILED , and AWS CloudFormation cancels the operation in any remaining regions.
RUNNING : The operation is currently being performed.
STOPPED : The user has cancelled the operation.
STOPPING : The operation is in the process of stopping, at user request.
SUCCEEDED : The operation completed creating or updating all the specified stacks without exceeding the failure tolerance for the operation.
OperationPreferences (dict) --
The preferences for how AWS CloudFormation performs this stack set operation.
RegionOrder (list) --
The order of the regions in where you want to perform the stack operation.
(string) --
FailureToleranceCount (integer) --
The number of accounts, per region, for which this operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage (but not both).
FailureTolerancePercentage (integer) --
The percentage of accounts, per region, for which this stack operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage , but not both.
MaxConcurrentCount (integer) --
The maximum number of accounts in which to perform this operation at one time. This is dependent on the value of FailureToleranceCount — MaxConcurrentCount is at most one more than the FailureToleranceCount .
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
MaxConcurrentPercentage (integer) --
The maximum percentage of accounts in which to perform this operation at one time.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number. This is true except in cases where rounding down would result is zero. In this case, CloudFormation sets the number as one instead.
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
RetainStacks (boolean) --
For stack set operations of action type DELETE , specifies whether to remove the stack instances from the specified stack set, but doesn't delete the stacks. You can't reassociate a retained stack, or add an existing, saved stack to a new stack set.
CreationTimestamp (datetime) --
The time at which the operation was initiated. Note that the creation times for the stack set operation might differ from the creation time of the individual stacks themselves. This is because AWS CloudFormation needs to perform preparatory work for the operation, such as dispatching the work to the requested regions, before actually creating the first stacks.
EndTimestamp (datetime) --
The time at which the stack set operation ended, across all accounts and regions specified. Note that this doesn't necessarily mean that the stack set operation was successful, or even attempted, in each account or region.
Creates stack instances for the specified accounts, within the specified regions. A stack instance refers to a stack in a specific account and region. Accounts and Regions are required parameters—you must specify at least one account and one region.
See also: AWS API Documentation
Request Syntax
client.create_stack_instances(
StackSetName='string',
Accounts=[
'string',
],
Regions=[
'string',
],
OperationPreferences={
'RegionOrder': [
'string',
],
'FailureToleranceCount': 123,
'FailureTolerancePercentage': 123,
'MaxConcurrentCount': 123,
'MaxConcurrentPercentage': 123
},
OperationId='string'
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to create stack instances from.
list
[REQUIRED]
The names of one or more AWS accounts that you want to create stack instances in the specified region(s) for.
(string) --
list
[REQUIRED]
The names of one or more regions where you want to create stack instances using the specified AWS account(s).
(string) --
dict
Preferences for how AWS CloudFormation performs this stack set operation.
RegionOrder (list) --
The order of the regions in where you want to perform the stack operation.
(string) --
FailureToleranceCount (integer) --
The number of accounts, per region, for which this operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage (but not both).
FailureTolerancePercentage (integer) --
The percentage of accounts, per region, for which this stack operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage , but not both.
MaxConcurrentCount (integer) --
The maximum number of accounts in which to perform this operation at one time. This is dependent on the value of FailureToleranceCount — MaxConcurrentCount is at most one more than the FailureToleranceCount .
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
MaxConcurrentPercentage (integer) --
The maximum percentage of accounts in which to perform this operation at one time.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number. This is true except in cases where rounding down would result is zero. In this case, CloudFormation sets the number as one instead.
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
string
The unique identifier for this stack set operation.
The operation ID also functions as an idempotency token, to ensure that AWS CloudFormation performs the stack set operation only once, even if you retry the request multiple times. You might retry stack set operation requests to ensure that AWS CloudFormation successfully received them.
If you don't specify an operation ID, the SDK generates one automatically.
Repeating this stack set operation with a new operation ID retries all stack instances whose status is OUTDATED .
This field is autopopulated if not provided.
dict
Response Syntax
{
'OperationId': 'string'
}
Response Structure
(dict) --
OperationId (string) --
The unique identifier for this stack set operation.
Returns summary information about stack instances that are associated with the specified stack set. You can filter for stack instances that are associated with a specific AWS account name or region.
See also: AWS API Documentation
Request Syntax
client.list_stack_instances(
StackSetName='string',
NextToken='string',
MaxResults=123,
StackInstanceAccount='string',
StackInstanceRegion='string'
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to list stack instances for.
string
If the previous request didn't return all of the remaining results, the response's NextToken parameter value is set to a token. To retrieve the next set of results, call ListStackInstances again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
string
The name of the AWS account that you want to list stack instances for.
string
The name of the region where you want to list stack instances.
dict
Response Syntax
{
'Summaries': [
{
'StackSetId': 'string',
'Region': 'string',
'Account': 'string',
'StackId': 'string',
'Status': 'CURRENT'|'OUTDATED'|'INOPERABLE',
'StatusReason': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Summaries (list) --
A list of StackInstanceSummary structures that contain information about the specified stack instances.
(dict) --
The structure that contains summary information about a stack instance.
StackSetId (string) --
The name or unique ID of the stack set that the stack instance is associated with.
Region (string) --
The name of the AWS region that the stack instance is associated with.
Account (string) --
The name of the AWS account that the stack instance is associated with.
StackId (string) --
The ID of the stack instance.
Status (string) --
The status of the stack instance, in terms of its synchronization with its associated stack set.
INOPERABLE : A DeleteStackInstances operation has failed and left the stack in an unstable state. Stacks in this state are excluded from further UpdateStackSet and DeleteStackInstances operations. You might need to clean up the stack manually.
OUTDATED : The stack isn't currently up to date with the stack set because:
The associated stack failed during a CreateStackSet or UpdateStackSet operation.
The stack was part of a CreateStackSet or UpdateStackSet operation that failed or was stopped before the stack was created or updated.
CURRENT : The stack is currently up to date with the stack set.
StatusReason (string) --
The explanation for the specific status code assigned to this stack instance.
NextToken (string) --
If the request doesn't return all of the remaining results, NextToken is set to a token. To retrieve the next set of results, call ListStackInstances again and assign that token to the request object's NextToken parameter. If the request returns all results, NextToken is set to null .
Returns the stack instance that's associated with the specified stack set, AWS account, and region.
For a list of stack instances that are associated with a specific stack set, use ListStackInstances.
See also: AWS API Documentation
Request Syntax
client.describe_stack_instance(
StackSetName='string',
StackInstanceAccount='string',
StackInstanceRegion='string'
)
string
[REQUIRED]
The name or the unique stack ID of the stack set that you want to get stack instance information for.
string
[REQUIRED]
The ID of an AWS account that's associated with this stack instance.
string
[REQUIRED]
The name of a region that's associated with this stack instance.
dict
Response Syntax
{
'StackInstance': {
'StackSetId': 'string',
'Region': 'string',
'Account': 'string',
'StackId': 'string',
'Status': 'CURRENT'|'OUTDATED'|'INOPERABLE',
'StatusReason': 'string'
}
}
Response Structure
(dict) --
StackInstance (dict) --
The stack instance that matches the specified request parameters.
StackSetId (string) --
The name or unique ID of the stack set that the stack instance is associated with.
Region (string) --
The name of the AWS region that the stack instance is associated with.
Account (string) --
The name of the AWS account that the stack instance is associated with.
StackId (string) --
The ID of the stack instance.
Status (string) --
The status of the stack instance, in terms of its synchronization with its associated stack set.
INOPERABLE : A DeleteStackInstances operation has failed and left the stack in an unstable state. Stacks in this state are excluded from further UpdateStackSet and DeleteStackInstances operations. You might need to clean up the stack manually.
OUTDATED : The stack isn't currently up to date with the stack set because:
The associated stack failed during a CreateStackSet or UpdateStackSet operation.
The stack was part of a CreateStackSet or UpdateStackSet operation that failed or was stopped before the stack was created or updated.
CURRENT : The stack is currently up to date with the stack set.
StatusReason (string) --
The explanation for the specific status code that is assigned to this stack instance.
Returns summary information about the results of a stack set operation.
See also: AWS API Documentation
Request Syntax
client.list_stack_set_operation_results(
StackSetName='string',
OperationId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to get operation results for.
string
[REQUIRED]
The ID of the stack set operation.
string
If the previous request didn't return all of the remaining results, the response object's NextToken parameter value is set to a token. To retrieve the next set of results, call ListStackSetOperationResults again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
dict
Response Syntax
{
'Summaries': [
{
'Account': 'string',
'Region': 'string',
'Status': 'PENDING'|'RUNNING'|'SUCCEEDED'|'FAILED'|'CANCELLED',
'StatusReason': 'string',
'AccountGateResult': {
'Status': 'SUCCEEDED'|'FAILED'|'SKIPPED',
'StatusReason': 'string'
}
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Summaries (list) --
A list of StackSetOperationResultSummary structures that contain information about the specified operation results, for accounts and regions that are included in the operation.
(dict) --
The structure that contains information about a specified operation's results for a given account in a given region.
Account (string) --
The name of the AWS account for this operation result.
Region (string) --
The name of the AWS region for this operation result.
Status (string) --
The result status of the stack set operation for the given account in the given region.
CANCELLED : The operation in the specified account and region has been cancelled. This is either because a user has stopped the stack set operation, or because the failure tolerance of the stack set operation has been exceeded.
FAILED : The operation in the specified account and region failed. If the stack set operation fails in enough accounts within a region, the failure tolerance for the stack set operation as a whole might be exceeded.
RUNNING : The operation in the specified account and region is currently in progress.
PENDING : The operation in the specified account and region has yet to start.
SUCCEEDED : The operation in the specified account and region completed successfully.
StatusReason (string) --
The reason for the assigned result status.
AccountGateResult (dict) --
The results of the account gate function AWS CloudFormation invokes, if present, before proceeding with stack set operations in an account
Status (string) --
The status of the account gate function.
SUCCEEDED : The account gate function has determined that the account passes any requirements for stack set operations to occur. AWS CloudFormation proceeds with stack operations in the account.
FAILED : The account gate function has determined that the account does not meet the requirements for stack set operations to occur. AWS CloudFormation cancels the stack set operations in that account, and the stack set operation status is set to FAILED.
SKIPPED : An account gate function has not been specified for the account, or the AWSCloudFormationStackSetExecutionRole of the stack set adminstration account lacks permissions to invoke the function. AWS CloudFormation proceeds with stack set operations in the account.
StatusReason (string) --
The reason for the account gate status assigned to this account.
NextToken (string) --
If the request doesn't return all results, NextToken is set to a token. To retrieve the next set of results, call ListOperationResults again and assign that token to the request object's NextToken parameter. If there are no remaining results, NextToken is set to null .
Returns the description of the specified stack set.
See also: AWS API Documentation
Request Syntax
client.describe_stack_set(
StackSetName='string'
)
string
[REQUIRED]
The name or unique ID of the stack set whose description you want.
dict
Response Syntax
{
'StackSet': {
'StackSetName': 'string',
'StackSetId': 'string',
'Description': 'string',
'Status': 'ACTIVE'|'DELETED',
'TemplateBody': 'string',
'Parameters': [
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
'Capabilities': [
'CAPABILITY_IAM'|'CAPABILITY_NAMED_IAM',
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
}
}
Response Structure
(dict) --
StackSet (dict) --
The specified stack set.
StackSetName (string) --
The name that's associated with the stack set.
StackSetId (string) --
The ID of the stack set.
Description (string) --
A description of the stack set that you specify when the stack set is created or updated.
Status (string) --
The status of the stack set.
TemplateBody (string) --
The structure that contains the body of the template that was used to create or update the stack set.
Parameters (list) --
A list of input parameters for a stack set.
(dict) --
The Parameter data type.
ParameterKey (string) --
The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.
ParameterValue (string) --
The value associated with the parameter.
UsePreviousValue (boolean) --
During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.
Capabilities (list) --
The capabilities that are allowed in the stack set. Some stack set templates might include resources that can affect permissions in your AWS account—for example, by creating new AWS Identity and Access Management (IAM) users. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.
(string) --
Tags (list) --
A list of tags that specify information about the stack set. A maximum number of 50 tags can be specified.
(dict) --
The Tag type enables you to specify a key-value pair that can be used to store information about an AWS CloudFormation stack.
Key (string) --
Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .
Value (string) --
Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.
Deletes a stack set. Before you can delete a stack set, all of its member stack instances must be deleted. For more information about how to do this, see DeleteStackInstances.
See also: AWS API Documentation
Request Syntax
client.delete_stack_set(
StackSetName='string'
)
string
[REQUIRED]
The name or unique ID of the stack set that you're deleting. You can obtain this value by running ListStackSets.
dict
Response Syntax
{}
Response Structure
(dict) --
Creates a stack set.
See also: AWS API Documentation
Request Syntax
client.create_stack_set(
StackSetName='string',
Description='string',
TemplateBody='string',
TemplateURL='string',
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
Capabilities=[
'CAPABILITY_IAM'|'CAPABILITY_NAMED_IAM',
],
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
ClientRequestToken='string'
)
string
[REQUIRED]
The name to associate with the stack set. The name must be unique in the region where you create your stack set.
Note
A stack name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.
string
A description of the stack set. You can use the description to identify the stack set's purpose or other important information.
string
The structure that contains the template body, with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information, see Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.
string
The location of the file that contains the template body. The URL must point to a template (maximum size: 460,800 bytes) that's located in an Amazon S3 bucket. For more information, see Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify either the TemplateBody or the TemplateURL parameter, but not both.
list
The input parameters for the stack set template.
(dict) --
The Parameter data type.
ParameterKey (string) --
The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.
ParameterValue (string) --
The value associated with the parameter.
UsePreviousValue (boolean) --
During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.
list
A list of values that you must specify before AWS CloudFormation can create certain stack sets. Some stack set templates might include resources that can affect permissions in your AWS account—for example, by creating new AWS Identity and Access Management (IAM) users. For those stack sets, you must explicitly acknowledge their capabilities by specifying this parameter.
The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM. The following resources require you to specify this parameter:
AWS::IAM::AccessKey
AWS::IAM::Group
AWS::IAM::InstanceProfile
AWS::IAM::Policy
AWS::IAM::Role
AWS::IAM::User
AWS::IAM::UserToGroupAddition
If your stack template contains these resources, we recommend that you review all permissions that are associated with them and edit their permissions if necessary.
If you have IAM resources, you can specify either capability. If you have IAM resources with custom names, you must specify CAPABILITY_NAMED_IAM. If you don't specify this parameter, this action returns an InsufficientCapabilities error.
For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.
(string) --
list
The key-value pairs to associate with this stack set and the stacks created from it. AWS CloudFormation also propagates these tags to supported resources that are created in the stacks. A maximum number of 50 tags can be specified.
If you specify tags as part of a CreateStackSet action, AWS CloudFormation checks to see if you have the required IAM permission to tag resources. If you don't, the entire CreateStackSet action fails with an access denied error, and the stack set is not created.
(dict) --
The Tag type enables you to specify a key-value pair that can be used to store information about an AWS CloudFormation stack.
Key (string) -- [REQUIRED]
Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .
Value (string) -- [REQUIRED]
Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.
string
A unique identifier for this CreateStackSet request. Specify this token if you plan to retry requests so that AWS CloudFormation knows that you're not attempting to create another stack set with the same name. You might retry CreateStackSet requests to ensure that AWS CloudFormation successfully received them.
If you don't specify an operation ID, the SDK generates one automatically.
This field is autopopulated if not provided.
dict
Response Syntax
{
'StackSetId': 'string'
}
Response Structure
(dict) --
StackSetId (string) --
The ID of the stack set that you're creating.
Updates the stack set and all associated stack instances.
Even if the stack set operation created by updating the stack set fails (completely or partially, below or above a specified failure tolerance), the stack set is updated with your changes. Subsequent CreateStackInstances calls on the specified stack set use the updated stack set.
See also: AWS API Documentation
Request Syntax
client.update_stack_set(
StackSetName='string',
Description='string',
TemplateBody='string',
TemplateURL='string',
UsePreviousTemplate=True|False,
Parameters=[
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
Capabilities=[
'CAPABILITY_IAM'|'CAPABILITY_NAMED_IAM',
],
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
OperationPreferences={
'RegionOrder': [
'string',
],
'FailureToleranceCount': 123,
'FailureTolerancePercentage': 123,
'MaxConcurrentCount': 123,
'MaxConcurrentPercentage': 123
},
OperationId='string'
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to update.
string
A brief description of updates that you are making.
string
The structure that contains the template body, with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information, see Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify only one of the following parameters: TemplateBody or TemplateURL —or set UsePreviousTemplate to true.
string
The location of the file that contains the template body. The URL must point to a template (maximum size: 460,800 bytes) that is located in an Amazon S3 bucket. For more information, see Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify only one of the following parameters: TemplateBody or TemplateURL —or set UsePreviousTemplate to true.
boolean
Use the existing template that's associated with the stack set that you're updating.
Conditional: You must specify only one of the following parameters: TemplateBody or TemplateURL —or set UsePreviousTemplate to true.
list
A list of input parameters for the stack set template.
(dict) --
The Parameter data type.
ParameterKey (string) --
The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.
ParameterValue (string) --
The value associated with the parameter.
UsePreviousValue (boolean) --
During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.
list
A list of values that you must specify before AWS CloudFormation can create certain stack sets. Some stack set templates might include resources that can affect permissions in your AWS account—for example, by creating new AWS Identity and Access Management (IAM) users. For those stack sets, you must explicitly acknowledge their capabilities by specifying this parameter.
The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM. The following resources require you to specify this parameter:
AWS::IAM::AccessKey
AWS::IAM::Group
AWS::IAM::InstanceProfile
AWS::IAM::Policy
AWS::IAM::Role
AWS::IAM::User
AWS::IAM::UserToGroupAddition
If your stack template contains these resources, we recommend that you review all permissions that are associated with them and edit their permissions if necessary.
If you have IAM resources, you can specify either capability. If you have IAM resources with custom names, you must specify CAPABILITY_NAMED_IAM. If you don't specify this parameter, this action returns an InsufficientCapabilities error.
For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.
(string) --
list
The key-value pairs to associate with this stack set and the stacks created from it. AWS CloudFormation also propagates these tags to supported resources that are created in the stacks. You can specify a maximum number of 50 tags.
If you specify tags for this parameter, those tags replace any list of tags that are currently associated with this stack set. This means:
If you don't specify this parameter, AWS CloudFormation doesn't modify the stack's tags.
If you specify any tags using this parameter, you must specify all the tags that you want associated with this stack set, even tags you've specifed before (for example, when creating the stack set or during a previous update of the stack set.). Any tags that you don't include in the updated list of tags are removed from the stack set, and therefore from the stacks and resources as well.
If you specify an empty value, AWS CloudFormation removes all currently associated tags.
If you specify new tags as part of an UpdateStackSet action, AWS CloudFormation checks to see if you have the required IAM permission to tag resources. If you omit tags that are currently associated with the stack set from the list of tags you specify, AWS CloudFormation assumes that you want to remove those tags from the stack set, and checks to see if you have permission to untag resources. If you don't have the necessary permission(s), the entire UpdateStackSet action fails with an access denied error, and the stack set is not updated.
(dict) --
The Tag type enables you to specify a key-value pair that can be used to store information about an AWS CloudFormation stack.
Key (string) -- [REQUIRED]
Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .
Value (string) -- [REQUIRED]
Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.
dict
Preferences for how AWS CloudFormation performs this stack set operation.
RegionOrder (list) --
The order of the regions in where you want to perform the stack operation.
(string) --
FailureToleranceCount (integer) --
The number of accounts, per region, for which this operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage (but not both).
FailureTolerancePercentage (integer) --
The percentage of accounts, per region, for which this stack operation can fail before AWS CloudFormation stops the operation in that region. If the operation is stopped in a region, AWS CloudFormation doesn't attempt the operation in any subsequent regions.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number.
Conditional: You must specify either FailureToleranceCount or FailureTolerancePercentage , but not both.
MaxConcurrentCount (integer) --
The maximum number of accounts in which to perform this operation at one time. This is dependent on the value of FailureToleranceCount — MaxConcurrentCount is at most one more than the FailureToleranceCount .
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
MaxConcurrentPercentage (integer) --
The maximum percentage of accounts in which to perform this operation at one time.
When calculating the number of accounts based on the specified percentage, AWS CloudFormation rounds down to the next whole number. This is true except in cases where rounding down would result is zero. In this case, CloudFormation sets the number as one instead.
Conditional: You must specify either MaxConcurrentCount or MaxConcurrentPercentage , but not both.
string
The unique ID for this stack set operation.
The operation ID also functions as an idempotency token, to ensure that AWS CloudFormation performs the stack set operation only once, even if you retry the request multiple times. You might retry stack set operation requests to ensure that AWS CloudFormation successfully received them.
If you don't specify an operation ID, AWS CloudFormation generates one automatically.
Repeating this stack set operation with a new operation ID retries all stack instances whose status is OUTDATED .
This field is autopopulated if not provided.
dict
Response Syntax
{
'OperationId': 'string'
}
Response Structure
(dict) --
OperationId (string) --
The unique ID for this stack set operation.
Returns summary information about operations performed on a stack set.
See also: AWS API Documentation
Request Syntax
client.list_stack_set_operations(
StackSetName='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to get operation summaries for.
string
If the previous paginated request didn't return all of the remaining results, the response object's NextToken parameter value is set to a token. To retrieve the next set of results, call ListStackSetOperations again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
dict
Response Syntax
{
'Summaries': [
{
'OperationId': 'string',
'Action': 'CREATE'|'UPDATE'|'DELETE',
'Status': 'RUNNING'|'SUCCEEDED'|'FAILED'|'STOPPING'|'STOPPED',
'CreationTimestamp': datetime(2015, 1, 1),
'EndTimestamp': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Summaries (list) --
A list of StackSetOperationSummary structures that contain summary information about operations for the specified stack set.
(dict) --
The structures that contain summary information about the specified operation.
OperationId (string) --
The unique ID of the stack set operation.
Action (string) --
The type of operation: CREATE , UPDATE , or DELETE . Create and delete operations affect only the specified stack instances that are associated with the specified stack set. Update operations affect both the stack set itself as well as all associated stack set instances.
Status (string) --
The overall status of the operation.
FAILED : The operation exceeded the specified failure tolerance. The failure tolerance value that you've set for an operation is applied for each region during stack create and update operations. If the number of failed stacks within a region exceeds the failure tolerance, the status of the operation in the region is set to FAILED . This in turn sets the status of the operation as a whole to FAILED , and AWS CloudFormation cancels the operation in any remaining regions.
RUNNING : The operation is currently being performed.
STOPPED : The user has cancelled the operation.
STOPPING : The operation is in the process of stopping, at user request.
SUCCEEDED : The operation completed creating or updating all the specified stacks without exceeding the failure tolerance for the operation.
CreationTimestamp (datetime) --
The time at which the operation was initiated. Note that the creation times for the stack set operation might differ from the creation time of the individual stacks themselves. This is because AWS CloudFormation needs to perform preparatory work for the operation, such as dispatching the work to the requested regions, before actually creating the first stacks.
EndTimestamp (datetime) --
The time at which the stack set operation ended, across all accounts and regions specified. Note that this doesn't necessarily mean that the stack set operation was successful, or even attempted, in each account or region.
NextToken (string) --
If the request doesn't return all results, NextToken is set to a token. To retrieve the next set of results, call ListOperationResults again and assign that token to the request object's NextToken parameter. If there are no remaining results, NextToken is set to null .
Returns summary information about stack sets that are associated with the user.
See also: AWS API Documentation
Request Syntax
client.list_stack_sets(
NextToken='string',
MaxResults=123,
Status='ACTIVE'|'DELETED'
)
string
If the previous paginated request didn't return all of the remaining results, the response object's NextToken parameter value is set to a token. To retrieve the next set of results, call ListStackSets again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
string
The status of the stack sets that you want to get summary information about.
dict
Response Syntax
{
'Summaries': [
{
'StackSetName': 'string',
'StackSetId': 'string',
'Description': 'string',
'Status': 'ACTIVE'|'DELETED'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Summaries (list) --
A list of StackSetSummary structures that contain information about the user's stack sets.
(dict) --
The structures that contain summary information about the specified stack set.
StackSetName (string) --
The name of the stack set.
StackSetId (string) --
The ID of the stack set.
Description (string) --
A description of the stack set that you specify when the stack set is created or updated.
Status (string) --
The status of the stack set.
NextToken (string) --
If the request doesn't return all of the remaining results, NextToken is set to a token. To retrieve the next set of results, call ListStackInstances again and assign that token to the request object's NextToken parameter. If the request returns all results, NextToken is set to null .
Stops an in-progress operation on a stack set and its associated stack instances.
See also: AWS API Documentation
Request Syntax
client.stop_stack_set_operation(
StackSetName='string',
OperationId='string'
)
string
[REQUIRED]
The name or unique ID of the stack set that you want to stop the operation for.
string
[REQUIRED]
The ID of the stack operation.
dict
Response Syntax
{}
Response Structure
(dict) --
{'Stacks': {'Outputs': {'ExportName': 'string'}}}
Returns the description for the specified stack; if no stack name was specified, then it returns the description for all the stacks created.
Note
If the stack does not exist, an AmazonCloudFormationException is returned.
See also: AWS API Documentation
Request Syntax
client.describe_stacks(
StackName='string',
NextToken='string'
)
string
The name or the unique stack ID that is associated with the stack, which are not 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.
Default: There is no default value.
string
A string that identifies the next page of stacks that you want to retrieve.
dict
Response Syntax
{
'Stacks': [
{
'StackId': 'string',
'StackName': 'string',
'ChangeSetId': 'string',
'Description': 'string',
'Parameters': [
{
'ParameterKey': 'string',
'ParameterValue': 'string',
'UsePreviousValue': True|False
},
],
'CreationTime': datetime(2015, 1, 1),
'LastUpdatedTime': datetime(2015, 1, 1),
'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_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_FAILED'|'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE'|'REVIEW_IN_PROGRESS',
'StackStatusReason': 'string',
'DisableRollback': True|False,
'NotificationARNs': [
'string',
],
'TimeoutInMinutes': 123,
'Capabilities': [
'CAPABILITY_IAM'|'CAPABILITY_NAMED_IAM',
],
'Outputs': [
{
'OutputKey': 'string',
'OutputValue': 'string',
'Description': 'string',
'ExportName': 'string'
},
],
'RoleARN': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
The output for a DescribeStacks action.
Stacks (list) --
A list of stack structures.
(dict) --
The Stack data type.
StackId (string) --
Unique identifier of the stack.
StackName (string) --
The name associated with the stack.
ChangeSetId (string) --
The unique ID of the change set.
Description (string) --
A user-defined description associated with the stack.
Parameters (list) --
A list of Parameter structures.
(dict) --
The Parameter data type.
ParameterKey (string) --
The key associated with the parameter. If you don't specify a key and value for a particular parameter, AWS CloudFormation uses the default value that is specified in your template.
ParameterValue (string) --
The value associated with the parameter.
UsePreviousValue (boolean) --
During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify true , do not specify a parameter value.
CreationTime (datetime) --
The time at which the stack was created.
LastUpdatedTime (datetime) --
The time the stack was last updated. This field will only be returned if the stack has been updated at least once.
StackStatus (string) --
Current status of the stack.
StackStatusReason (string) --
Success/failure message associated with the stack status.
DisableRollback (boolean) --
Boolean to enable or disable rollback on stack creation failures:
true : disable rollback
false : enable rollback
NotificationARNs (list) --
SNS topic ARNs to which stack related events are published.
(string) --
TimeoutInMinutes (integer) --
The amount of time within which stack creation should complete.
Capabilities (list) --
The capabilities allowed in the stack.
(string) --
Outputs (list) --
A list of output structures.
(dict) --
The Output data type.
OutputKey (string) --
The key associated with the output.
OutputValue (string) --
The value associated with the output.
Description (string) --
User defined description associated with the output.
ExportName (string) --
The name of the export associated with the output.
RoleARN (string) --
The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that is associated with the stack. During a stack operation, AWS CloudFormation uses this role's credentials to make calls on your behalf.
Tags (list) --
A list of Tag s that specify information about the stack.
(dict) --
The Tag type enables you to specify a key-value pair that can be used to store information about an AWS CloudFormation stack.
Key (string) --
Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (AWS) have the reserved prefix: aws: .
Value (string) --
Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.
NextToken (string) --
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.
{'StackSetName': 'string'}
Returns information about a new or existing template. The GetTemplateSummary action is useful for viewing parameter information, such as default parameter values and parameter types, before you create or update a stack.
You can use the GetTemplateSummary action when you submit a template, or you can get template information for a running or deleted stack.
For deleted stacks, GetTemplateSummary returns the template information for up to 90 days after the stack has been deleted. If the template does not exist, a ValidationError is returned.
See also: AWS API Documentation
Request Syntax
client.get_template_summary(
TemplateBody='string',
TemplateURL='string',
StackName='string',
StackSetName='string'
)
string
Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information about templates, see Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify only one of the following parameters: StackName , TemplateBody , or TemplateURL .
string
Location of file containing the template body. The URL must point to a template (max size: 460,800 bytes) that is located in an Amazon S3 bucket. For more information about templates, see Template Anatomy in the AWS CloudFormation User Guide.
Conditional: You must specify only one of the following parameters: StackName , TemplateBody , or TemplateURL .
string
The name or the stack ID that is associated with the stack, which are not always interchangeable. For running stacks, you can specify either the stack's name or its unique stack ID. For deleted stack, you must specify the unique stack ID.
Conditional: You must specify only one of the following parameters: StackName , TemplateBody , or TemplateURL .
string
The name or unique ID of the stack set from which the stack was created.
dict
Response Syntax
{
'Parameters': [
{
'ParameterKey': 'string',
'DefaultValue': 'string',
'ParameterType': 'string',
'NoEcho': True|False,
'Description': 'string',
'ParameterConstraints': {
'AllowedValues': [
'string',
]
}
},
],
'Description': 'string',
'Capabilities': [
'CAPABILITY_IAM'|'CAPABILITY_NAMED_IAM',
],
'CapabilitiesReason': 'string',
'ResourceTypes': [
'string',
],
'Version': 'string',
'Metadata': 'string',
'DeclaredTransforms': [
'string',
]
}
Response Structure
(dict) --
The output for the GetTemplateSummary action.
Parameters (list) --
A list of parameter declarations that describe various properties for each parameter.
(dict) --
The ParameterDeclaration data type.
ParameterKey (string) --
The name that is associated with the parameter.
DefaultValue (string) --
The default value of the parameter.
ParameterType (string) --
The type of parameter.
NoEcho (boolean) --
Flag that indicates whether the parameter value is shown as plain text in logs and in the AWS Management Console.
Description (string) --
The description that is associate with the parameter.
ParameterConstraints (dict) --
The criteria that AWS CloudFormation uses to validate parameter values.
AllowedValues (list) --
A list of values that are permitted for a parameter.
(string) --
Description (string) --
The value that is defined in the Description property of the template.
Capabilities (list) --
The capabilities found within the template. If your template contains IAM resources, you must specify the CAPABILITY_IAM or CAPABILITY_NAMED_IAM value for this parameter when you use the CreateStack or UpdateStack actions with your template; otherwise, those actions return an InsufficientCapabilities error.
For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.
(string) --
CapabilitiesReason (string) --
The list of resources that generated the values in the Capabilities response element.
ResourceTypes (list) --
A list of all the template resource types that are defined in the template, such as AWS::EC2::Instance , AWS::Dynamo::Table , and Custom::MyCustomInstance .
(string) --
Version (string) --
The AWS template format version, which identifies the capabilities of the template.
Metadata (string) --
The value that is defined for the Metadata property of the template.
DeclaredTransforms (list) --
A list of the transforms that are declared in the template.
(string) --