AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

AWS CloudFormation Stacks Updates

To update an existing stack, you must submit a template that specifies updates for the properties of resources in the stack. This can be done by using the AWS CloudFormation console, the aws cloudformation update-stack CLI command, or with the UpdateStack API.

When AWS CloudFormation updates a stack, it gets new property settings for the current resources in the stack by using the template that you submit. AWS CloudFormation updates only the resources that have changes specified in the template. If the template includes one or more nested stacks, AWS CloudFormation also initiates an update for every nested stack. This is necessary to determine whether the nested stacks have been modified. AWS CloudFormation updates only those resources in the nested stacks that have changes specified in corresponding templates.

Resources that have not changed run without disruption during the update process. Updates to resources are handled differently depending on the type of resource and, in some cases, depending on the nature of a particular resource property. AWS CloudFormation uses one of the following techniques to update the resource:

  • Update with no interruption. AWS CloudFormation updates the resource without disrupting operation of that resource and without changing the resource's physical name. For example, if you update any properties on an AWS::CloudWatch::Alarm resource, AWS CloudFormation updates the alarm's configuration and, during the update, the alarm's operation continues without disruption.

  • Reconfiguration with some interruption. AWS CloudFormation updates the resource with some interruption. Some resources may experience some interruption during the process of applying property changes to those resources but they will retain their physical names. For example, if you update any properties on an AWS::ElasticLoadBalancing::LoadBalancer resource, there may be some interruption of the LoadBalancer's operation while AWS CloudFormation and Elastic Load Balancing reconfigure the LoadBalancer.

  • Replacement. AWS CloudFormation updates the resource by recreating the resource. Some resources require creating a new resource with the property changes and generating a new physical name. AWS CloudFormation creates the replacement resource first, changes references from other dependent resources to point to the replacement resource, and then deletes the old resource. For example, if you update the Engine property of an AWS::RDS::DBInstance resource, AWS CloudFormation must create a new resource with the specified property changes and replace the current DBInstance resource with the new one.

Important

Whether or not a change in a resource causes an interruption in service depends on the resource itself and on the type of change you're making to it. To learn more about updating a particular resource, see the documentation associated with that resource (for example, the EC2 documentation provides details about what changes will interrupt an EC2 instance) and in the AWS Resource Types Reference, where the effects of updating a resource are listed per property. You should be aware of how each resource change will affect your stack before making a change.

Depending on the technique used to modify each updated resource in your stack, you can make good decisions about when it's best to modify resources to reduce the impact of such changes on your application. In particular, you should plan carefully when resources must be replaced during an update. For example, if you update the Port property of an AWS::RDS::DBInstance resource, AWS CloudFormation will create a new DB Instance with a changed port setting, as well as a new physical name. To plan for this, you should take a snapshot of the current databases, prepare a strategy for how applications using that DB Instance will handle an interruption while the DB Instance is being replaced, ensure that the applications using that DB Instance take into account the new port setting and any other updates you have made, and use the DB snapshot to restore the databases on the new DB instance. This example is not exhaustive: it's meant to give you an idea of the things to plan for when the update technique for a resource is replacement.

Note

You cannot update AWS::S3::Bucket resources, for example, to add or modify tags.

Follow these steps to update a stack and monitor its progress.

Step 1. Get a copy of the template for the stack

The template used to update the stack must contain declarations for all the resources in the existing stack; therefore, you should use the template for the existing stack as a starting point and make your updates to a copy of that template. The first thing you need to do is get a copy of the template for the existing stack.

If you are managing your template in a source control system, use a copy of that template as a starting point. Otherwise, you can get a copy of the template used to create the stack from AWS CloudFormation.

To get the template for a stack from AWS CloudFormation:

AWS Management Console

  1. In the AWS CloudFormation console, click the check box next to the stack you want to update and click the Template tab to view the template.

  2. From the Template, copy the template, paste it into a text file, and save the file. You'll specify your changes to the stack's resources in this file.

CLI

  1. Use the command aws cloudformation get-template to get the template for the stack you want to update.

  2. Copy the template, paste it into a text file, and save the file. Make sure that you copy only the template. The command encloses the template in double quotes—do not copy the double quotes surrounding the template. The template itself starts with an open brace and ends with the final close brace. You'll specify changes to the stack's resources in this file.

Step 2. Update the template

To specify changes to a stack, modify a copy of the stack's template. Currently, you can specify only the following changes in the update template:

  • Add new resources, or remove existing resources.

  • Add, modify, or delete properties of existing resources.

    Information about the effects of updating particular properties for resources is provided in the AWS Resource Types Reference. For each property, the effects of an update will be one of the following:

  • Add, modify, or delete attributes for resources (Metadata, DependsOn, and DeletionPolicy).

  • Add, modify, or delete parameter declarations. However, you cannot add, modify, or delete a parameter that is used by a resource that does not support updates.

  • Add, modify, or delete output value declarations.

  • Add, modify, or delete mapping declarations.

Warning

Changes to DeletionPolicy or output value declarations cannot be updated by themselves. Changes to DeletionPolicy or output value declarations can be made only with changes that add, modify or delete properties of existing resources or that change the resource metadata.

Changing the logical name of a resource is equivalent to deleting that resource and replacing it with a new one. Any other resources that depend on the one being renamed will also need to be updated and may cause them to be replaced.

If your template includes an unsupported change, AWS CloudFormation returns a message that tells you that the change is not permitted. This message may occur asynchronously, however, since resources are created and updated by CloudFormation in a non-deterministic order by default.

