HetznerBareMetalMachineTemplate

In HetznerBareMetalMachineTemplate you can define all important properties for the HetznerBareMetalMachines. HetznerBareMetalMachines are reconciled by the HetznerBareMetalMachineController, which DOES NOT create or delete Hetzner dedicated machines. Instead, it uses the inventory of HetznerBareMetalHosts. These hosts correspond to already existing bare metal servers, which get provisioned when selected by a HetznerBareMetalMachine.

Lifecycle of a HetznerBareMetalMachine

Creating a HetznerBareMetalMachine

Simply put, the specs of a HetznerBareMetalMachine consist of two parts. First, there is information about how the bare metal server is supposed to be provisioned. Second, there are properties where you can specify which host to select. If these selectors correspond to a host that is not consumed yet, then the HetznerBareMetalMachine transfers important information to the host object. This information is used to provision the host according to what you specified in the specs of HetznerBareMetalMachineTemplate. If a host has provisioned successfully, then the HetznerBareMetalMachine is considered to be ready.

Deleting of a HetznerBareMetalMachine

When the HetznerBareMetalMachine object gets deleted, it removes the information from the host that the latter used for provisioning. The host then triggers the deprovisioning. As soon as this has been completed, the HetznerBareMetalMachineController removes the owner and consumer reference of the host and deletes the finalizer of the machine, so that it can be finally deleted.

Updating a HetznerBareMetalMachine

Updating a HetznerBareMetalMachineTemplate is not possible. Instead, a new template should be created.

cloud-init and installimage

Both in installimage⁠ and cloud-init the ports used for SSH can be changed, e.g. with the following code snippet:

		sed -i -e '/^\(#\|\)Port/s/^.*$/Port 2223/' /etc/ssh/sshd_config
	

As the controller needs to know this to be able to successfully provision the server, these ports can be specified in SSHSpec of HetznerBareMetalMachineTemplate.

When the port is changed in cloud-init, then we additionally need to use the following command to make sure that the change of ports takes immediate effect: systemctl restart sshd

Choosing the right host

Via MatchLabels you can specify a certain label (key and value) that identifies the host. You get more flexibility with MatchExpressions. This allows decisions like "take any host that has the key "mykey" and let this key have either one of the values "val1", "val2", and "val3".

Overview of HetznerBareMetalMachineTemplate.Spec

installImage.image

You must specify either:

• name and url
• path
• url and imageURLCommand

Example of an image provided by Hetzner via NFS:

		image:
  path: /root/.oldroot/nfs//images/Ubuntu-2404-noble-amd64-base.tar.zst
	

Example of an image provided by you via https. The script installimage of Hetzner parses the name to detect the version. It is recommended to follow their naming pattern.

		image:
  name: Ubuntu-2404-noble-amd64-custom
  url: https://user:pwd@example.com/images/Ubuntu-2404-noble-amd64-custom.tar.gz
	

Example of pulling an image from an oci-registry:

		image:
  name: Ubuntu-2404-noble-amd64-custom
  url: oci://ghcr.io/myorg/images/Ubuntu-2404-noble-amd64-custom:1.0.1
	

If you need credentials to pull the image, then provide the environment variable OCI_REGISTRY_AUTH_TOKEN to the controller.

You can provide the variable via a secret of the deployment caph-controller-manager:

		apiVersion: apps/v1
kind: Deployment
metadata:
  # ...
spec:
  # ...
  template:
    spec:
      containers:
        - command:
            - /manager
          image: ghcr.io/syself/caph:vXXX
          env:
            - name: OCI_REGISTRY_AUTH_TOKEN
              valueFrom:
                secretKeyRef:
                  name: my-oci-registry-secret # The name of the secret
                  key: OCI_REGISTRY_AUTH_TOKEN # The key in the secret. Format: "user:pwd" or just "token"
      # ... other container specs
	

You can push an image to an oci-registry with a tool like oras⁠:

		oras push ghcr.io/myorg/images/Ubuntu-2404-noble-amd64-custom:1.0.1 \
    --artifact-type application/vnd.myorg.machine-image.v1 Ubuntu-2404-noble-amd64-custom.tar.gz
	

Example of provisioning a bare metal machine via a custom image-url-command:

		imageURLCommand: image-url-command-install-foo.sh
image:
  url: oci://ghcr.io/myorg/images/Ubuntu-2404-noble-amd64-custom:1.0.1
	

In this mode, name and path must be empty.