You are viewing documentation for version 1.17.x. The most current version is 1.20.x.  This documentation is available for 1.20.x.

Chain of Trust

Bottlerocket’s cryptographic validation mechansims

Container hosts are particularly sensitive, with nearly unfettered access to your workloads, secrets, storage, and network. Consequently, ensuring that only your desired code runs on the host is paramount. Bottlerocket’s chain of trust provides cryptographic verification of all parts of the boot sequence through to your containers starting. Effectively, this means that every step verifies the next step in the sequence and any verification failure will immediately prevent any further progress.

Starting from Bottlerocket 1.15.0 with Kubernetes 1.28 or ECS 2 variants (or newer), Secure Boot is enabled by default, where supported by firmware.

Boot Sequence

EFISystemPartition(NVRAM)signature dbPower UpUEFIFirmwareshimGRUBgrub.cfg(w/dm-verityroot hash)Bottlerocketimmutableroot FSkerneldm-verity root hashsignature: shimsignature: GRUBsignature: kernelsignature: grub.cfg

The chain of trust starts prior to booting Bottlerocket. Modern, server-class machines initialize by loading firmware that conforms to the UEFI specification. In the most basic configuration, the firmware hands off control of the machine to the OS or bootloader. However, UEFI optionally implements Secure Boot, which is a mechanism that prevents hand off to unsigned software. Bottlerocket uses Secure Boot by default.

To start, the firmware retrieves the Bottlerocket certificate stored in the system’s NVRAM and uses it to verify that the first-stage bootloader, shim, is correctly signed.

Shim has access to certs stored in NVRAM. These certs are needed to verify the signed binary for GNU GRUB, the next step in the boot process. GRUB verifies the signature of its configuration file, grub.cfg, then grub calls into shim to verify the kernel. The GRUB configuration also contains the dm-verity root hash for the immutable root filesystem. GRUB hands off to the now-verified Linux kernel which can mount the root filesystem using the dm-verity root hash.

If any verification fails during the above process, the boot sequence will cease. After the boot process, dm-verity will detect any changes to the block device underlying the root filesystem and trigger a reboot of the machine.


This chain of trust relies on Secure Boot enabled firmware. Secure Boot has some prerequisites which are primarily relevant on metal variants:

  1. UEFI firmware
  2. Firmware Secure Boot feature enabled; Compatibility Support Module and/or legacy bios emulation disabled
  3. The machine’s NVRAM must contain Bottlerocket’s “db” certificate, which is used to sign shim. The Bottlerocket EFI partition includes this certificate in both PEM and DER formats.

Verifying these requirements varies by hardware vendor and may involve making edits on your hardware’s firmware setup menu.

On aws-* variants , any instance based with a Xen-based hypervisor (generation 4 and below) use a legacy BIOS mode and consequently cannot use Secure Boot.

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.