# bottlerocket-os/bottlerocket architecture

> Architecture diagram of the GitHub repository bottlerocket-os/bottlerocket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bottlerocket-os/bottlerocket
- Repository: https://github.com/bottlerocket-os/bottlerocket
- Video tour (about a minute): https://gitdiagram.com/bottlerocket-os/bottlerocket/video

## Overview

Bottlerocket is a Linux host OS for container workloads. Its documented settings workflow is to change system configuration through the API, with settings modeled and migrated across OS updates. The tree shows datastore implementations and many versioned migration programs, but not the API service, update orchestrator, or their runtime wiring; those links are therefore not inferred. Defaults and variant-specific configuration are also represented by the repository tree. The README’s partition-flip update mechanism and security design have no corresponding implementation paths in the supplied tree.

Main entry points: [`sources/api/datastore/src/lib.rs`](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/lib.rs) (Datastore API), [`sources/settings-migrations`](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-migrations) (Versioned migrations), [`sources/settings-defaults`](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-defaults) (Variant defaults), [`sources/settings-plugins`](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-plugins) (Settings plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Settings configuration"]
  node_settings_api["Settings API"]
  node_defaults["Variant defaults"]
  node_plugins["Settings plugins"]
end

subgraph group_storage["Datastore library"]
  node_datastore["Datastore API<br/>[lib.rs]"]
  node_memory_store[("Memory store<br/>[memory.rs]")]
  node_filesystem_store[("Filesystem store<br/>[filesystem.rs]")]
  node_key_validation["Key validation<br/>[key.rs]"]
  node_serialization["Serialization<br/>[mod.rs]"]
  node_deserialization["Deserialization<br/>[mod.rs]"]
end

subgraph group_migration["Settings migrations"]
  node_migration_programs["Versioned migrations"]
  node_registry_migration["Registry settings<br/>[main.rs]"]
  node_dns_migration["DNS settings<br/>[main.rs]"]
  node_plugin_migration["Verifier plugins<br/>[main.rs]"]
  node_device_migration["Device plugin settings<br/>[main.rs]"]
end

subgraph group_capabilities["OS capabilities"]
  node_partition_updates["Partition-flip updates"]
  node_container_host["Container host OS"]
end

node_operator(("Operator or orchestrator"))
node_workloads["Container workloads"]

node_operator -->|"changes settings"| node_settings_api
node_settings_api -->|"accesses settings"| node_datastore
node_defaults -.->|"provides defaults"| node_datastore
node_plugins -.->|"extends settings"| node_datastore
node_datastore -->|"uses backend"| node_memory_store
node_datastore -->|"uses backend"| node_filesystem_store
node_datastore -->|"validates keys"| node_key_validation
node_datastore -->|"serializes data"| node_serialization
node_datastore -->|"deserializes data"| node_deserialization
node_partition_updates -->|"runs migrations"| node_migration_programs
node_migration_programs -->|"includes migration"| node_registry_migration
node_migration_programs -->|"includes migration"| node_dns_migration
node_migration_programs -->|"includes migration"| node_plugin_migration
node_migration_programs -->|"includes migration"| node_device_migration
node_partition_updates -->|"updates OS"| node_container_host
node_container_host -->|"hosts workloads"| node_workloads

click node_defaults "https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-defaults"
click node_plugins "https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-plugins"
click node_datastore "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/lib.rs"
click node_memory_store "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/memory.rs"
click node_filesystem_store "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/filesystem.rs"
click node_key_validation "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/key.rs"
click node_serialization "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/serialization/mod.rs"
click node_deserialization "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/deserialization/mod.rs"
click node_migration_programs "https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-migrations"
click node_registry_migration "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/archived/v1.4.0/registry-mirror-representation/src/main.rs"
click node_dns_migration "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/archived/v1.8.0/cluster-dns-ip-list/src/main.rs"
click node_plugin_migration "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/v1.56.0/image-verifier-plugins-extensible/src/main.rs"
click node_device_migration "https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/v1.40.0/kubelet-device-plugins-cdi-settings/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_settings_api,node_defaults,node_plugins toneBlue
class node_datastore,node_memory_store,node_filesystem_store,node_key_validation,node_serialization,node_deserialization toneAmber
class node_migration_programs,node_registry_migration,node_dns_migration,node_plugin_migration,node_device_migration toneMint
class node_partition_updates,node_container_host toneRose
class node_operator,node_workloads toneIndigo
```

## Components

### Settings configuration

- **Settings API**
- [Variant defaults](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-defaults): `sources/settings-defaults`
- [Settings plugins](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-plugins): `sources/settings-plugins`

### Datastore library

- [Datastore API](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/lib.rs): `sources/api/datastore/src/lib.rs`
- [Memory store](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/memory.rs): `sources/api/datastore/src/memory.rs`
- [Filesystem store](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/filesystem.rs): `sources/api/datastore/src/filesystem.rs`
- [Key validation](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/key.rs): `sources/api/datastore/src/key.rs`
- [Serialization](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/serialization/mod.rs): `sources/api/datastore/src/serialization/mod.rs`
- [Deserialization](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/datastore/src/deserialization/mod.rs): `sources/api/datastore/src/deserialization/mod.rs`

### Settings migrations

- [Versioned migrations](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/settings-migrations): `sources/settings-migrations`
- [Registry settings](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/archived/v1.4.0/registry-mirror-representation/src/main.rs): `sources/settings-migrations/archived/v1.4.0/registry-mirror-representation/src/main.rs`
- [DNS settings](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/archived/v1.8.0/cluster-dns-ip-list/src/main.rs): `sources/settings-migrations/archived/v1.8.0/cluster-dns-ip-list/src/main.rs`
- [Verifier plugins](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/v1.56.0/image-verifier-plugins-extensible/src/main.rs): `sources/settings-migrations/v1.56.0/image-verifier-plugins-extensible/src/main.rs`
- [Device plugin settings](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/settings-migrations/v1.40.0/kubelet-device-plugins-cdi-settings/src/main.rs): `sources/settings-migrations/v1.40.0/kubelet-device-plugins-cdi-settings/src/main.rs`

### OS capabilities

- **Partition-flip updates**
- **Container host OS**

### Other components

- **Operator or orchestrator**
- **Container workloads**

## Connections

- Operator or orchestrator → Settings API: changes settings
- Settings API → Datastore API: accesses settings
- Variant defaults → Datastore API: provides defaults
- Settings plugins → Datastore API: extends settings
- Datastore API → Memory store: uses backend
- Datastore API → Filesystem store: uses backend
- Datastore API → Key validation: validates keys
- Datastore API → Serialization: serializes data
- Datastore API → Deserialization: deserializes data
- Partition-flip updates → Versioned migrations: runs migrations
- Versioned migrations → Registry settings: includes migration
- Versioned migrations → DNS settings: includes migration
- Versioned migrations → Verifier plugins: includes migration
- Versioned migrations → Device plugin settings: includes migration
- Partition-flip updates → Container host OS: updates OS
- Container host OS → Container workloads: hosts workloads