Quick-start update

docs/user-guide/examples/bmc-secret.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: bml-01
+type: Opaque
+stringData:
+  username: replaceme
+  password: replaceme

docs/user-guide/examples/bmh-01-provision.yaml

@@ -0,0 +1,17 @@
+apiVersion: metal3.io/v1alpha1
+kind: BareMetalHost
+metadata:
+  name: bml-vm-01
+spec:
+  online: true
+  bootMACAddress: 00:60:2f:31:81:01
+  bootMode: UEFI
+  hardwareProfile: libvirt
+  bmc:
+    address: redfish-virtualmedia+http://192.168.222.1:8000/redfish/v1/Systems/bmh-vm-01
+    credentialsName: bml-01
+  image:
+    checksumType: sha256
+    checksum: http://192.168.222.1/SHA256SUMS
+    format: qcow2
+    url: http://192.168.222.1/jammy-server-cloudimg-amd64.img

docs/user-guide/examples/bmh-01.yaml

@@ -0,0 +1,12 @@
+apiVersion: metal3.io/v1alpha1
+kind: BareMetalHost
+metadata:
+  name: bml-vm-01
+spec:
+  online: true
+  bootMACAddress: 00:60:2f:31:81:01
+  bootMode: UEFI
+  hardwareProfile: libvirt
+  bmc:
+    address: redfish-virtualmedia+http://192.168.222.1:8000/redfish/v1/Systems/bmh-vm-01
+    credentialsName: bml-01

docs/user-guide/examples/bmo/kustomization.yaml

@@ -0,0 +1,9 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: baremetal-operator-system
+# This is the kustomization that we build on. You can download it and change
+# the URL to a relative path if you do not want to access it over the network.
+# Note that the ref=main specifies the version to use.
+# We use main here simply because the integration with IrSO is not included in a release yet.
+resources:
+- https://github.com/metal3-io/baremetal-operator/config/use-irso?ref=main

docs/user-guide/examples/capm3-vars.sh

@@ -0,0 +1,33 @@
+# Baremetal lab image variables
+# export IMAGE_URL="http://192.168.0.150/CENTOS_10_NODE_IMAGE_K8S_v1.34.1.qcow2"
+# export IMAGE_CHECKSUM="afa7e95ee6fb92b952ab85bae4d01033651e690cf04a626c668041d7b94ddd4a"
+# export IMAGE_FORMAT="qcow2"
+# Virtualized setup variables
+export IMAGE_URL="http://192.168.222.1/CENTOS_10_NODE_IMAGE_K8S_v1.34.1.raw"
+export IMAGE_CHECKSUM="20537529c0588e1c3d1929981207ef6fac73df7b2500b84f462d09badcc670ea"
+export IMAGE_FORMAT="raw"
+# Common variables
+export IMAGE_CHECKSUM_TYPE="sha256"
+export KUBERNETES_VERSION="v1.34.1"
+# Make sure this does not conflict with other networks
+export POD_CIDR='["192.168.10.0/24"]'
+# These can be used to add user-data
+export CTLPLANE_KUBEADM_EXTRA_CONFIG="
+    preKubeadmCommands:
+    - systemctl enable --now crio
+    users:
+    - name: user
+      sshAuthorizedKeys:
+      - ssh-ed25519 ABCD... [email protected]"
+export WORKERS_KUBEADM_EXTRA_CONFIG="
+      preKubeadmCommands:
+      - systemctl enable --now crio
+      users:
+      - name: user
+        sshAuthorizedKeys:
+        - ssh-ed25519 ABCD... [email protected]"
+# NOTE! You must ensure that this is forwarded or assigned somehow to the
+# server(s) that is selected for the control-plane.
+# We reserved this address in the net.xml as a basic way to get a fixed IP.
+export CLUSTER_APIENDPOINT_HOST="192.168.222.101"
+export CLUSTER_APIENDPOINT_PORT="6443"

