# flatcar/mantle architecture

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

- Interactive diagram: https://gitdiagram.com/flatcar/mantle
- Repository: https://github.com/flatcar/mantle

## Overview

Mantle is a collection of Flatcar development utilities. The principal workflow is Kola’s user-invoked integration testing: configure a platform, launch machines, run tests, and report results. Separate branches cover provider operations through Ore, release and artifact indexing through Plume, and update-payload handling. The graph preserves major README capabilities; several subsystem connections are omitted or marked unverified because their implementation was not sampled.

Main entry points: [`kola/harness.go`](https://github.com/flatcar/mantle/blob/main/kola/harness.go) (Test runner), [`cmd/plume/plume.go`](https://github.com/flatcar/mantle/blob/main/cmd/plume/plume.go) (Plume CLI), [`kola/cluster/cluster.go`](https://github.com/flatcar/mantle/blob/main/kola/cluster/cluster.go) (Test cluster), [`platform/machine`](https://github.com/flatcar/mantle/tree/main/platform/machine) (Machine backends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kola["Kola testing"]
  node_kola_cli["Kola CLI<br/>[kola.go]"]
  node_kola_options["Run options<br/>[options.go]"]
  node_kola_runner["Test runner<br/>[harness.go]"]
  node_test_registry["Test registry<br/>[register.go]"]
  node_cluster["Test cluster<br/>[cluster.go]"]
  node_harness["Test harness<br/>[harness.go]"]
  node_kolet["Instance agent<br/>[kolet.go]"]
end

subgraph group_platforms["Machine platforms"]
  node_platform_api["Platform interface<br/>[platform.go]"]
  node_qemu["QEMU runtime<br/>[qemu.go]"]
  node_local_network["Local networking<br/>[dnsmasq.go]"]
  node_machine_backends["Machine backends"]
end

subgraph group_cloud["Cloud operations"]
  node_ore["Ore CLI<br/>[ore.go]"]
  node_provider_commands["Provider commands"]
  node_provider_apis["Provider APIs"]
  node_cloud_services(("Cloud providers"))
end

subgraph group_release["Release artifacts"]
  node_plume["Plume CLI<br/>[plume.go]"]
  node_prerelease["Pre-release<br/>[prerelease.go]"]
  node_release_command["Release publishing<br/>[release.go]"]
  node_index_command["Index generation<br/>[index.go]"]
  node_storage["Artifact storage<br/>[storage.go]"]
  node_storage_bucket["Storage bucket<br/>[bucket.go]"]
  node_index_job["Directory index<br/>[job.go]"]
end

subgraph group_updates["Update payloads"]
  node_payload_generator["Payload generator<br/>[generator.go]"]
  node_payload["Payload reader<br/>[payload.go]"]
  node_updater["Payload updater<br/>[updater.go]"]
  node_update_metadata["Update metadata"]
  node_signature["Payload signatures<br/>[signature.go]"]
end

node_user(("Developer"))

node_user -->|"runs tests"| node_kola_cli
node_kola_cli -->|"configures"| node_kola_options
node_kola_options -->|"sets options"| node_kola_runner
node_kola_runner -->|"runs suite"| node_harness
node_kola_runner -->|"registers tests"| node_test_registry
node_kola_runner -->|"creates cluster"| node_cluster
node_cluster -->|"uses test context"| node_harness
node_cluster -->|"uses platform"| node_platform_api
node_kola_runner -->|"selects platform"| node_platform_api
node_platform_api -.->|"implemented by"| node_machine_backends
node_machine_backends -.->|"may launch locally"| node_qemu
node_machine_backends -.->|"uses local services"| node_local_network
node_kola_runner -->|"deploys agent"| node_kolet
node_user -->|"runs provider commands"| node_ore
node_ore -.->|"dispatches commands"| node_provider_commands
node_provider_commands -.->|"uses provider API"| node_provider_apis
node_provider_apis -.->|"calls provider"| node_cloud_services
node_user -->|"runs release tools"| node_plume
node_plume -->|"starts pre-release"| node_prerelease
node_plume -->|"starts release"| node_release_command
node_plume -->|"starts indexing"| node_index_command
node_release_command -->|"publishes artifacts"| node_storage
node_index_command -->|"opens bucket"| node_storage_bucket
node_index_command -->|"runs index job"| node_index_job
node_storage_bucket -.->|"uses storage"| node_storage
node_payload_generator -->|"builds metadata"| node_update_metadata
node_payload_generator -->|"uses signatures"| node_signature
node_payload -->|"reads metadata"| node_update_metadata
node_payload -->|"verifies signatures"| node_signature

click node_kola_cli "https://github.com/flatcar/mantle/blob/main/cmd/kola/kola.go"
click node_kola_options "https://github.com/flatcar/mantle/blob/main/cmd/kola/options.go"
click node_kola_runner "https://github.com/flatcar/mantle/blob/main/kola/harness.go"
click node_test_registry "https://github.com/flatcar/mantle/blob/main/kola/register/register.go"
click node_cluster "https://github.com/flatcar/mantle/blob/main/kola/cluster/cluster.go"
click node_harness "https://github.com/flatcar/mantle/blob/main/harness/harness.go"
click node_kolet "https://github.com/flatcar/mantle/blob/main/cmd/kolet/kolet.go"
click node_platform_api "https://github.com/flatcar/mantle/blob/main/platform/platform.go"
click node_qemu "https://github.com/flatcar/mantle/blob/main/platform/qemu.go"
click node_local_network "https://github.com/flatcar/mantle/blob/main/platform/local/dnsmasq.go"
click node_machine_backends "https://github.com/flatcar/mantle/tree/main/platform/machine"
click node_ore "https://github.com/flatcar/mantle/blob/main/cmd/ore/ore.go"
click node_provider_commands "https://github.com/flatcar/mantle/tree/main/cmd/ore"
click node_provider_apis "https://github.com/flatcar/mantle/tree/main/platform/api"
click node_plume "https://github.com/flatcar/mantle/blob/main/cmd/plume/plume.go"
click node_prerelease "https://github.com/flatcar/mantle/blob/main/cmd/plume/prerelease.go"
click node_release_command "https://github.com/flatcar/mantle/blob/main/cmd/plume/release.go"
click node_index_command "https://github.com/flatcar/mantle/blob/main/cmd/plume/index.go"
click node_storage "https://github.com/flatcar/mantle/blob/main/storage/storage.go"
click node_storage_bucket "https://github.com/flatcar/mantle/blob/main/storage/bucket.go"
click node_index_job "https://github.com/flatcar/mantle/blob/main/storage/index/job.go"
click node_payload_generator "https://github.com/flatcar/mantle/blob/main/update/generator/generator.go"
click node_payload "https://github.com/flatcar/mantle/blob/main/update/payload.go"
click node_updater "https://github.com/flatcar/mantle/blob/main/update/updater.go"
click node_update_metadata "https://github.com/flatcar/mantle/blob/main/update/metadata/update_metadata.proto"
click node_signature "https://github.com/flatcar/mantle/blob/main/update/signature/signature.go"

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_kola_cli,node_kola_options,node_kola_runner,node_test_registry,node_cluster,node_harness,node_kolet toneBlue
class node_platform_api,node_qemu,node_local_network,node_machine_backends toneAmber
class node_ore,node_provider_commands,node_provider_apis,node_cloud_services toneMint
class node_plume,node_prerelease,node_release_command,node_index_command,node_storage,node_storage_bucket,node_index_job toneRose
class node_payload_generator,node_payload,node_updater,node_update_metadata,node_signature,node_user toneIndigo
```

## Components

### Kola testing

- [Kola CLI](https://github.com/flatcar/mantle/blob/main/cmd/kola/kola.go): `cmd/kola/kola.go`
- [Run options](https://github.com/flatcar/mantle/blob/main/cmd/kola/options.go): `cmd/kola/options.go`
- [Test runner](https://github.com/flatcar/mantle/blob/main/kola/harness.go): `kola/harness.go`
- [Test registry](https://github.com/flatcar/mantle/blob/main/kola/register/register.go): `kola/register/register.go`
- [Test cluster](https://github.com/flatcar/mantle/blob/main/kola/cluster/cluster.go): `kola/cluster/cluster.go`
- [Test harness](https://github.com/flatcar/mantle/blob/main/harness/harness.go): `harness/harness.go`
- [Instance agent](https://github.com/flatcar/mantle/blob/main/cmd/kolet/kolet.go): `cmd/kolet/kolet.go`

### Machine platforms

- [Platform interface](https://github.com/flatcar/mantle/blob/main/platform/platform.go): `platform/platform.go`
- [QEMU runtime](https://github.com/flatcar/mantle/blob/main/platform/qemu.go): `platform/qemu.go`
- [Local networking](https://github.com/flatcar/mantle/blob/main/platform/local/dnsmasq.go): `platform/local/dnsmasq.go`
- [Machine backends](https://github.com/flatcar/mantle/tree/main/platform/machine): `platform/machine`

### Cloud operations

- [Ore CLI](https://github.com/flatcar/mantle/blob/main/cmd/ore/ore.go): `cmd/ore/ore.go`
- [Provider commands](https://github.com/flatcar/mantle/tree/main/cmd/ore): `cmd/ore`
- [Provider APIs](https://github.com/flatcar/mantle/tree/main/platform/api): `platform/api`
- **Cloud providers**

### Release artifacts

- [Plume CLI](https://github.com/flatcar/mantle/blob/main/cmd/plume/plume.go): `cmd/plume/plume.go`
- [Pre-release](https://github.com/flatcar/mantle/blob/main/cmd/plume/prerelease.go): `cmd/plume/prerelease.go`
- [Release publishing](https://github.com/flatcar/mantle/blob/main/cmd/plume/release.go): `cmd/plume/release.go`
- [Index generation](https://github.com/flatcar/mantle/blob/main/cmd/plume/index.go): `cmd/plume/index.go`
- [Artifact storage](https://github.com/flatcar/mantle/blob/main/storage/storage.go): `storage/storage.go`
- [Storage bucket](https://github.com/flatcar/mantle/blob/main/storage/bucket.go): `storage/bucket.go`
- [Directory index](https://github.com/flatcar/mantle/blob/main/storage/index/job.go): `storage/index/job.go`

### Update payloads

- [Payload generator](https://github.com/flatcar/mantle/blob/main/update/generator/generator.go): `update/generator/generator.go`
- [Payload reader](https://github.com/flatcar/mantle/blob/main/update/payload.go): `update/payload.go`
- [Payload updater](https://github.com/flatcar/mantle/blob/main/update/updater.go): `update/updater.go`
- [Update metadata](https://github.com/flatcar/mantle/blob/main/update/metadata/update_metadata.proto): `update/metadata/update_metadata.proto`
- [Payload signatures](https://github.com/flatcar/mantle/blob/main/update/signature/signature.go): `update/signature/signature.go`

### Other components

- **Developer**

## Connections

- Developer → Kola CLI: runs tests
- Kola CLI → Run options: configures (evidence: `cmd/kola/options.go`)
- Run options → Test runner: sets options (evidence: `cmd/kola/options.go`)
- Test runner → Test harness: runs suite (evidence: `kola/harness.go`)
- Test runner → Test registry: registers tests (evidence: `kola/harness.go`)
- Test runner → Test cluster: creates cluster (evidence: `kola/harness.go`)
- Test cluster → Test harness: uses test context (evidence: `kola/cluster/cluster.go`)
- Test cluster → Platform interface: uses platform (evidence: `kola/cluster/cluster.go`)
- Test runner → Platform interface: selects platform (evidence: `kola/harness.go`)
- Platform interface → Machine backends: implemented by
- Machine backends → QEMU runtime: may launch locally
- Machine backends → Local networking: uses local services
- Test runner → Instance agent: deploys agent (evidence: `kola/harness.go`)
- Developer → Ore CLI: runs provider commands
- Ore CLI → Provider commands: dispatches commands
- Provider commands → Provider APIs: uses provider API
- Provider APIs → Cloud providers: calls provider
- Developer → Plume CLI: runs release tools
- Plume CLI → Pre-release: starts pre-release
- Plume CLI → Release publishing: starts release
- Plume CLI → Index generation: starts indexing (evidence: `cmd/plume/index.go`)
- Release publishing → Artifact storage: publishes artifacts
- Index generation → Storage bucket: opens bucket (evidence: `cmd/plume/index.go`)
- Index generation → Directory index: runs index job (evidence: `cmd/plume/index.go`)
- Storage bucket → Artifact storage: uses storage
- Payload generator → Update metadata: builds metadata (evidence: `update/generator/generator.go`)
- Payload generator → Payload signatures: uses signatures (evidence: `update/generator/generator.go`)
- Payload reader → Update metadata: reads metadata (evidence: `update/payload.go`)
- Payload reader → Payload signatures: verifies signatures (evidence: `update/payload.go`)
