# Bottlerocket OS: a container host with no shell and an API for settings > Bottlerocket is a Linux-based operating system built to host containers, with an API for configuration and partition-flip updates. It is aimed at EKS, ECS and VMware Kubernetes nodes, and its design keeps a shell off the image on purpose. **bottlerocket-os/bottlerocket** — An operating system designed for hosting containers - Repository: https://github.com/bottlerocket-os/bottlerocket - Website: https://bottlerocket.dev - Stars: 9,671 · Forks: 585 - Language: Rust - License: NOASSERTION - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/bottlerocket-os-bottlerocket ## What Bottlerocket OS is for, and who it is not for Bottlerocket is a free and open-source Linux-based operating system meant for hosting containers. That sentence sets the boundary: it is a host OS, not a distribution you log into and administer. The project's stated focus is security and maintainability, and the README frames this as a reflection of what the team learned building operating systems and services at Amazon. The intended user is someone running a container orchestrator. Bottlerocket is best used with one, and the repository ships separate quickstart guides for Amazon EKS, Amazon ECS, VMware and bare metal. If you want a general-purpose server, a build box, or a machine where you install packages interactively, this is the wrong tool, and the README is unusually direct about why: to improve security there is no SSH server in a Bottlerocket image, and not even a shell. The variant list also shows where the project concentrates effort. EKS variants cover Kubernetes 1.31 through 1.37, with matching `-nvidia` builds. ECS variants are `aws-ecs-2`, `aws-ecs-3` and their FIPS and NVIDIA counterparts. VMware variants track Kubernetes 1.31 through 1.37. The README states that all Kubernetes variants using 1.30 and earlier, VMware variants using 1.30 and earlier, bare metal Kubernetes variants, and ECS-1 variants are no longer supported, and recommends replacing nodes running them with the latest compatible variant. That is a real constraint on anyone sitting on an older cluster. ## The mechanism: modeled settings, an API, and partition flips Two design decisions carry most of the weight. The first is that configuration is modeled rather than edited. Bottlerocket-specific additions focus on reliable updates and on the API, and the README states that instead of making configuration changes manually you change settings with an API call, and those changes are automatically migrated through updates. The settings are part of the image's data model, which is why they can survive a version jump: the system knows which keys exist and what they mean. The second is how updates land. Bottlerocket updates are based on partition flips, described in the README as the basis for fast and reliable system updates. A new version is written to the inactive partition and the system switches to it, rather than mutating the running root filesystem in place. That model is what makes an immutable host practical, and it is also why the settings API matters: if you cannot log in and edit files, the API is the only supported path for changing anything. The repository layout reinforces the variant story. `variants/` holds one directory per build target, and the workspace `Cargo.toml` lists them as members, including `aws-k8s-1.31` through `aws-k8s-1.37`, their `-fips` counterparts, `aws-ecs-2`, `aws-ecs-3`, `aws-ecs-4`, `aws-mantle-1`, `vmware-k8s-*` and `metal-dev`. A build produces an artifact named for its architecture and variant, for example `bottlerocket-aws-k8s-1.32-x86_64--.img`. Supported architectures are `x86_64` and `aarch64`, written as `arm64` in some contexts. ## Installing Bottlerocket on EKS or ECS and getting a shell There is no installer to run. You launch an image, and the repository's quickstart guides cover the orchestrator setup and the instance launch for EKS, ECS and VMware. The README points at `QUICKSTART-EKS.md`, `QUICKSTART-ECS.md`, `QUICKSTART-VMWARE.md` and, for bare metal, `PROVISIONING-METAL.md`. The repository also includes `sample-eksctl.yaml` and `sample-eksctl-ssh.yaml`, which are the concrete starting points for an EKS node group. The README does not reproduce their contents, so open them in the repository and set the AMI family and Kubernetes version to match the variant you intend to run, for example `aws-k8s-1.32`. Because there is no shell, the way in is a container. The README describes a control container that gives you a shell within Bottlerocket, from which you can change settings, manually update the system, debug problems and explore. The access methods require that your instance has permission to reach the ECR repository where these containers live, and the README names the policy to add to the instance's IAM role: `AmazonEC2ContainerRegistryReadOnly`. The README does not document the exact control container image reference or the command that starts it, so take those from the quickstart guide for your platform rather than guessing. Once you have a shell, the settings API is where configuration changes belong, because those are the changes that migrate through updates. If you intend to build rather than consume images, `BUILDING.md` covers building an image and registering an EC2 AMI from it, and `Makefile.toml` and `Twoliter.toml` sit at the top level of the build setup. The README does not list the individual build commands, so follow `BUILDING.md` rather than assembling a command from the file names. ## Where Bottlerocket is the wrong choice The absence of a shell is the headline limitation, and it is deliberate rather than a gap to be filled. Debugging a node means going through the control container, which in turn means the instance role has to be able to pull from ECR. A cluster whose node role is locked down to exactly the permissions its workloads need will have to widen that role, and that is a security trade you should make consciously. The variant support window is the second constraint. The README lists Kubernetes 1.30 and earlier variants, VMware 1.30 and earlier variants, bare metal Kubernetes variants and ECS-1 variants as no longer supported, and tells users to replace those nodes. If your cluster upgrade cadence lags the Kubernetes release train, you will be replacing nodes on the project's schedule, not yours. The variant list is also narrower than a general distribution's hardware support, which is why `SUPPORTED-HARDWARE.md` exists as a separate file worth reading before you commit. The third limitation is documentation depth in the README itself. It states what the API and partition flips do, but it does not document rollback. If you need a documented procedure for reverting a bad update, the README is silent on it, and you should treat that as an open question to resolve from the quickstart guides and the linked documentation site before you put production nodes on it. ## How Bottlerocket differs from a general-purpose node image The obvious alternative is a general-purpose Linux distribution used as a Kubernetes node, where you have a package manager, an SSH daemon and a shell, and you patch the running system in place. The difference is not cosmetic. On a general-purpose host, configuration drifts: someone edits a file, an upgrade overwrites it, and the node's state stops matching anything you can reproduce. Bottlerocket replaces that with modeled settings changed through an API and migrated across updates, and with partition flips instead of in-place mutation. That trade runs the other way too. A general-purpose host lets you install an agent, a diagnostic tool or a kernel module on the spot. Bottlerocket's base operating system has just what you need to run containers reliably, built from standard open-source components, and anything beyond that has to fit the variant and settings model. If your workflow depends on ad-hoc node customization, a general-purpose distribution will cost you less friction. There is also a middle path worth naming: container-optimized images from other vendors that keep a shell and an SSH option while still shipping a minimal, container-focused base. The dividing line is whether the settings model is enforced. Bottlerocket's claim is that configuration is modeled and migrated; an image that merely trims packages does not give you that, and you are back to editing files that the next update may not preserve. ## Maintenance, versioning and licence The repository is not archived, and the last push was on 2026-09-19. Releases are frequent: v1.65.0 on 2026-09-09, v1.64.0 on 2026-07-29 and v1.63.0 on 2026-07-17. The upgrade cost is mostly in the variant matrix rather than in a manual migration, because settings are migrated through updates. What you pay for is keeping the node variant aligned with your cluster's Kubernetes version and replacing nodes when a variant leaves support. Licensing needs care rather than a summary. The repository's licence field is reported as `NOASSERTION`, and the top level contains both `LICENSE-APACHE` and `LICENSE-MIT`, which is the usual dual-licence arrangement for Rust projects, but the repository metadata does not assert a single SPDX identifier. There is also a `TRADEMARKS.md` file, which matters if you plan to redistribute images or publish AMIs under a name. Read `LICENSE-APACHE`, `LICENSE-MIT` and `TRADEMARKS.md` yourself; nothing here is legal advice. If you build your own images, the cost shifts to your build pipeline. `BUILDING.md` covers building an image and registering an EC2 AMI from it, and `PUBLISHING.md` covers making TUF repos, copying AMIs across regions, marking them public or granting account access, and making them discoverable through SSM parameters. That is a real amount of infrastructure to own, and it is the price of running a variant the project does not ship. ## Conclusion Adopt Bottlerocket for EKS, ECS or VMware Kubernetes worker nodes where you want an immutable image, API-driven settings and partition-flip updates instead of a general-purpose Linux host you patch by hand. Do not adopt it as a general-purpose server OS or a place to run non-container workloads: the README states there is no SSH server and not even a shell, and the control container path needs `AmazonEC2ContainerRegistryReadOnly` on the instance role. Before committing, verify that your cluster version has a supported variant (Kubernetes 1.30 and earlier variants are listed as no longer supported), and confirm the exact container image and command for the control container rather than guessing, because the README does not document rollback. ## FAQ ### What is Bottlerocket OS? It is a free and open-source Linux-based operating system meant for hosting containers, with an API for configuration and updates based on partition flips. The README describes its focus as security and maintainability, and says it is best used with a container orchestrator. ### What is a Bottlerocket AMI? It is the EC2 image produced from a Bottlerocket build. Artifacts are named for their architecture and variant, for example `bottlerocket-aws-k8s-1.32-x86_64--.img`, and `BUILDING.md` covers how to build an image and register an EC2 AMI from it. ### How do I use Bottlerocket on AWS? The README points to `QUICKSTART-EKS.md` for Amazon EKS and `QUICKSTART-ECS.md` for Amazon ECS, and the repository includes `sample-eksctl.yaml`. Because there is no shell, access goes through the control container, which requires the instance role to be able to read from ECR. ### What is Bottlerocket Linux? Bottlerocket is a Linux-based operating system built from standard open-source components, with Bottlerocket-specific additions focused on reliable updates and on the API. It is a container host rather than a general-purpose distribution, and the image has no SSH server and no shell. ## Sources - [bottlerocket-os/bottlerocket on GitHub](https://github.com/bottlerocket-os/bottlerocket) - [Issues](https://github.com/bottlerocket-os/bottlerocket/issues) - [Project website](https://bottlerocket.dev) - [README](https://github.com/bottlerocket-os/bottlerocket/blob/develop/README.md) - [Releases](https://github.com/bottlerocket-os/bottlerocket/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bottlerocket-os-bottlerocket