docs/user-guide/examples/cleanup-virtual-lab.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+docker rm -f sushy-tools
+
+virsh -c qemu:///system destroy --domain "bmh-vm-01"
+virsh -c qemu:///system undefine --domain "bmh-vm-01" --remove-all-storage --nvram
+
+# Clear network
+virsh -c qemu:///system net-destroy baremetal-e2e
+virsh -c qemu:///system net-undefine baremetal-e2e
+
+sudo iptables -D FORWARD -i kind -o metal3 -j ACCEPT
+sudo iptables -D FORWARD -i metal3 -o kind -j ACCEPT
+
+sudo ip link delete metalend type veth

docs/user-guide/examples/image-server.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+mkdir disk-images
+
+pushd disk-images || exit
+wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
+wget https://cloud-images.ubuntu.com/jammy/current/SHA256SUMS
+sha256sum --ignore-missing -c SHA256SUMS
+wget https://artifactory.nordix.org/artifactory/metal3/images/k8s_v1.34.1/CENTOS_10_NODE_IMAGE_K8S_v1.34.1.qcow2
+sha256sum CENTOS_10_NODE_IMAGE_K8S_v1.34.1.qcow2
+# Convert to raw.
+# This helps lower memory requirements, since the raw image can be streamed to disk
+# instead of first loaded to memory by IPA for conversion.
+qemu-img convert -f qcow2 -O raw CENTOS_10_NODE_IMAGE_K8S_v1.34.1.qcow2 CENTOS_10_NODE_IMAGE_K8S_v1.34.1.raw
+# Local cache of IPA
+wget https://tarballs.opendev.org/openstack/ironic-python-agent/dib/ipa-centos9-master.tar.gz
+popd || exit
+
+docker run --name image-server --rm -d -p 80:8080 \
+  -v "$(pwd)/disk-images:/usr/share/nginx/html" nginxinc/nginx-unprivileged

docs/user-guide/examples/ironic/certificate.yaml

@@ -0,0 +1,44 @@
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned-issuer
+  namespace: baremetal-operator-system
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: ironic-cacert
+  namespace: baremetal-operator-system
+spec:
+  commonName: ironic-ca
+  isCA: true
+  issuerRef:
+    kind: Issuer
+    name: selfsigned-issuer
+  secretName: ironic-cacert
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: ca-issuer
+  namespace: baremetal-operator-system
+spec:
+  ca:
+    secretName: ironic-cacert
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: ironic-cert
+  namespace: baremetal-operator-system
+spec:
+  ipAddresses:
+  - 192.168.222.2
+  dnsNames:
+  - ironic.baremetal-operator-system.svc
+  issuerRef:
+    kind: Issuer
+    name: ca-issuer
+  secretName: ironic-cert

docs/user-guide/examples/ironic/ironic.yaml

@@ -0,0 +1,16 @@
+apiVersion: ironic.metal3.io/v1alpha1
+kind: Ironic
+metadata:
+  name: ironic
+  namespace: baremetal-operator-system
+spec:
+  networking:
+    dhcp:
+      rangeBegin: "192.168.222.100"
+      rangeEnd: "192.168.222.200"
+      networkCIDR: "192.168.222.0/24"
+    interface: "eth0"
+    ipAddress: "192.168.222.2"
+    ipAddressManager: "keepalived"
+  tls:
+    certificateName: ironic-cert

docs/user-guide/examples/ironic/kustomization.yaml

@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: baremetal-operator-system
+resources:
+- ironic.yaml
+- certificate.yaml

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,17 @@
+<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'/>
+      <!-- Reserve IP for convenience -->
+      <host mac='00:60:2f:31:81:01' name='bmh-vm-01' ip='192.168.222.101'/>
+      <bootp file='http://192.168.222.2:6180/boot.ipxe'/>
+    </dhcp>
+  </ip>
+</network>

