WIP

Signed-off-by: Lennart Jern <[email protected]>

Author: lentzi90

docs/user-guide/examples/kind.yaml

@@ -0,0 +1,16 @@
+apiVersion: kind.x-k8s.io/v1alpha4
+kind: Cluster
+nodes:
+- role: control-plane
+  # Open ports for Ironic
+  extraPortMappings:
+  # Ironic httpd
+  - containerPort: 6180
+    hostPort: 6180
+    listenAddress: "0.0.0.0"
+    protocol: TCP
+  # Ironic API
+  - containerPort: 6385
+    hostPort: 6385
+    listenAddress: "0.0.0.0"
+    protocol: TCP

docs/user-guide/examples/net.xml

@@ -0,0 +1,15 @@
+<network>
+  <name>baremetal-e2e</name>
+  <forward mode='nat'>
+    <nat>
+      <port start='1024' end='65535'/>
+    </nat>
+  </forward>
+  <bridge name='metal3'/>
+  <ip address='192.168.222.1' netmask='255.255.255.0'>
+    <dhcp>
+      <range start='192.168.222.3' end='192.168.222.99'/>
+      <bootp file='http://192.168.222.2:6180/boot.ipxe'/>
+    </dhcp>
+  </ip>
+</network>

docs/user-guide/examples/sushy-emulator.conf

@@ -0,0 +1,36 @@
+# Listen on the local IP address 192.168.222.1
+SUSHY_EMULATOR_LISTEN_IP = u'192.168.222.1'
+
+# Bind to TCP port 8000
+SUSHY_EMULATOR_LISTEN_PORT = 8000
+
+# Serve this SSL certificate to the clients
+SUSHY_EMULATOR_SSL_CERT = None
+
+# If SSL certificate is being served, this is its RSA private key
+SUSHY_EMULATOR_SSL_KEY = None
+
+# The OpenStack cloud ID to use. This option enables OpenStack driver.
+SUSHY_EMULATOR_OS_CLOUD = None
+# The libvirt URI to use. This option enables libvirt driver.
+SUSHY_EMULATOR_LIBVIRT_URI = u'qemu:///system'
+
+# Instruct the libvirt driver to ignore any instructions to
+# set the boot device. Allowing the UEFI firmware to instead
+# rely on the EFI Boot Manager
+# Note: This sets the legacy boot element to dev="fd"
+# and relies on the floppy not existing, it likely wont work
+# your VM has a floppy drive.
+SUSHY_EMULATOR_IGNORE_BOOT_DEVICE = False
+
+# The map of firmware loaders dependant on the boot mode and
+# system architecture. Ideally the x86_64 loader will be capable
+# of secure boot or not based on the chosen nvram.
+SUSHY_EMULATOR_BOOT_LOADER_MAP = {
+    u'UEFI': {
+        u'x86_64': u'/usr/share/OVMF/OVMF_CODE.secboot.fd'
+    },
+    u'Legacy': {
+        u'x86_64': None
+    }
+}

docs/user-guide/src/quick-start.md

@@ -2,7 +2,7 @@
 
 <!-- cSpell:ignore htpasswd,virsh -->
 
-This guide has been tested on Ubuntu server 22.04. It should be seen as an
+This guide has been tested on Ubuntu server 24.04. It should be seen as an
 example rather than the absolute truth about how to deploy and use Metal3. We
 will cover two environments and two scenarios. The environments are
 
@@ -79,24 +79,14 @@ and the MAC address:
 Start by defining a libvirt network:
 
 ```xml
-<network>
-  <name>baremetal</name>
-  <forward mode='nat'>
-    <nat>
-      <port start='1024' end='65535'/>
-    </nat>
-  </forward>
-  <bridge name='metal3'/>
-  <ip address='192.168.222.1' netmask='255.255.255.0'>
-  </ip>
-</network>
+{{#embed-github repo:"metal3-io/metal3-docs" branch:"main" path:"docs/user-guide/examples/net.xml"}}
 ```
 
 Save this as `net.xml`, define it and start it.
 
 ```bash
 virsh -c qemu:///system net-define net.xml
-virsh -c qemu:///system net-start baremetal
+virsh -c qemu:///system net-start baremetal-e2e
 ```
 
 Next, we will create a virtual machine. Feel free to adjust at as you see fit,
