Locking to a Specific Release

How to lock a Bottlerocket node to a specific release version

Locking your Bottlerocket nodes to a specific release is possible using the Bottlerocket Settings API.

A quick explanation of the apiclient command used below:

Two settings are set: updates.version-lock and updates.ignore-waves.

  • updates.version-lock: which version of Bottlerocket to lock to when apiclient checks for updates.
  • updates.ignore-waves: ignore the update waves behavior and update the Bottlerocket node immediately.

To create an SSM Command Document, follow the steps in the AWS Systems Manager User Guide: “Create an SSM document (console)”. Remember to select “YAML” in the “Content” box, since the SSM Command Document below is formatted in YAML.

SSM Command Document: Lock to a Specific Release

The following SSM Command Document is referred to in this documentation as version-lock-bottlerocket-node:

---
schemaVersion: "2.2"
description: "Lock a Bottlerocket host to a specific version via the Bottlerocket Settings API"
parameters:
  TargetVersion:
    type: "String"
    description: "The target version of Bottlerocket to lock to (e.g. 1.12.0)"
mainSteps:
  - name: "setTargetVersion"
    action: "aws:runShellScript"
    inputs:
      timeoutSeconds: '20'
      runCommand:
        - "apiclient set updates.version-lock=\"{{ TargetVersion }}\" updates.ignore-waves=true"

You should now have the above SSM Command Document available in the SSM “Owned by me” tab in the “Documents” section of the SSM Console.

Applying a Version Lock

In order to apply a version lock using SSM, follow these steps:

  1. First, tell your Bottlerocket nodes that you want them to lock to a specific version.
    • Apply the version-lock-bottlerocket-node SSM Command Document previously described.
      • In the “Command parameters” section of the Run Command page, remember to specify the full version of Bottlerocket that you want to lock to (e.g. 1.12.0, not 1.12).
      • If you are using EKS, select all nodes in a given EKS cluster by specifying an instance tag in the “Target selection” section of the page. Specify eks:cluster-name as the tag key, with the tag value set to your cluster name.
  2. Next, tell your Bottlerocket nodes to prepare to boot into that specific version.
  3. Finally, reboot your Bottlerocket nodes into the version you locked to.

Removing a Version Lock

In order to remove a version lock using SSM, create and apply the following SSM Command Document to the Bottlerocket nodes you want to remove a Version Lock from (the SSM Command Document can be named version-unlock-bottlerocket-node for example):

SSM Command Document: Remove a Version Lock

---
schemaVersion: "2.2"
description: "Remove a Version Lock from a Bottlerocket host via the Bottlerocket Settings API"
mainSteps:
  - name: "unsetTargetVersion"
    action: "aws:runShellScript"
    inputs:
      timeoutSeconds: '20'
      runCommand:
        - "apiclient set updates.version-lock=\"latest\" updates.ignore-waves=false"

See a problem with this page? File an issue. All feedback is appreciated.
You can also directly contribute a change to the source file of this page on GitHub.