docs/user-guide/examples/setup-bootstrap.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+kind create cluster --config kind.yaml
+
+# (Optional) Initialize CAPM3. This is only needed for scenario 2, but it also installs
+# cert-manager, which is needed for pretty much everything else.
+# If you skip this, make sure you install cert-manager separately!
+clusterctl init --infrastructure=metal3 --ipam=metal3
+
+kubectl apply -f https://github.com/metal3-io/ironic-standalone-operator/releases/latest/download/install.yaml
+kubectl -n ironic-standalone-operator-system wait --for=condition=Available deploy/ironic-standalone-operator-controller-manager
+
+# Now we can deploy Ironic and BMO
+kubectl create ns baremetal-operator-system
+# Apply Ironic with retry logic (up to 5 attempts with 10 second delays).
+# The IrSO webhook is not guaranteed to be ready when the IrSO deployment is,
+# so some retries may be needed.
+MAX_RETRIES=5
+RETRY_DELAY=10
+RETRY_COUNT=0
+echo "Applying Ironic configuration..."
+while [ ${RETRY_COUNT} -lt ${MAX_RETRIES} ]; do
+  if kubectl apply -k ironic; then
+    echo "Successfully applied Ironic configuration"
+    break
+  else
+    RETRY_COUNT=$((RETRY_COUNT + 1))
+    echo "Failed to apply Ironic configuration. Retrying in ${RETRY_DELAY} seconds... (Attempt ${RETRY_COUNT}/${MAX_RETRIES})"
+    sleep ${RETRY_DELAY}
+  fi
+done
+if [ ${RETRY_COUNT} -eq ${MAX_RETRIES} ]; then
+  echo "ERROR: Failed to apply Ironic configuration after ${MAX_RETRIES} attempts. Exiting."
+  exit 1
+fi
+kubectl apply -k bmo

docs/user-guide/examples/setup-virtual-lab.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Define and start the baremetal-e2e network
+virsh -c qemu:///system net-define net.xml
+virsh -c qemu:///system net-start baremetal-e2e
+
+# We need to create veth pair to connect the baremetal-e2e net (defined above)
+# and the docker network used by kind. This is to allow controllers in
+# the kind cluster to communicate with the VMs and vice versa.
+# For example, Ironic needs to communicate with IPA.
+# These options are the same as what kind creates by default,
+# except that we hard code the IPv6 subnet and specify a bridge name.
+#
+# NOTE! If you used kind before, you already have this network but
+# without the fixed bridge name. Please remove it first in that case!
+# docker network rm kind
+docker network create -d=bridge \
+    -o com.docker.network.bridge.enable_ip_masquerade=true \
+    -o com.docker.network.driver.mtu=1500 \
+    -o com.docker.network.bridge.name="kind" \
+    --ipv6 --subnet "fc00:f853:ccd:e793::/64" \
+    kind
+
+# Next create the veth pair
+sudo ip link add metalend type veth peer name kindend
+sudo ip link set metalend master metal3
+sudo ip link set kindend master kind
+sudo ip link set metalend up
+sudo ip link set kindend up
+
+# Then we need to set routing rules as well
+sudo iptables -I FORWARD -i kind -o metal3 -j ACCEPT
+sudo iptables -I FORWARD -i metal3 -o kind -j ACCEPT
+
+# Start the sushy-emulator container that acts as BMC
+docker run --name sushy-tools --rm --network host -d \
+  -v /var/run/libvirt:/var/run/libvirt \
+  -v "$(pwd)/sushy-emulator.conf:/etc/sushy/sushy-emulator.conf" \
+  -e SUSHY_EMULATOR_CONFIG=/etc/sushy/sushy-emulator.conf \
+  quay.io/metal3-io/sushy-tools:latest sushy-emulator
+
+# Generate a VM definition xml file and then define the VM
+# use --ram=8192 for Scenario 2
+virt-install \
+  --connect qemu:///system \
+  --name bmh-vm-01 \
+  --description "Virtualized BareMetalHost" \
+  --osinfo=ubuntu-lts-latest \
+  --ram=4096 \
+  --vcpus=2 \
+  --disk size=25 \
+  --boot uefi,hd,network \
+  --import \
+  --network network=baremetal-e2e,mac="00:60:2f:31:81:01" \
+  --noautoconsole \
+  --print-xml > bmh-vm-01.xml
+virsh define bmh-vm-01.xml
+rm bmh-vm-01.xml

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 won't work
+# if your VM has a floppy drive.
+SUSHY_EMULATOR_IGNORE_BOOT_DEVICE = False
+
+# The map of firmware loaders dependent 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
+    }
+}