Bootstrap containers are a form of host container that you can use to run critical software before the node connects to an orchestrator. They give you substantial power to configure and modify the system in ways that would otherwise be difficult or impossible.
When you define a bootstrap container using user-data or the Bottlerocket API, the following sequence occurs on next boot:
systemd
starts all of the bootstrap containers concurrently,systemd
will not move to the next target until all of the bootstrap containers start, run, and exit,mode=once
will change to mode=off
once complete,essential=true
that exits with an non-zero exit code halts the boot process,kubelet
on *-k8s-*
variants or the ECS agent on *-ecs-*
variants).This example shows four bootstrap containers (B1
,B2
,B3
, and B4
) starting.
The start order of these containers is not sequential and could be in any order.
Container B2
runs the longest and the next stage of the boot does not proceed until it completes.
This example is the same as the previous one except container B2
is configured with essential=true
.
Container B2
exits with a non-zero exit code and consequently the boot halts.
This example is the same as the first except container B4
is configured with mode=once
.
After all the bootstrap containers finish, Bottlerocket (via a systemd
unit) updates container B4
’s mode
to off
.
As a consequence of this lifecycle, you should keep a few things in mind when using bootstrap containers:
systemd
starts all the bootstrap containers concurrently, you cannot rely on a deterministic starting order./etc/
).Bootstrap containers sit somewhat between default host containers and superpowered
host container permissions.
They have access to the underlying host filesystem at /.bottlerocket/
which contains the root filesystem (/.bottlerocket/rootfs
).
Additionally, bootstrap containers run with the CAP_SYS_ADMIN capability, allowing for the creation of files, directories, and mounts accessible to the host (however the root filesystem remains immutable).
You cannot elevate the permissions of bootstrap containers.
Bootstrap containers have a variety of uses.
apiclient
.apiclient
./.bottlerocket/rootfs/mnt
and all bootstrap or superpowered
host containers share this bind mount, you can configure ephemeral disks attached to your host in a bootstrap container and use it elsewhere.