CRD Reference

API reference for the Machine custom resource.

API group: unbounded-cloud.io/v1alpha3

This document describes the custom resource definition shipped with the project: Machine.

Machine

Printer columns:

spec.ssh

SSH connection details. When ssh is nil, the machina controller skips the Machine entirely.

spec.pxe

PXE boot configuration consumed by the metalman controller.

spec.kubernetes

Kubernetes join configuration.

spec.operations

status

Conditions

Phase lifecycle

The machina controller drives the following phases:

Labels and annotations

Labels:

Annotations:

Examples

Minimal SSH-only Machine:

apiVersion: unbounded-cloud.io/v1alpha3
kind: Machine
metadata:
  name: worker-01
spec:
  ssh:
    host: "10.0.0.50"
    privateKeyRef:
      name: ssh-key
      namespace: unbounded-kube
  kubernetes:
    version: v1.34.0
    bootstrapTokenRef:
      name: bootstrap-token-abc123

SSH with bastion:

apiVersion: unbounded-cloud.io/v1alpha3
kind: Machine
metadata:
  name: worker-02
spec:
  ssh:
    host: "192.168.1.100:2222"
    username: ubuntu
    privateKeyRef:
      name: ssh-key
      namespace: unbounded-kube
      key: id_ed25519
    bastion:
      host: "bastion.example.com"
      username: jump
  kubernetes:
    version: v1.34.0
    bootstrapTokenRef:
      name: bootstrap-token-abc123

PXE / bare-metal Machine:

apiVersion: unbounded-cloud.io/v1alpha3
kind: Machine
metadata:
  name: baremetal-01
  labels:
    unbounded-cloud.io/site: lab
spec:
  ssh:
    host: "10.0.0.60"
    privateKeyRef:
      name: ssh-key
      namespace: unbounded-kube
  pxe:
    image: ghcr.io/azure/images/host-ubuntu2404:v1
    dhcpLeases:
    - ipv4: "10.0.0.60"
      mac: "aa:bb:cc:dd:ee:ff"
      subnetMask: "255.255.255.0"
      gateway: "10.0.0.1"
      dns:
      - "8.8.8.8"
    redfish:
      url: "https://bmc-01.example.com"
      username: admin
      passwordRef:
        name: bmc-password
        namespace: unbounded-kube
    cloudInit:
      userDataConfigMapRef:
        name: my-cloud-init
        namespace: unbounded-kube
  kubernetes:
    version: v1.34.0
    bootstrapTokenRef:
      name: bootstrap-token-abc123

Netboot OCI Images

Netboot images are standard OCI container images built FROM scratch that contain all files needed for PXE booting a machine under /disk/. This follows the kubevirt containerDisk convention.

Files with a .tmpl suffix are Go templates rendered per-machine at serve time; other files are served verbatim. A metadata.yaml file provides image-level configuration (e.g. dhcpBootImageName).

Image layout

Template data

Templates receive the following data object:

Building images

Images are built, tagged, and pushed using standard container tooling:

docker build -t ghcr.io/azure/images/host-ubuntu2404:v1 .
docker push ghcr.io/azure/images/host-ubuntu2404:v1

See images/host-ubuntu2404/ for an example Containerfile.

metadata.yaml

dhcpBootImageName: shimx64.efi

The dhcpBootImageName field specifies the boot filename included in DHCP responses (option 67).

CRD relationships

See Also

• SSH Guide – SSH provisioning walkthrough using these CRDs.
• PXE Guide – Bare-metal provisioning walkthrough using Machine and OCI netboot images.
• Networking CRDs – Site, GatewayPool, and related CRDs from unbounded-net.
• CLI Reference – The kubectl unbounded commands that create these resources.
• Architecture – How these CRDs drive the provisioning pipelines.