DOCSEARCHbyAlgolia
Submit Docs

Bottlerocket OS Documentation

repository·develop·Indexed 27 days ago

https://github.com/bottlerocket-os/bottlerocket

An open-source, Linux-based operating system designed specifically for hosting containers. It features an atomic update model with A/B partition sets, dm-verity for immutable root filesystems, and specialized variants for Amazon EKS, ECS, and VMware. The OS includes a control container for AWS SSM access, an optional admin container for SSH, and the apiclient tool for system configuration and update management.

Tokens
37.4K
Snippets
74
Records
227
Agent score
94%

What's inside Bottlerocket

  2. Security Recommendations Overview

    develop

    Bottlerocket follows the Shared Responsibility Model. To meet security and compliance requirements, users should implement the following recommendations categorized by priority:

    Critical Priority

    • Enable automatic updates
    • Avoid containers with elevated privileges
    • Restrict access to the host API socket
    • Restrict access to the container runtime socket

    Important Priority

    • Design for host replacement
    • Enable kernel lockdown
    • Limit use of host containers
    • Limit use of privileged SELinux labels
    • Limit access to system mounts
    • Limit access to host namespaces
    • Limit access to block devices
    • Enforce requested NVIDIA GPU limits for unprivileged containers
    • Limit use of NVIDIA GPU Time-Slicing

    Moderate Priority

    • Do not run containers as UID 0

  3. Understand Bottlerocket Variants

    develop
    Bottlerocket uses variants to maintain a minimal footprint for security and performance. Instead of including all possible orchestrator agents in a single image, Bottlerocket provides specific variants tailored to different use cases. Each variant consists of a specific list of packages and a model defining its API settings.

  4. Use the bottlerocket-release library to parse os-release data

    develop
    The bottlerocket-release library provides a BottlerocketRelease struct that represents the data found in a standard os-release file (or a custom file path provided by the user). It is designed to pull information at runtime to avoid unnecessary rebuilds when the build_id changes. The VERSION_ID field is automatically parsed and returned as a semver::Version for easier programmatic comparison.

  5. Verify Bottlerocket security hardening

    develop

    Bottlerocket implements several layers of defense-in-depth hardening:

    • Immutable Rootfs: Uses dm-verity for transparent integrity checking of the root filesystem. If corruption is detected, the kernel is configured to restart, failing closed to prevent running in an unknown state.
    • No Shell/Interpreters: Non-developer builds do not include a shell or interpreted languages (like Python) to prevent attackers from pivoting via local code execution.
    • SELinux: Enabled in enforcing mode by default. It cannot be disabled and is used to prevent components from modifying API settings, container archives, or other container layers.
    • Kernel Lockdown: Enabled in integrity mode on most variants to block actions that could compromise the kernel. (Note: *-nvidia variants use none to allow unsigned kernel modules).
    • Hardened Binaries: Executables are built with PIE (Position-Independent Executables), stack canaries, and full RELRO support to mitigate memory corruption and ROP attacks.

  6. Understand hardware support for Bottlerocket bare metal

    develop

    The Bottlerocket bare metal variant is designed for x86_64 server hardware outside of AWS or VMware clusters. To maintain a small and simple footprint, the kernel includes a reduced set of drivers compared to general-purpose Linux distributions.

    Included Drivers:

    • A wide spread of 10G+ Ethernet NICs (excluding model-specific FPGA offloading).
    • Common RAID controllers.

    If your hardware is missing required drivers, you can request their inclusion by submitting an issue using the metal_driver.md template.

  7. Understand Bottlerocket security features

    develop

    Bottlerocket uses several security mechanisms to protect the system:

    • dm-verity: Used to verify the immutable root filesystem.
    • SELinux: Provides mandatory access control.
    • Rust: Most first-party components are written in Rust to eliminate memory safety issues.

    For detailed implementation details, refer to the SECURITY_FEATURES.md file. For best practices on securing your deployment, refer to SECURITY_GUIDANCE.md.

  9. Customize VMware OVA upload parameters

    develop

    When running cargo make for VMware uploads, you can override several parameters using environment variables:

    • Target Datacenters: Override the Infra.toml list using VMWARE_DATACENTERS="datacenter1,datacenter2".
    • VM Name: Override the default VM name using VMWARE_VM_NAME=my-name.
    • Import Spec: Override the import spec path using VMWARE_IMPORT_SPEC_PATH=/path/to/my/spec.toml. You can use the template at tools/pubsys/support/vmware/import_spec.template as a starting point.

    Example uploading as a template with a custom name, specific datacenters, and a custom import spec:

    cargo make vmware-template \
  -e BUILDSYS_VARIANT=vmware-k8s-1.32 \
  -e VMWARE_DATACENTERS="foo,bar" \
  -e VMWARE_VM_NAME=my-name \
  -e VMWARE_IMPORT_SPEC_PATH=/path/to/my/spec.toml
    cargo make vmware-template \
  -e BUILDSYS_VARIANT=vmware-k8s-1.32 \
  -e VMWARE_IMPORT_SPEC_PATH=/path/to/my/spec.toml

  10. Install dependencies to build Bottlerocket

    develop

    Before building Bottlerocket, ensure your system meets the following requirements:

    System Requirements

    • Disk Space: At least 80GB of local directory space.
    • CPU: Highly demanding; scales well to 32+ cores.

    OS Packages

    Ubuntu:

    apt install build-essential openssl libssl-dev pkg-config liblz4-tool

    Fedora:

    yum install make automake gcc openssl openssl-devel pkg-config lz4 perl-FindBin perl-lib

    Rust and Build Tools

    • Rust: Version 1.51.0 or higher (recommended via rustup).
    • cargo-make: Required for organizing build tasks.
    cargo install cargo-make

    Docker

    • Version: 20.10.10 or later (BuildKit support is required).
    • Setup: Ensure your user is in the docker group.
    • Cgroups v2 Note: If you encounter OCI runtime create failed: this version of runc doesn't work on cgroups v2, you may need to disable the unified cgroup hierarchy by setting the kernel parameter systemd.unified_cgroup_hierarchy=0 in your boot configuration (e.g., GRUB) and rebooting.

  11. Configure Bottlerocket using User Data

    develop

    Bottlerocket variants ingest TOML-formatted user data from multiple sources. If a setting is defined in multiple sources, the value from the later source overrides the earlier one. The precedence order depends on the variant type:

    All Variants:

    1. /var/lib/bottlerocket/user-data.toml

    AWS Variants:

    1. /var/lib/bottlerocket/user-data.toml
    2. AWS Instance Metadata Service (IMDS)

    VMware Variants:

    1. /var/lib/bottlerocket/user-data.toml
    2. Mounted CD-ROM (file named user-data or from an OVF file)
    3. VMware guestinfo interface

  12. Enable and Access the Admin Container

    develop

    The admin container provides an SSH server and is disabled by default. It allows you to log in as ec2-user using your EC2-registered SSH key.

    1. Enable the Admin Container

    Via User Data (at launch):

    [settings.host-containers.admin]
enabled = true

    Via Control Container (on a running instance):

    enable-admin-container

    Via API (if using a custom control container):

    apiclient set host-containers.admin.enabled=true

    2. Access the Admin Container

    From the Control Container:

    enter-admin-container

    Or execute commands directly:

    apiclient exec admin bash

    Via SSH: Once enabled, connect via SSH using your registered key.

    3. Get a Root Shell

    Once inside the admin container, run sheltie to obtain a full root shell in the Bottlerocket host. Note that most changes made as root will not persist across restarts due to the dm-verity filesystem setup.