You must specify a template containing all the resources from the current stack configuration. Unchanged resources must be specified with the same values as their current stack configuration. The updated resources must be one of the supported resources in the list above. In addition, an updated resource must list all the properties that you want to set on that resource and not just the properties that you want to update.

Some resources or properties may have constraints on property values or changes to those values. For example, changes to the AllocatedStorage property of an AWS::RDS::DBInstance resource must be greater than the current setting and if the value specified for the update does not meet those constraints, the update for that resource will fail. For the specific constraints on AllocatedStorage changes, see ModifyDBInstance.

Updates to a resource can affect the properties of other resources. If you used the Ref function or the Fn::GetAtt function to specify an attribute from an updated resource as part of a property value in another resource in the template, AWS CloudFormation will also update the resource that contains the reference to the property that has changed. For example, if you updated the MasterUsername property of an AWS::RDS::DBInstance resource and you had an AWS::AutoScaling::LaunchConfiguration resource that had a UserData property that contained a reference to the DB Instance name using the Ref function, AWS CloudFormation would recreate the DB Instance with a new name and also update the LaunchConfiguration resource.

To change a template to update a stack

  1. In the template file that you saved in Step 1, modify the template to reflect the changes you want to make to the stack. Make sure you follow the guidelines above.

  2. Save the template file. If you want to specify the template as a URL when you update the stack, upload the update template to an Amazon S3 bucket. Make sure that you use a bucket that is in the same region as the stack you are updating.

Step 3. Update the stack

Updating a stack is similar to creating a stack—you specify a template, parameters, and capabilities for the stack—but there are some differences. The stack retains the original settings for notification, rollback, and timeout settings. Currently, these settings cannot be updated. As we discussed in Step 2, an update template has specific requirements that you need to follow for updates.

There are also some differences between creating and updating parameters. When you update the stack, you can change the parameter values that are used for resources that support updates; however, you must keep the existing values in the current stack for parameters that affect resources that do not support updates. Parameters declared with NoEcho must be re-specified.

To update an existing stack

AWS Management Console

  1. In the AWS CloudFormation console, click the check box next to the stack you want to update and click Update Stack to start the Update Stack Wizard.

  2. Specify the location of the updated template:

    • For a template stored in a file

      Click Upload a Template File. In the box below, enter the location for the template file, or click Browse to navigate to the file and select it, and then click Continue.

    • For a template stored in an Amazon S3 bucket

      Click Provide a Template URL. In the box below, type or paste the URL for the template, and then click Continue.

  3. On the Specify Parameters page, enter or modify the parameter values.

    AWS CloudFormation populates each parameter with the value that is currently set in the stack with the exception of parameters declared with the NoEcho attribute.

    When you have the settings the way you want, click Continue.

  4. If you have IAM resources in the template, check I acknowledge that this template may create IAM resources to specify that you want to go ahead with using IAM resources in the template. For more information about using IAM resources in templates, see Controlling Access with AWS Identity and Access Management.

  5. Review the information for the stack. When you’re satisfied with the settings, click Update Stack, and then click Close. Your stack may take several minutes to update.

CLI

Step 4. Monitor the progress of the stack update

You can monitor the progress of a stack update by viewing the stack's events. The Events tab displays each major step in the creation and update of the stack sorted by the time of each event with latest events on top. The start of the stack update process is marked with an UPDATE_IN_PROGRESS event for the stack:

2011-09-30 09:35 PDT AWS::CloudFormation::Stack MyStack UPDATE_IN_PROGRESS 

Next are events that mark the beginning and completion of the update of each resource that was changed in the update template. For example, updating an AWS::RDS::DBInstance resource named MyDB would result in the following entries:

2011-09-30 09:35 PDT AWS::RDS::DBInstance MyDB UPDATE_COMPLETE
2011-09-30 09:35 PDT AWS::RDS::DBInstance MyDB UPDATE_IN_PROGRESS 

The UPDATE_IN_PROGRESS event is logged when AWS CloudFormation reports that it has begun to update the resource. The UPDATE_COMPLETE event is logged when the resource is successfully created.

When AWS CloudFormation has successfully updated the stack, you will see the following event:

2011-09-30 09:35 PDT AWS::CloudFormation::Stack MyStack UPDATE_COMPLETE 

If an update of a resource fails, AWS CloudFormation reports an UPDATE_FAILED event that includes a reason for the failure. For example, if your update template specified a property change that is not supported by the resource such as reducing the size of AllocatedStorage for an AWS::RDS::DBInstance resource, you would see events like these:

2011-09-30 09:36 PDT AWS::RDS::DBInstance MyDB UPDATE_FAILED Size cannot be less than current size; requested: 5; current: 10
2011-09-30 09:35 PDT AWS::RDS::DBInstance MyDB UPDATE_IN_PROGRESS 

If a resource update fails, AWS CloudFormation rolls back any resources that it has updated during the upgrade to their configurations before the update. Here is an example of the events you would see during an update rollback:

2011-09-30 09:38 PDT AWS::CloudFormation::Stack MyStack UPDATE_ROLLBACK_COMPLETE
2011-09-30 09:38 PDT AWS::RDS::DBInstance MyDB UPDATE_COMPLETE
2011-09-30 09:37 PDT AWS::RDS::DBInstance MyDB UPDATE_IN_PROGRESS
2011-09-30 09:37 PDT AWS::CloudFormation::Stack MyStack UPDATE_ROLLBACK_IN_PROGRESS The following resource(s) failed to update: [MyDB] 

To view stack events

AWS Management Console

  1. In the AWS CloudFormation console, click the check box next to the stack you updated and click Events tab to view the stacks events.

  2. To update the event list with the most recent events, you need to click the Refresh button in the lower pane.

CLI