An operating system designed for hosting containers
An operating system designed for hosting containers
Welcome to Bottlerocket!
Bottlerocket is a free and open-source Linux-based operating system meant for hosting containers.
To learn more about Bottlerocket, visit the official Bottlerocket website and documentation. Otherwise, if you’re ready to jump right in, read one of our setup guides for running Bottlerocket in Amazon EKS, Amazon ECS, or VMware. If you're interested in running Bottlerocket on bare metal servers, please refer to the provisioning guide to get started.
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:
There are many ways to take part in the Bottlerocket community:
Join us on Meetup to hear about the latest Bottlerocket (virtual/in-person) events and community meetings. Community meetings are typically every other week.
Details can be found under the Events section on Meetup, and you will receive email notifications if you become a member of the Meetup group. (It's free to join!)
Start or join a discussion if you have questions about Bottlerocket.
If you're interested in contributing, thank you! Please see our contributor's guide.
If you find a security issue, please contact our security team rather than opening an issue.
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 or a discussion thread! You can let us know about things that seem difficult, or even ways you might like to help.
To start, we're focusing on the use of Bottlerocket as a host OS in AWS EKS Kubernetes clusters and Amazon ECS 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 x86_64 build of the aws-k8s-1.32 variant will produce an image named bottlerocket-aws-k8s-1.32-x86_64-<version>-<commit>.img.
The following variants support EKS, as described above:
aws-k8s-1.31aws-k8s-1.32aws-k8s-1.33aws-k8s-1.34aws-k8s-1.35aws-k8s-1.36aws-k8s-1.37aws-k8s-1.31-nvidiaaws-k8s-1.32-nvidiaaws-k8s-1.33-nvidiaaws-k8s-1.34-nvidiaaws-k8s-1.35-nvidiaaws-k8s-1.36-nvidiaaws-k8s-1.37-nvidiaThe following variants support ECS:
aws-ecs-2aws-ecs-2-nvidiaaws-ecs-3aws-ecs-3-fipsaws-ecs-3-nvidiaWe also have variants that are designed to be Kubernetes worker nodes in VMware:
vmware-k8s-1.31vmware-k8s-1.32vmware-k8s-1.33vmware-k8s-1.34vmware-k8s-1.35vmware-k8s-1.36vmware-k8s-1.37The following variants are no longer supported:
We recommend users replace nodes running these variants with the latest variant compatible with their cluster.
Our supported architectures include x86_64 and aarch64 (written as arm64 in some contexts).
:walking: :running:
Bottlerocket is best used with a container orchestrator. To get started with Kubernetes in Amazon EKS, please see QUICKSTART-EKS. To get started with Kubernetes in VMware, please see QUICKSTART-VMWARE. To get started with Amazon ECS, please see QUICKSTART-ECS. These guides describe:
To see how to provision Bottlerocket on bare metal, see PROVISIONING-METAL.
To build your own Bottlerocket images, please see BUILDING. It describes:
To publish your built Bottlerocket images, please see PUBLISHING. It describes:
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, debug problems, and generally explore.
Note: These methods require that your instance has permission to access the ECR repository where these containers live; the appropriate policy to add to your instance's IAM role is AmazonEC2ContainerRegistryReadOnly.
Bottlerocket has a "control" container, enabled by default, that runs outside of the orchestrator in a separate instance of containerd. This container runs the AWS SSM agent that lets you run commands, or start shell sessions, on Bottlerocket instances in EC2. (You can easily replace this control container with your own just by changing the URI; see Settings.)
In AWS, you need to give your instance the SSM role for this to work; see the setup guide. Outside of AWS, you can use AWS Systems Manager for hybrid environments. There's more detail about hybrid environments in the control container documentation.
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_ID --region REGION_CODE
With the default control container, you can make API calls to configure and manage your Bottlerocket host. To do even more, read the next section about the admin container. You can access the admin container from the control container like this:
enter-admin-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.
Outside of AWS, you can pass in your own SSH keys.
(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:
enable-admin-container
Or you can start an interactive session immediately like this:
enter-admin-container
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:
apiclient set host-containers.admin.enabled=true
Once you've enabled the admin container, you can either access it through SSH or execute commands from the control container like this:
apiclient exec admin bash
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.
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.
The update process uses images secured by TUF. For more details, see the update system documentation.
There are several ways of updating your Bottlerocket hosts. We provide tools for automatically updating hosts, as well as an API for direct control of updates.
For EKS variants of Bottlerocket, we recommend using the Bottlerocket update operator for automated updates.
For the ECS variant of Bottlerocket, we recommend using the Bottlerocket ECS updater for automated updates.
The Bottlerocket API includes methods for checking and starting system updates. You can read more about the update APIs in our update system documentation.
apiclient knows how to ha
No open issues yet, or sync has not completed.