You are viewing documentation for version 1.17.x. The most current version is 1.19.x.  This documentation is available for 1.19.x.

Host Containers

Special purpose, non-orchestrated containers for node management and administration

Host containers are a special type of container you can use to manage and administer your Bottlerocket node. These containers are non-orchestrated, which means Kubernetes or ECS are unaware of these containers and cannot directly manage their lifecycle. Instead you manage the lifecycle of these containers by manipulating specific Bottlerocket settings with the API.

Built-in host containers

Depending on the variant, Bottlerocket has two standard host containers: the control container and the admin container. The control container provides a pathway to connect (via SSM) to and interact with the host as well as conveniently access the Bottlerocket API. The control container also provides an entry point to the admin container. The admin container allows you to more deeply interact with the host as it mounts the root filesystem and has elevated privileges.

The control and admin containers are not actually special: both are just host containers with specific privileges. Case in point, you can disable (and re-enable) these containers as-needed and you can even fully replace the functionality of both the host and admins containers with your own host containers.

Properties of host containers

Host containers have a number of different properties from orchestrated containers.


Bottlerocket has two parallel instances of containerd: one for your orchestrated workloads and one for host containers.

API Access

All host containers automatically mount the API socket (/run/api.sock) and the API Client (/usr/local/bin/apiclient). This allows you to run API commands and manipulate Bottlerocket settings from within the host containers without explicitly mounting these resources. As a consequence, any user that can access a host container can change configurations which could effect the efficiency or stability of the node.

Lifecycle & restarts

Host containers start and stop based on the value of their enabled setting. If a host container exits, Bottlerocket automatically restarts the container after 45 seconds.


Host containers can have high levels of privilege. See<container>.superpowered for more details.


Host containers do not update automatically. Updates only occur when you update the<container>.source or when an in-place update occurs.

User data

Distinct, but inspired by instance user data, host containers pass arbitrary1 base64-encoded data from the API into a file2.

Persistent storage

All host containers have persistent storage that survive node reboots as well as container stop/start cycles2.

Use Cases

When considering if you should use a host container, evaluate the specific properties of host containers and if you need to manage the lifecycle with your orchestrator. Generally, you should try to solve your problem with an orchestrated container and only turn to a host container for low-level use-cases.


  • The control container is a host container because it needs to be available early to give you access to the OS.
  • The admin container is a host container because it needs high levels of privilege and you may need it to debug when orchestration isn’t working

Also See

See a problem with this page? File an issue. All feedback is appreciated.
You can also directly contribute a change to the source file of this page on GitHub.

  1. The admin container has a special uses for user data. See the warning on<container>.user-data ↩︎

  2. Paths for persistent storage and user data (<HOST_CONTAINER_NAME> being the name of the host container):

    • /.bottlerocket/host-containers/<HOST_CONTAINER_NAME> and /.bottlerocket/host-containers/<HOST_CONTAINER_NAME>/user-data
    • /.bottlerocket/host-containers/current and /.bottlerocket/host-containers/current/user-data
     ↩︎ ↩︎