0.2.x (Current) on Bottlerocket

Concepts

Mon, 01 Jan 0001 00:00:00 +0000

You can update Bottlerocket in a couple of ways:

node replacement where new instances with a new version of the OS replace nodes with older versions of the OS,
in-place updates where the node downloads and reboots into a new version of the OS while maintaining the same instance/machine.

There is no single preferred nor advised method to update a node; both methods have pros and cons depending on your situation. You can trigger an in-place update manually with the API or you can use the Bottlerocket ECS Updater. The ECS Updater is a service that checks for (and applies) Bottlerocket updates when your nodes are ready.

Setup

Mon, 01 Jan 0001 00:00:00 +0000

This guide assumes you have AWS CLI v2 installed on a Unix-like system and that you’re authenticated into an account with the requisite permissions.

Note

Environment variable names in this guide do not have specific meaning; you can replace them with your own or directly interpolate your values as needed.

Define your environment

First, define your region in an environment variable. Customize the value of this variable for whatever region in which your particular Amazon ECS cluster resides.

Operate & Observe

Mon, 01 Jan 0001 00:00:00 +0000

By default, the ECS Updater runs every 12 hours (using the default template, schedule defined at at .Resources.BottlerocketUpdaterSchedule.Properties.ScheduleExpression). Each time it runs, the ECS Updater creates a new log stream in Amazon CloudWatch Logs in the log group you specified when deploying. You can view the logs in the CloudWatch Logs Console, with your own tools, or in the console.

ECS Updater logs in the console

First, you’ll need to retrieve the log stream; likely you’re interested in the most recent update check. Using the environment variables established in the Setup documentation, run the following command to get the most recent stream and store it in an environment variable:

Troubleshoot

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting’s first step is evaluating the log messages emitted by ECS Updater. See Operate & Observe for details on how logging works with ECS Updater and what common messages mean.

Common Issues

Bottlerocket instances start with an old version of Bottlerocket

After using ECS Updater for a while you may notice that any brand new nodes added to the cluster start with an older version of Bottlerocket then ECS Updater flags them for an update on next invocation. The ECS updater can only update existing nodes and it doesn’t manage the node creation process. If you’re using an auto-scaling group, update your AMI ID in the the launch configuration or template.

Uninstall

Mon, 01 Jan 0001 00:00:00 +0000

To uninstall ECS Updater, delete the AWS CloudFormation stack that you previously deployed. Assuming you have the environment variables set from the previous install guide, run the following:

aws cloudformation delete-stack \
 --stack-name ${ECS_UPDATER_STACK} \
 --region ${AWS_REGION}

With no errors, this will give no return status.

To confirm the removal of ECS Updater, describe the stack:

aws cloudformation delete-stack --stack-name ${ECS_UPDATER_STACK}

If deleted, the CLI returns An error occurred (ValidationError) when calling the DescribeStacks operation Stack with id <...> does not exist , otherwise it will show the stack, indicating a still active ECS Updater.