This document describes what Bottlerocket variants are and how they are built.
In the Background section, we discuss the motivation for variants.
In the Variants section, we list the variants that exist today.
In the Development section, we provide a short guide for adding a new variant.
Bottlerocket is purpose-built for hosting containers. It can run one of several container orchestrator agents. It is also image-based and does not include a package manager for customization at runtime.
Conceptually, each image could include all orchestrator agents, but that would conflict with our design goals. We want to keep the footprint of Bottlerocket as small as possible for security and performance reasons. Instead, we make different variants available for use, each with its own set of software and API settings.
A variant is essentially a list of packages to install, plus a model that defines the API. The documentation for packages covers how to create a package. Information about API settings for variants can be found in the models documentation.
The aws-k8s-1.15 variant includes the packages needed to run a Kubernetes node in AWS. It supports self-hosted clusters and clusters managed by EKS.
The aws-dev variant has useful packages for local development of the OS. It includes tools for troubleshooting as well as Docker for running containers.
Say we want to create my-variant, a custom build of Bottlerocket that runs my-agent.
This listing shows the directory structure of our sample variant.
variants/my-variant
├── Cargo.toml
├── build.rs
└── lib.rs
Each variant has a Cargo.toml file that lists the packages to install.
It also includes a build.rs build script which tells Cargo to invoke our buildsys tool.
Artifacts for the variant are built as a side effect of Cargo running the script.
It has an empty lib.rs for the actual crate, since Cargo expects some Rust code to build.
Our sample variant has the following manifest.
[package]
name = "my-variant"
version = "0.1.0"
edition = "2018"
publish = false
build = "build.rs"
[package.metadata.build-variant]
included-packages = [
"release",
"my-agent",
]
[lib]
path = "lib.rs"
The package.metadata table is ignored by Cargo and interpreted by our buildsys tool.
It contains an included-packages list which specifies the packages to install when building the image.
Variants should almost always include the release package.
This pulls in the other core packages and includes essential configuration and services.
Be sure to include publish = false for all packages, as these are not standard crates and should never appear on crates.io.
We use the same build script for all variants.
use std::process::{exit, Command};
fn main() -> Result<(), std::io::Error> {
let ret = Command::new("buildsys").arg("build-variant").status()?;
if !ret.success() {
exit(1);
}
Ok(())
}
If you need a build script with different behavior, the recommended approach is to modify the buildsys tool.
The package.metadata table can be extended with declarative elements that enable the new feature.
We use the same Rust code for all variants.
// not used
After the above files are in place, the variant must be added to the variants workspace.
Open variants/Cargo.toml in your editor and update the members list.
[workspace]
members = [
...
"my-variant",
...
]
Next, run cargo generate-lockfile to refresh Cargo.lock.
To build your variant, run the following command in the top-level Bottlerocket directory.
cargo make -e BUILDSYS_VARIANT=my-variant
This will build all packages first, not just the ones needed by your variant.