You are viewing documentation for version 1.22.x. The most current version is 1.25.x.  This documentation is available for 1.25.x.

Bootstrap Commands

Configure the host with Bottlerocket API commands during boot.

Bootstrap commands are a way to configure and modify a Bottlerocket instance using the Bottlerocket API at boot time. They run prior to the Bootstrap Containers.

Lifecycle

When you define a bootstrap command using user-data or the Bottlerocket API, the following sequence occurs on next boot:

  • systemd runs all the bootstrap commands in lexicographical order of their names. Each Bottlerocket API command inside a bootstrap-command runs serially in the declared order.
  • systemd will not move to the next target until all of the bootstrap commands start, run and exit.
  • any bootstrap command configured with mode=once will change to mode=off once complete.
  • any bootstrap command set to essential=true that exits with a non-zero exit code halts the boot process.

Examples

Considerations

As a consequence of this lifecycle, you should keep a few things in mind when using bootstrap commands:

  1. Bootstrap commands can only run apiclient commands.
  2. Bootstrap commands can’t run apiclient exec commands because host containers aren’t ready at this stage of the boot.
  3. Running apiclient reboot in a bootstrap command with mode=always will cause the node to reboot endlessly.
  4. apiclient reboot in a bootstrap command with mode=once will hold off the reboot until the completion of all bootstrap commands.
  5. Due to serial nature of bootstrap commands, they should be short-running to reduce overhead on boot times.

Use cases

The following are a few examples use cases for bootstrap commands

Configure ephemeral disks

In a Kubernetes host

[settings.bootstrap-commands.k8s-ephemeral-storage]
commands = [
    ["apiclient", "ephemeral-storage", "init"],
    ["apiclient", "ephemeral-storage" ,"bind", "--dirs", "/var/lib/containerd", "/var/lib/kubelet", "/var/log/pods"]
]
essential = true
mode = "always"

In an ECS host

[settings.bootstrap-commands.ecs-ephemeral-storage]
commands = [
    ["apiclient", "ephemeral-storage", "init"],
    ["apiclient", "ephemeral-storage" ,"bind", "--dirs", "/var/lib/containerd", "/var/lib/docker", "/var/log/ecs"]
]
essential = true
mode = "always"

Running the CIS reports

Bottlerocket CIS Benchmark

[settings.bootstrap-commands.bottlerocket-cis-benchmark]
commands = [["apiclient", "report", "cis", "-l", "2"]]
essential = true
mode = "always"

Kubernetes CIS Benchmark

[settings.bootstrap-commands.kubernetes-cis-benchmark]
commands = [["apiclient", "report", "cis-k8s", "-l", "2"]]
essential = true
mode = "always"

Checking and Applying Updates

[settings.bootstrap-commands.kubernetes-cis-benchmark]
commands = [["apiclient", "update", "apply", "--check", "--reboot"]]
essential = true
mode = "always"

Also see


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.