Performing safe canary updates
CloudWatch synthetics safe canary updates allows you to test the updates on your existing canaries before applying the changes. This feature helps you validate canary compatibility with new run times and other configuration changes such as code or memory changes. This will help minimize potential monitoring disruptions caused by erroneous updates.
By using canary safe updates on runtime version updates, configuration changes, and code script modifications, you can mitigate risk, maintain uninterrupted monitoring, verify the changes before committing, update, and reduce downtime.
Prerequisites
Make sure the prequisites are complete.
Amazon account with CloudWatch synthetics permissions
Existing canary on the supported runtime versions (see Limitations for compatible runtimes)
Include compatible runtimes when performing a dry run (see Limitations for compatible runtimes)
Best practices
Here are some best practices to follow while performing a canary .
Execute a dry run to validate a runtime update
Perform dry runs before production updates to canary
Review canary logs and artifacts after a dry run
Use dry runs to validate dependencies and library compatibility
Testing canary using dry run
You can test the canary update using the following options:
Using the Amazon Web Services Management Console's Edit workflow
Go the CloudWatch synthetics console.
Select the canary you want to update.
From the Actions drop down, choose Edit.
Update the canary with the changes you want to test. For example, changing runtime version or editing the script’s code.
Under Canary script, choose Start Dry Run to test and view the results immediately or choose Validate and save later at the bottom of the page to start the test and view the results later in your Canary Details page.
After the dry run succeeds, choose Submit to commit your canary updates.
Using the Amazon Web Services Management Console for updating canaries in a batch
Go the CloudWatch synthetics console.
Choose the Synthetics list page.
Select upto five canaries for which you want to update the runtime.
From the Actions drop down, choose Update Runtime.
Choose Start dry run for new runtime to start the dry run and test your changes before an update.
On the Synthetics list page, you will see a text next to the Runtime version for the canary that displays the progress of the dry run (this is only displayed for dry runs involving a runtime update).
Once the dry run succeeds, you will see an Initiate Update text.
Choose Initiate Update to commit the runtime update.
If the dry run fails, you will see an Update dry run failed text. Choose the text to view the debug link to the canary details page.
Using the Amazon CLI or SDK
The API starts the dry run for the provided canary name MyCanary and updates the runtime version to syn-nodejs-puppeteer-10.0.
aws synthetics start-canary-dry-run \ --name MyCanary \ --runtime-version syn-nodejs-puppeteer-10.0 // Or if you wanted to update other configurations: aws synthetics start-canary-dry-run \ --name MyCanary \ --execution-role-arn arn:aws:iam::123456789012:role/NewRole
The API will return the DryRunId inside the DryRunConfigOutput.
Call GetCanary with the provided DryRunId to receive the canary’s dry run configurations and an additional field DryRunConfig which contains the status of the dry run listed as LastDryRunExecutionStatus.
aws synthetics get-canary \ --name MyCanary \ --dry-run-id XXXX-XXXX-XXXX-XXXX
For more details, use GetCanaryRuns with the provided DryRunId to retrieve the run and additional information.
aws synthetics get-canary-runs \ --name MyCanary \ --dry-run-id XXXX-XXXX-XXXX-XXXX
After a successful dry run, you can then use UpdateCanary with the provided DryRunId in order to commit your changes.
aws synthetics update-canary \ --name MyCanary \ --dry-run-id XXXX-XXXX-XXXX-XXXX
When it fails for any reason (result from GetCanaryRuns will have the details), the result from GetCanaryRuns has an artifact location that contains logs to debug. When there are no logs, the dry run failed to be created. You can validate by using GetCanary.
aws synthetics get-canary \ --name MyCanary \ --dry-run-id XXXX-XXXX-XXXX-XXXX
The State, StateReason, and StateReasonCode displays the status of the dry run.
Using Amazon CloudFormation
In your template for a Synthetics Canary, provide the field DryRunAndUpdate which accepts a boolean value true or false.
when the value is true every update executes a dry run to validate the changes before automatically updating the canary. When the dry run fails, the canary does not update and fails the deployment and Amazon CloudFormation deployment with a valid reason. To debug this issue, use the Amazon Synthetics console
or if using an API, get the ArtifactS3Location using the GetCanaryRuns API, and download the *-log.txt files to review the canary log executions for errors. After validation, modify the Amazon CloudFormation template and retry the deployment or use the above API to validate.
When the value is false, synthetics will not execute a dry run to validate changes and will directly commit your updates.
For information on troubleshooting a failed canary, see Troubleshooting a failed canary.
An example template.
SyntheticsCanary: Type: 'AWS::Synthetics::Canary' Properties: Name: MyCanary RuntimeVersion: syn-nodejs-puppeteer-10.0 Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600} ... DryRunAndUpdate: true
Limitations
Supports runtime versions – syn-nodejs-puppeteer-10.0+, syn-nodejs-playwright-2.0+, and syn-python-selenium-5.1+
You can only execute one dry run per canary at a time
When a dry run fails, you cannot update the canary
Dry run cannot test any Schedule field changes
Note
When you initiate a dry run with code changes for a Playwright canary and you want to update the canary without providing the associated DryRunId, you must explicitly specify the code parameters.