alauda · wgkingk · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/docs/en/apis/providers/bare-metal/baremetalcluster.mdx b/docs/en/apis/providers/bare-metal/baremetalcluster.mdx
@@ -0,0 +1,8 @@
+---
+weight: 10
+---
+
+# BaremetalCluster [infrastructure.cluster.x-k8s.io/v1beta1]
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="baremetalclusters.infrastructure.cluster.x-k8s.io" />
diff --git a/docs/en/apis/providers/bare-metal/baremetalmachine.mdx b/docs/en/apis/providers/bare-metal/baremetalmachine.mdx
@@ -0,0 +1,8 @@
+---
+weight: 20
+---
+
+# BaremetalMachine [infrastructure.cluster.x-k8s.io/v1beta1]
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="baremetalmachines.infrastructure.cluster.x-k8s.io" />
diff --git a/docs/en/apis/providers/bare-metal/baremetalmachinetemplate.mdx b/docs/en/apis/providers/bare-metal/baremetalmachinetemplate.mdx
@@ -0,0 +1,8 @@
+---
+weight: 30
+---
+
+# BaremetalMachineTemplate [infrastructure.cluster.x-k8s.io/v1beta1]
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="baremetalmachinetemplates.infrastructure.cluster.x-k8s.io" />
diff --git a/docs/en/apis/providers/bare-metal/index.mdx b/docs/en/apis/providers/bare-metal/index.mdx
@@ -6,14 +6,37 @@ weight: 40
 
 <Overview />
 
-## Status
+The Bare Metal Infrastructure Provider builds on `elemental-operator` and Cluster API. Operators interact with two CRD groups, both documented here:
 
-📋 **Planned**
+- `infrastructure.cluster.x-k8s.io/v1beta1` — the provider's own resources.
+- `elemental.cattle.io/v1beta1` — owned by `elemental-operator`; the provider only reads and annotates them, but operators must author the registration/seed objects and inspect inventory objects on every workflow.
 
-API documentation will be available when development begins.
+## Custom Resources
 
-## Planned Resources
+### Provider resources (`infrastructure.cluster.x-k8s.io/v1beta1`)
 
-- `MetalCluster`: Represents a Kubernetes cluster infrastructure on bare metal
-- `MetalMachine`: Represents a bare metal server
-- `MetalMachineTemplate`: Template for configuring bare metal servers
+| Resource | Description | Documentation |
+|---|---|---|
+| `BaremetalCluster` | Cluster-level infrastructure: control-plane VIP, endpoint, network type. | [BaremetalCluster](./baremetalcluster.mdx) |
+| `BaremetalMachine` | Single infra machine bound to one `MachineInventory`. | [BaremetalMachine](./baremetalmachine.mdx) |
+| `BaremetalMachineTemplate` | Template that binds a pool to a `KubeadmControlPlane` or `MachineDeployment`. | [BaremetalMachineTemplate](./baremetalmachinetemplate.mdx) |
+| `MachineInventoryPool` | Allowed set of `MachineInventory` names for a cluster. | [MachineInventoryPool](./machineinventorypool.mdx) |
+
+### Elemental resources (`elemental.cattle.io/v1beta1`)
+
+| Resource | Description | Documentation |
+|---|---|---|
+| `MachineRegistration` | Registration URL + first-install cloud-config. Authored once per cluster. | [MachineRegistration](./machineregistration.mdx) |
+| `SeedImage` | Triggers ISO build with the registration baked in. | [SeedImage](./seedimage.mdx) |
+| `MachineInventory` | Long-lived host identity; consumed by `MachineInventoryPool`. The provider also reads `spec.observedNetwork` (Alauda-fork-only) and writes the `baremetal.alauda.io/*` annotations. | [MachineInventory](./machineinventory.mdx) |
+
+## Upstream Cluster API resources
+
+The provider also composes the following upstream resources without changing their schemas. Refer to the [Cluster API reference](../../cluster_api/) for full schemas.
+
+| Resource | API group | Purpose |
+|---|---|---|
+| `Cluster` | `cluster.x-k8s.io/v1beta1` | Top-level CAPI resource; carries the bare-metal-specific `cpaas.io/*` annotations. |
+| `KubeadmControlPlane` | `controlplane.cluster.x-k8s.io/v1beta1` | Owns control-plane `Machine` lifecycle and kubeadm config. |
+| `MachineDeployment` | `cluster.x-k8s.io/v1beta1` | Owns worker `Machine` lifecycle. |
+| `KubeadmConfigTemplate` | `bootstrap.cluster.x-k8s.io/v1beta1` | Worker cloud-init `user-data` template. |
diff --git a/docs/en/apis/providers/bare-metal/machineinventory.mdx b/docs/en/apis/providers/bare-metal/machineinventory.mdx
@@ -0,0 +1,17 @@
+---
+weight: 70
+---
+
+# MachineInventory [elemental.cattle.io/v1beta1]
+
+`MachineInventory` is the long-lived identity object for a physical host. It is created by `elemental-register` after a host boots the seed ISO, and it survives reprovisioning — `BaremetalMachine` only borrows it for the lifetime of one Kubernetes node.
+
+The bare-metal provider reads two parts of this resource:
+
+- `metadata.name` — must appear in a `MachineInventoryPool.spec.inventoryNames` entry for the host to be allocatable.
+- `spec.observedNetwork` — an Alauda-fork-only field captured during registration; the provider replays it as cloud-init `network-config` v2 on every reprovision, so the host comes back with the same interface/bond/VLAN/IP layout as when it was first inventoried.
+
+The provider also writes `metadata.annotations` (`baremetal.alauda.io/owner-*`, `baremetal.alauda.io/plan.type`) and updates `status.plan` / `status.conditions` during clean/reprovision.
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="machineinventories.elemental.cattle.io" />
diff --git a/docs/en/apis/providers/bare-metal/machineinventorypool.mdx b/docs/en/apis/providers/bare-metal/machineinventorypool.mdx
@@ -0,0 +1,8 @@
+---
+weight: 40
+---
+
+# MachineInventoryPool [infrastructure.cluster.x-k8s.io/v1beta1]
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="machineinventorypools.infrastructure.cluster.x-k8s.io" />
diff --git a/docs/en/apis/providers/bare-metal/machineregistration.mdx b/docs/en/apis/providers/bare-metal/machineregistration.mdx
@@ -0,0 +1,10 @@
+---
+weight: 50
+---
+
+# MachineRegistration [elemental.cattle.io/v1beta1]
+
+`MachineRegistration` is owned by `elemental-operator` and is created once per workload cluster. The bare-metal provider does not mutate it, but operators must author it because its `config` block is baked into the registration ISO and replayed by `elemental-register` on first boot — it carries the registration URL, MachineInventoryLabels, and the cloud-init that turns a freshly imaged host into a usable `MachineInventory`.
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="machineregistrations.elemental.cattle.io" />
diff --git a/docs/en/apis/providers/bare-metal/seedimage.mdx b/docs/en/apis/providers/bare-metal/seedimage.mdx
@@ -0,0 +1,10 @@
+---
+weight: 60
+---
+
+# SeedImage [elemental.cattle.io/v1beta1]
+
+`SeedImage` is owned by `elemental-operator`. Creating one references a `MachineRegistration` and triggers the operator to build an ISO with the registration URL embedded; operators download that ISO and boot bare-metal hosts from it. The resulting `MachineInventory` objects are what `MachineInventoryPool` allocates to `BaremetalMachine`.
+
+{/* cspell:disable-next-line */}
+<K8sCrd name="seedimages.elemental.cattle.io" />