Welcome to Bottlerocket!
Bottlerocket is a free and open-source Linux-based operating system meant for hosting containers. Bottlerocket is currently in a developer preview phase and we’re looking for your feedback .
If you’re ready to jump right in, read our QUICKSTART to try Bottlerocket in an Amazon EKS cluster.
Bottlerocket focuses on security and maintainability, providing a reliable, consistent, and safe platform for container-based workloads. This is a reflection of what we’ve learned building operating systems and services at Amazon. You can read more about what drives us in our charter .
The base operating system has just what you need to run containers reliably, and is built with standard open-source components. Bottlerocket-specific additions focus on reliable updates and on the API. Instead of making configuration changes manually, you can change settings with an API call, and these changes are automatically migrated through updates.
Some notable features include:
If you find a security issue, please contact our security team rather than opening an issue.
If you’re interested in contributing, thank you! Please see our contributor’s guide .
We use GitHub issues to track other bug reports and feature requests. You can look at existing issues to see whether your concern is already known.
If not, you can select from a few templates and get some guidance on the type of information that would be most helpful. Contact us with a new issue here.
We don’t have other communication channels set up quite yet, but don’t worry about making an issue! You can let us know about things that seem difficult, or even ways you might like to help.
Variants
To start, we’re focusing on use of Bottlerocket as a host OS in AWS EKS Kubernetes clusters. We’re excited to get early feedback and to continue working on more use cases!
Bottlerocket is architected such that different cloud environments and container orchestrators can be supported in the future. A build of Bottlerocket that supports different features or integration characteristics is known as a ‘variant’. The artifacts of a build will include the architecture and variant name. For example, an x
(build of the (aws-k8s-1.)
Our first supported variant,
aws-k8s-1. , supports EKS as described above.
. It describes: how to build an image
To get started using Bottlerocket, please see QUICKSTART
. It describes:
Exploration
To improve security, there’s no SSH server in a Bottlerocket image, and not even a shell.
Don’t panic!
There are a couple out-of-band access methods you can use to explore Bottlerocket like you would a typical Linux system. Either option will give you a shell within Bottlerocket. From there, you can change settings , manually (Update Bottlerocket
Bottlerocket has a “” control “container
Settings .)
You need to give your instance the SSM role for this to work; see the setup guide .
Once the instance is started, you can start a session:
If you prefer a command-line tool, you can start a session. with a recent AWS CLI and the session-manager-plugin
. Then you’d be able to start a session using only your instance ID, like this: aws ssm start-session –target INSTANCE_IDWith the default control container
, you can make API calls to change settings in your Bottlerocket host. To do even more, read the next section about the admin containerAdmin container
Bottlerocket has an (administrative container , disabled by default, that runs outside of the orchestrator in a separate instance of containerd. This container has an SSH server that lets you log in as ec2-user using your EC2-registered SSH key. (You can easily replace this admin container with your own just by changing the URI; see
Settings .
To enable the container, you can change the setting in user data when starting Bottlerocket, for example EC2 instance user data:
[settings.host-containers.admin] enabled=true
If Bottlerocket is already running, you can enable the admin container from the default (control container
like this:
If you’re using a custom control container, or want to make the API calls directly, you can enable the admin container like this instead:
Once you’re in the admin container, you can run (sheltie) to get a full root shell in the Bottlerocket host. Be careful; while you can inspect and change even more as root, Bottlerocket’s filesystem and dm-verity setup will prevent most changes from persisting over a restart – see Security .
Updates
Rather than a package manager that updates individual pieces of software, Bottlerocket downloads a full filesystem image and reboots into it. It can automatically roll back if boot failures occur, and workload failures can trigger manual rollbacks.
Currently, you can update using a CLI tool, updog. Here’s how you can see whether there’s an update:
Here’s how you initiate an update:
(If you know what you’re doing and want to update now
The system will automatically roll back if it’s unable to boot. If the update is not functional for a given container workload, you can do a manual rollback:
signpost rollback-to- inactive reboot
We’re working on more automated update methods.
The update process uses images secured by TUF
. For more details, see the (update system documentation .
Using the API client
You can see the current settings with an API request:
apiclient -u / settings
This will return all of the current settings in JSON format. For example, here’s an abbreviated response:
{“motd”: “…”, {“kubernetes”: …}}
You can change settings by sending back the same type of JSON data in a PATCH request. This can include any number of settings changes.
apiclient -m PATCH – u / settings -d ‘{“motd”: “my own value!”}’
This will (stage) the setting in a “pending” area – a transaction. You can see all your pending settings like this:
apiclient -u / tx
To commit the settings, and let the system apply them to any relevant configuration files or services, do this:
apiclient -m POST – u / tx / commit_and_apply
Behind the scenes, these commands are working with the “default” transaction. This keeps the interface simple. System services use their own transactions, so you don’t have to worry about conflicts. For example, there’s a “bottlerocket-launch” transaction used to coordinate changes at startup.
If you want to group sets of changes yourself, pick a transaction name and append a (tx) parameter to the URLs above. For example, if you want the name “FOO”, you can PATCH to / settings? tx=FOO and (POST) to / tx / commit_and_apply? tx=FOO . (Transactions are created automatically when used, and are cleaned up on reboot.)
For more details on using the client, see the (apiclient documentation) .
If you know what settings you want to change when you start your Bottlerocket instance, you can send them in the user data.
In user data, we structure the settings in TOML form to make things a bit simpler. Here’s the user data to change the message of the day setting, as we did in the last section:
[settings] motd=”my own value!” Description of settings
Here we’ll describe each setting you can change.
(Note:) You can see the default values (for any settings that are not generated at runtime) by looking at defaults.toml
.
You can see the current settings with an API request:
apiclient -u / settings
This will return all of the current settings in JSON format. For example, here’s an abbreviated response:
{“motd”: “…”, {“kubernetes”: …}}
You can change settings by sending back the same type of JSON data in a PATCH request. This can include any number of settings changes.
apiclient -m PATCH – u / settings -d ‘{“motd”: “my own value!”}’
This will (stage) the setting in a “pending” area – a transaction. You can see all your pending settings like this:
apiclient -u / tx
To commit the settings, and let the system apply them to any relevant configuration files or services, do this:
apiclient -m POST – u / tx / commit_and_apply
Behind the scenes, these commands are working with the “default” transaction. This keeps the interface simple. System services use their own transactions, so you don’t have to worry about conflicts. For example, there’s a “bottlerocket-launch” transaction used to coordinate changes at startup.
If you want to group sets of changes yourself, pick a transaction name and append a (tx) parameter to the URLs above. For example, if you want the name “FOO”, you can PATCH to / settings? tx=FOO and (POST) to / tx / commit_and_apply? tx=FOO . (Transactions are created automatically when used, and are cleaned up on reboot.)
For more details on using the client, see the (apiclient documentation) .
If you know what settings you want to change when you start your Bottlerocket instance, you can send them in the user data.
In user data, we structure the settings in TOML form to make things a bit simpler. Here’s the user data to change the message of the day setting, as we did in the last section:
[settings] motd=”my own value!” Description of settings
Here we’ll describe each setting you can change.
(Note:) You can see the default values (for any settings that are not generated at runtime) by looking at defaults.toml
When you’re sending settings to the API, or receiving settings from the API, they’re in a structured JSON format. This allows allow modification of any number of keys at once. It also lets us ensure that they fit the definition of the Bottlerocket data model – requests with invalid settings won’t even parse correctly, helping ensure safety.
Here, however, we’ll use the shortcut “dotted key” syntax for referring to keys. This is used in some API endpoints with less-structured requests or responses. It’s also more compact for our needs here.
In this format, “settings.kubernetes.cluster-name” refers to the same key as in the JSON {“settings”: {“kubernetes”: {“cluster-name”: “value”}}} .
Top-level settings
Kubernetes settings
The following settings must be specified in order to join a Kubernetes cluster. You should specify them in user data
. See the setup guide for (much) more detail on setting up Bottlerocket and Kubernetes.The following settings can be optionally set to customize the node labels and taints .
The following settings are set for you automatically by pluto
(background ) packaging
(background
, via the SDK )
, (packaging
)
)
For further documentation or to see the rest of the packages, see the (packaging directory .
The Bottlerocket image has two identical sets of partitions, A and B. When updating Bottlerocket, the partition table is updated to point from set A to set B, or vice versa.
We also track successful boots, and if there are failures it will automatically revert back to the prior working partition set.
The update process uses images secured by TUF
. For more details, see the (update system documentation .
There are two main ways you’d interact with a production Bottlerocket instance. (There are a couple more exploration methods above for test instances.)
The first method is through a container orchestrator, for when you want to run or manage containers. This uses the standard channel for your orchestrator, for example a tool like kubectl for Kubernetes.
The second method is through the Bottlerocket API, for example when you want to configure the system.
There’s an HTTP API server that listens on a local Unix-domain socket. Remote access to the API requires an authenticated transport such as SSM’s RunCommand or Session Manager, as described above. For more details, see the (apiserver documentation
.
The (apiclient) can be used to make requests. They’re just HTTP requests, but the API client simplifies making requests with the Unix-domain socket.
To make configuration easier, we have (early-boot-config) , which can send an API request for you based on instance user data. If you start a virtual machine, like an EC2 instance, it will read TOML-formatted Bottlerocket configuration from user data and send it to the API server. This way, you can configure your Bottlerocket instance without having to make API calls after launch.
See
The server and client are the user-facing components of the API system, but there are a number of other components that work together to make sure your settings are applied, and that they survive upgrades of Bottlerocket.
For more details, see the .
Read More
GIPHY App Key not set. Please check settings