@@ -130,11 +120,7 @@ the form of [sushy-tools](https://docs.openstack.org/sushy/latest/).
 We need to create configuration file first:
 
 ```conf
-# Listen on 192.168.222.1:8000
-SUSHY_EMULATOR_LISTEN_IP = u'192.168.222.1'
-SUSHY_EMULATOR_LISTEN_PORT = 8000
-# The libvirt URI to use. This option enables libvirt driver.
-SUSHY_EMULATOR_LIBVIRT_URI = u'qemu:///system'
+{{#embed-github repo:"metal3-io/metal3-docs" branch:"main" path:"docs/user-guide/examples/sushy-emulator.conf"}}
 ```
 
 ```bash
@@ -164,22 +150,7 @@ note that this is absolutely not intended for production environments.
 We will use the following configuration file for kind, save it as `kind.yaml`:
 
 ```yaml
-kind: Cluster
-apiVersion: kind.x-k8s.io/v1alpha4
-nodes:
-- role: control-plane
-  # Open ports for Ironic
-  extraPortMappings:
-  # Ironic httpd
-  - containerPort: 6180
-    hostPort: 6180
-    listenAddress: "0.0.0.0"
-    protocol: TCP
-  # Ironic API
-  - containerPort: 6385
-    hostPort: 6385
-    listenAddress: "0.0.0.0"
-    protocol: TCP
+{{#embed-github repo:"metal3-io/metal3-docs" branch:"main" path:"docs/user-guide/examples/kind.yaml"}}
 ```
 
 As you can see, it has a few ports forwarded from the host. This is to make
@@ -195,22 +166,23 @@ We will need to install cert-manager also. It will be used to manage the
 certificates for Ironic later.
 
 ```bash
-kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
 ```
 
 ### DHCP server
 
 The BareMetalHosts must be able to call back to Ironic when going through the
 inspection phase. This means that they must have IP addresses in a network where
-they can reach Ironic. We will set up a DHCP server for this purpose.
+they can reach Ironic. Any DHCP server can be used for this.
 
-Any DHCP server can be used for this. We will here use the Ironic container
-image that incudes dnsmasq and some scripts for configuring it.
-
-Create a configuration file and save it as `dnsmasq.env`.
+For the virtualized environment, we rely on the libvirt network to provide the DHCP server.
 
 Baremetal lab:
 
+We will here use the Ironic container
+image that incudes dnsmasq and some scripts for configuring it.
+Create a configuration file and save it as `dnsmasq.env`.
+
 ```bash
 # The same HTTP port must be provided to all containers!
 HTTP_PORT=6180
@@ -225,26 +197,6 @@ DHCP_RANGE=192.168.0.100,192.168.0.149
 GATEWAY_IP=192.168.0.1
 ```
 
-Virtualized environment:
-
-```bash
-HTTP_PORT=6180
-DHCP_HOSTS=00:60:2f:31:81:01
-DHCP_IGNORE=tag:!known
-# IP of the host from VM perspective
-PROVISIONING_IP=192.168.222.1
-GATEWAY_IP=192.168.222.1
-DHCP_RANGE=192.168.222.100,192.168.222.149
-```
-
-You can now run the DHCP server like this:
-
-```bash
-docker run --name dnsmasq --rm -d --net=host --privileged --user 997:994 \
-  --env-file dnsmasq.env --entrypoint /bin/rundnsmasq \
-  quay.io/metal3-io/ironic
-```
-
 ### Image server
 
 In order to do anything useful, we will need a server for hosting disk images
@@ -336,7 +288,7 @@ PROVISIONING_INTERFACE=eth0
 CACHEURL=http://192.168.222.1/images
 IRONIC_KERNEL_PARAMS=console=ttyS0
 # Docker does not allow cross-network access. If using kind to create the management
-# cluster, explicitly set the external ip and use port forwarding to access ironic services. 
+# cluster, explicitly set the external ip and use port forwarding to access ironic services.
 IRONIC_EXTERNAL_IP=192.168.222.1
 ```
 
@@ -578,7 +530,7 @@ place.
 1. Deploy cert-manager.
 
    ```bash
-   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
+   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
    ```
 
 1. Start the DHCP server.