Updating and existing CloudFormation

At times, we will release new versions of Symbee Connect CloudFormations. Any time an updated CloudFormation becomes available, we list it in our release notes. We take the same approach with CloudFormation updates as we do with all our releases and avoid "breaking" changes. But it may be necessary for you to take a CloudFormation update to access or use new features, or receive a fix that has been identified.

The steps in this section guide you through downloading and updating an existing CloudFormation template you have previously deployed.

How AWS CloudFormation updates work

This description is simply an overview of the essentials of how CloudFormation updates work, as it can be helpful to understand what's happening when you perform a CloudFormation update. For complete details, refer to the formal AWS documentation here.

A CloudFormation script (either in YAML or JSON format - we publish all ours in YAML format) is essentially a template describing a list of resources required to be deployed (referred to as a "stack"). It is not really a list of steps of how those resources are deployed, but rather an itemized list of resources (and their required configuration) that is expected to be present once a CloudFormation stack deploy is complete. The AWS CloudFormation service handles how these objects are created, and in what order based on dependencies.

CloudFormation templates can have Parameters you are prompted to input when deploying (or updating) the CloudFormation. Those parameters often then govern which resources a CloudFormation deploys.

When you run (deploy) a CloudFormation template the first time with certain input parameter values, AWS CloudFormation will determine which resources need to be deployed and how they should be configured.

When you perform an update of a CloudFormation stack (even if you don't replace/update the version of the CloudFormation template the stack is using), changing the values of the input parameters results in AWS CloudFormation re-assessing what resources were previously deployed (the last time the stack was created or updated) against what resources should be deployed as a result of your new parameter values. The end result is a "change set". AWS CloudFormation then applies the change set, which can potentially result in previous resources being undeployed (destroyed) as they are no longer required, new resources getting created based (based on the latest parameter selections), and/or existing resources getting re-configured.

CloudFormation Update Steps

Follow the steps below to update one of your already deployed Symbee Connect CloudFormation stacks with the latest release:

1. Log into your Symbee Connect Administration Portal.
2. If you have more than one Environment configured within your Company in Symbee Connect, on the top Navigation bar, ensure you select the appropriate Environment you wish to configure for Audit History streaming before downloading any CloudFormation script.
3. Then click on the main Function menu in the top navigation bar, and click on Feature Integrations (CloudFormations) in the Company Environment Configuration section.
4. From the Feature Integrations (AWS CloudFormations) page, find the link to the CloudFormation you want to update, and click the download link to download.
5. You will be prompted with a Save As dialog screen.
6. Save the downloaded CloudFormation template file (a *.yml YAML file) locally to your PC for use in the following steps.
7. Log Into your AWS Management Console.
8. Make sure you are in the correct AWS region for where you want to deploy (this can be found on the top right of the Navigation bar).
9. Click on Services at the top, and under Management and Governance, choose CloudFormation.
10. From the CloudFormations console, select Stacks in the left-hand navigation bar, and find the stack associated with the CloudFormation you are updating that you previously deployed.
11. Click the Update button (in the top right of the screen).
12. You will be presented the Update Stack view:
    • Under the Prepare Template section, select Replace current template
    • Under Specify Template, select Upload a template file
    • Under Upload a template file, click Choose File
    • In the resulting file selector, find and upload the file you saved from Step 6 above
    • Click Next at the bottom

13. On the next Specify stack details page, all the Parameters values will be pre-loaded with the previously entered values you selected when you originally deployed the CloudFormation stack.

    • In most cases, you will want to leave all the input parameter values you originally selected unchanged.
    • The exceptions to this are:
      • If a new parameter has been added as part of the update (what requires a value to be input); or
      • If the parameter refers to a Lambda binary (a .jar or .zip file) with a version number in it. In this case, the pre-loaded parameter value will be the previous value/version (that will no longer be available. You need to click it, and select the new value in the resulting dropdown - there will only ever be one option in the dropdown list, which will be the latest version of the binary available.
    • Click on Next

14. On the Configure Stack options, keep all the defaults, and click Next at the bottom

15. On the Review page, scroll to the bottom, check the blue "I acknowledge that AWS CloudFormation might create IAM resources" check box, and click the Submit button at the bottom to complete.

A stack update usually takes a minute or two to run (depends on which stack you are updating). Within the Events tab of the stack, you can click the refresh button (top-right) to see progress, until the deployment update is complete.