# metal3-io/baremetal-operator architecture

> Architecture diagram of the GitHub repository metal3-io/baremetal-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metal3-io/baremetal-operator
- Repository: https://github.com/metal3-io/baremetal-operator

## Overview

Bare Metal Operator is a Kubernetes operator that manages bare-metal hosts through BareMetalHost resources. The principal workflow is a user submitting host intent to Kubernetes, after which the manager reconciles host state, invokes a provisioner for inspection or image provisioning, and reports status. Additional branches manage claims, preprovisioning images, firmware, network attachments, and BMC events. The README establishes the product capabilities; sampled source and the SOURCE INDEX show the manager, controllers, and Ironic integration. Some internal call paths are not shown, so uncertain links are omitted.

Main entry points: [`main.go`](https://github.com/metal3-io/baremetal-operator/blob/main/main.go) (Operator manager), [`internal/controller/metal3.io/baremetalhost_controller.go`](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/baremetalhost_controller.go) (Host reconciliation), [`pkg/provisioner/provisioner.go`](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/provisioner.go) (Provisioner interface), [`internal/controller/metal3.io/hostclaim_controller.go`](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostclaim_controller.go) (Claim reconciliation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Kubernetes API"]
  node_hostapi["Host resources"]
  node_otherapi["Related resources<br/>[hostclaim_types.go]"]
  node_webhooks["Admission validation"]
  node_hoststatus["Host status"]
end

subgraph group_reconcile["Reconciliation"]
  node_manager["Operator manager<br/>[main.go]"]
  node_hostcontroller["Host reconciliation"]
  node_claimcontroller["Claim reconciliation"]
  node_imagecontroller["Image reconciliation"]
  node_eventcontroller["BMC event reconciliation"]
  node_firmwarecontrollers["Firmware reconciliation"]
  node_firmwaresettings["Firmware settings"]
  node_dataimage["Data image reconciliation"]
  node_switchcontroller["Switch reconciliation"]
end

subgraph group_provision["Host Provisioning"]
  node_provisioner["Provisioner interface<br/>[provisioner.go]"]
  node_ironic["Ironic provisioner<br/>[ironic.go]"]
  node_bmc["BMC access<br/>[access.go]"]
  node_hardwaredetails["Hardware inspection<br/>[hardwaredetails.go]"]
end

subgraph group_support["Host Services"]
  node_claimmanager["Host selection"]
  node_imageprovider["Image building<br/>[default.go]"]
end

node_user(("Cluster user"))
node_kube(("Kubernetes API"))

node_user -->|"submits intent"| node_kube
node_kube -->|"validates changes"| node_webhooks
node_webhooks -->|"validates resource"| node_hostapi
node_manager -->|"registers controllers"| node_hostcontroller
node_manager -->|"registers controllers"| node_imagecontroller
node_manager -->|"registers controllers"| node_claimcontroller
node_manager -->|"registers controllers"| node_eventcontroller
node_manager -->|"registers controllers"| node_firmwarecontrollers
node_manager -->|"registers controllers"| node_firmwaresettings
node_manager -->|"registers controllers"| node_dataimage
node_manager -.->|"registers controllers"| node_switchcontroller
node_kube -->|"reconciles host"| node_hostcontroller
node_hostcontroller -.->|"invokes provisioning"| node_provisioner
node_provisioner -->|"implements interface"| node_ironic
node_ironic -->|"accesses BMC"| node_bmc
node_ironic -.->|"converts inventory"| node_hardwaredetails
node_hostcontroller -->|"reports host state"| node_hoststatus
node_hostcontroller -->|"creates image resource"| node_imagecontroller
node_imagecontroller -->|"builds image"| node_imageprovider
node_claimcontroller -->|"manages host claims"| node_claimmanager
node_claimcontroller -->|"reconciles claims"| node_otherapi
node_eventcontroller -->|"uses provisioner"| node_provisioner
node_firmwarecontrollers -->|"creates provisioner"| node_provisioner
node_firmwaresettings -->|"creates provisioner"| node_provisioner
node_hostcontroller -->|"reads host intent"| node_hostapi

click node_manager "https://github.com/metal3-io/baremetal-operator/blob/main/main.go"
click node_hostapi "https://github.com/metal3-io/baremetal-operator/blob/main/apis/metal3.io/v1alpha1/baremetalhost_types.go"
click node_otherapi "https://github.com/metal3-io/baremetal-operator/blob/main/apis/metal3.io/v1alpha1/hostclaim_types.go"
click node_webhooks "https://github.com/metal3-io/baremetal-operator/blob/main/internal/webhooks/metal3.io/v1alpha1/baremetalhost_webhook.go"
click node_hostcontroller "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/baremetalhost_controller.go"
click node_claimcontroller "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostclaim_controller.go"
click node_imagecontroller "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/controllers/preprovisioningimage_controller.go"
click node_eventcontroller "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/bmceventsubscription_controller.go"
click node_firmwarecontrollers "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostfirmwarecomponents_controller.go"
click node_firmwaresettings "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostfirmwaresettings_controller.go"
click node_dataimage "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/dataimage_controller.go"
click node_switchcontroller "https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/baremetalswitch_controller.go"
click node_claimmanager "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/hostclaim/hostclaim_manager.go"
click node_imageprovider "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/imageprovider/default.go"
click node_provisioner "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/provisioner.go"
click node_ironic "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/ironic/ironic.go"
click node_bmc "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/hardwareutils/bmc/access.go"
click node_hardwaredetails "https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/ironic/hardwaredetails/hardwaredetails.go"
click node_hoststatus "https://github.com/metal3-io/baremetal-operator/blob/main/apis/metal3.io/v1alpha1/baremetalhost_types.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_hostapi,node_otherapi,node_webhooks,node_hoststatus,node_user toneBlue
class node_manager,node_hostcontroller,node_claimcontroller,node_imagecontroller,node_eventcontroller,node_firmwarecontrollers,node_firmwaresettings,node_dataimage,node_switchcontroller toneAmber
class node_provisioner,node_ironic,node_bmc,node_hardwaredetails,node_kube toneMint
class node_claimmanager,node_imageprovider toneRose
```

## Components

### Kubernetes API

- [Host resources](https://github.com/metal3-io/baremetal-operator/blob/main/apis/metal3.io/v1alpha1/baremetalhost_types.go): `apis/metal3.io/v1alpha1/baremetalhost_types.go`
- [Related resources](https://github.com/metal3-io/baremetal-operator/blob/main/apis/metal3.io/v1alpha1/hostclaim_types.go): `apis/metal3.io/v1alpha1/hostclaim_types.go`
- [Admission validation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/webhooks/metal3.io/v1alpha1/baremetalhost_webhook.go): `internal/webhooks/metal3.io/v1alpha1/baremetalhost_webhook.go`
- [Host status](https://github.com/metal3-io/baremetal-operator/blob/main/apis/metal3.io/v1alpha1/baremetalhost_types.go): `apis/metal3.io/v1alpha1/baremetalhost_types.go`

### Reconciliation

- [Operator manager](https://github.com/metal3-io/baremetal-operator/blob/main/main.go): `main.go`
- [Host reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/baremetalhost_controller.go): `internal/controller/metal3.io/baremetalhost_controller.go`
- [Claim reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostclaim_controller.go): `internal/controller/metal3.io/hostclaim_controller.go`
- [Image reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/controllers/preprovisioningimage_controller.go): `pkg/controllers/preprovisioningimage_controller.go`
- [BMC event reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/bmceventsubscription_controller.go): `internal/controller/metal3.io/bmceventsubscription_controller.go`
- [Firmware reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostfirmwarecomponents_controller.go): `internal/controller/metal3.io/hostfirmwarecomponents_controller.go`
- [Firmware settings](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/hostfirmwaresettings_controller.go): `internal/controller/metal3.io/hostfirmwaresettings_controller.go`
- [Data image reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/dataimage_controller.go): `internal/controller/metal3.io/dataimage_controller.go`
- [Switch reconciliation](https://github.com/metal3-io/baremetal-operator/blob/main/internal/controller/metal3.io/baremetalswitch_controller.go): `internal/controller/metal3.io/baremetalswitch_controller.go`

### Host Provisioning

- [Provisioner interface](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/provisioner.go): `pkg/provisioner/provisioner.go`
- [Ironic provisioner](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/ironic/ironic.go): `pkg/provisioner/ironic/ironic.go`
- [BMC access](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/hardwareutils/bmc/access.go): `pkg/hardwareutils/bmc/access.go`
- [Hardware inspection](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/provisioner/ironic/hardwaredetails/hardwaredetails.go): `pkg/provisioner/ironic/hardwaredetails/hardwaredetails.go`

### Host Services

- [Host selection](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/hostclaim/hostclaim_manager.go): `pkg/hostclaim/hostclaim_manager.go`
- [Image building](https://github.com/metal3-io/baremetal-operator/blob/main/pkg/imageprovider/default.go): `pkg/imageprovider/default.go`

### Other components

- **Cluster user**
- **Kubernetes API**

## Connections

- Cluster user → Kubernetes API: submits intent
- Kubernetes API → Admission validation: validates changes
- Admission validation → Host resources: validates resource (evidence: `internal/webhooks/metal3.io/v1alpha1/baremetalhost_webhook.go`)
- Operator manager → Host reconciliation: registers controllers (evidence: `main.go`)
- Operator manager → Image reconciliation: registers controllers (evidence: `main.go`)
- Operator manager → Claim reconciliation: registers controllers (evidence: `main.go`)
- Operator manager → BMC event reconciliation: registers controllers (evidence: `main.go`)
- Operator manager → Firmware reconciliation: registers controllers (evidence: `main.go`)
- Operator manager → Firmware settings: registers controllers (evidence: `main.go`)
- Operator manager → Data image reconciliation: registers controllers (evidence: `main.go`)
- Operator manager → Switch reconciliation: registers controllers
- Kubernetes API → Host reconciliation: reconciles host
- Host reconciliation → Provisioner interface: invokes provisioning
- Provisioner interface → Ironic provisioner: implements interface
- Ironic provisioner → BMC access: accesses BMC (evidence: `pkg/provisioner/ironic/ironic.go`)
- Ironic provisioner → Hardware inspection: converts inventory
- Host reconciliation → Host status: reports host state (evidence: `internal/controller/metal3.io/baremetalhost_controller.go`)
- Host reconciliation → Image reconciliation: creates image resource (evidence: `internal/controller/metal3.io/baremetalhost_controller.go`)
- Image reconciliation → Image building: builds image (evidence: `pkg/controllers/preprovisioningimage_controller.go`)
- Claim reconciliation → Host selection: manages host claims (evidence: `internal/controller/metal3.io/hostclaim_controller.go`)
- Claim reconciliation → Related resources: reconciles claims (evidence: `internal/controller/metal3.io/hostclaim_controller.go`)
- BMC event reconciliation → Provisioner interface: uses provisioner (evidence: `internal/controller/metal3.io/bmceventsubscription_controller.go`)
- Firmware reconciliation → Provisioner interface: creates provisioner (evidence: `internal/controller/metal3.io/hostfirmwarecomponents_controller.go`)
- Firmware settings → Provisioner interface: creates provisioner (evidence: `internal/controller/metal3.io/hostfirmwaresettings_controller.go`)
- Host reconciliation → Host resources: reads host intent (evidence: `internal/controller/metal3.io/baremetalhost_controller.go`)
