### Clone the metal3-demo repository Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Clones the metal3-demo repository from GitHub. ```shell git clone https://github.com/suse-edge/metal3-demo.git ``` -------------------------------- ### Install pre-requisite packages Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Runs the preparation script to install required packages. Must be executed from the cloned repository directory. ```shell cd metal3-demo ./01_prepare_host.sh ``` -------------------------------- ### Apply BareMetalHost manifests Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Applies the BareMetalHost manifests from the metal3-demo-files directory. ```shell kubectl apply -f ~/metal3-demo-files/baremetalhosts ``` -------------------------------- ### Create management cluster Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Runs the script to create the management cluster. ```shell ./04_launch_mgmt_cluster.sh ``` -------------------------------- ### Build images with default configuration Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Runs the build script to configure the environment for deploying management and downstream clusters with openSUSE Leap Micro 6.0. ```shell ./03_build_images.sh ``` -------------------------------- ### Expected output of kubectl get bmh Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Example output showing hosts in 'available' state. ```text NAME STATE CONSUMER ONLINE ERROR AGE controlplane-0 available true 9m44s worker-0 available true 9m44s ``` -------------------------------- ### Configure the host environment Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Executes the host configuration script from the repository's main directory. ```shell ./02_configure_host.sh ``` -------------------------------- ### Install libguestfs-tools and set root password with virt-customize Source: https://github.com/cledorze/metal3-demo/blob/main/docs/troubleshooting/provisioning.md Install libguestfs-tools and use virt-customize to set the root password on a provisioning image. Replace with the actual image file and PASSWORD with the desired password. ```shell metal@metal3:~$ sudo apt-get install libguestfs-tools metal@metal3: ~$ sudo virt-customize -a --root-password password:PASSWORD ``` -------------------------------- ### Ansible playbook using libvirt-setup role Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-libvirt-setup.md Example playbook that runs the libvirt-setup role on localhost with variables to configure the number of controlplane and worker hosts, disable DHCP, enable IPv6, and enable secure boot. ```yaml - hosts: localhost connection: local gather_facts: true roles: - role: libvirt-setup vars: num_controlplane_hosts: 3 num_worker_hosts: 5 libvirt_network_dhcp: false libvirt_network_ipv6: true libvirt_secure_boot: true ``` -------------------------------- ### Create a non-root user with sudo access Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Creates a user 'auser' with passwordless sudo and switches to that user. Requires an existing non-root user or root privileges. ```bash sudo useradd auser -m -s /bin/bash sudo echo "auser ALL=NOPASSWD: ALL" > /etc/sudoers.d/auser sudo su - auser ``` -------------------------------- ### Usage example: playbook with kubernetes-tools role Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-kubernetes-tools.md Example playbook that applies the kubernetes-tools role to localhost with custom versions for helm, kubectl, and clusterctl. Overrides the default version variables to install specific releases. ```yaml - hosts: localhost connection: local roles: - role: kubernetes-tools vars: helm_version: v3.14.0 kubectl_version: v1.30.0 capi_core_version: v1.8.0 ``` -------------------------------- ### Dual-stack / DHCP-less testing setup Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/configuration.md Configures extra_vars.yml for dual-stack / DHCP-less testing by disabling DHCP and enabling IPv6, then sets EXTRA_VARS_FILE. ```bash cp extra_vars.yml ~/extra_vars.yml echo "libvirt_network_dhcp: false" >> ~/extra_vars.yml echo "libvirt_network_ipv6: true" >> ~/extra_vars.yml export EXTRA_VARS_FILE=~/extra_vars.yml ``` -------------------------------- ### Monitor BareMetalHost status Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Checks the status of BareMetalHosts until they reach 'available' state. ```shell kubectl get bmh ``` -------------------------------- ### Playbook usage example for image-cache role Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-image-cache.md Shows how to include the image-cache role in a playbook targeting localhost. ```yaml - hosts: localhost connection: local roles: - role: image-cache ``` -------------------------------- ### Usage example for sushy-tools role Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-sushy-tools.md Example playbook that applies the sushy-tools role on localhost with custom variables. Sets the Redfish API port and Basic-auth credentials. ```yaml - hosts: localhost connection: local roles: - role: sushy-tools vars: sushy_tools_port: 8000 vbmc_username: admin vbmc_password: password ``` -------------------------------- ### Import role in playbook (prepare_host.yml excerpt) Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-packages-installation.md Imports the packages_installation role to install required packages. Used in playbooks/prepare_host.yml. ```yaml # playbooks/prepare_host.yml (excerpt — as shipped) - name: Install required packages import_role: name: packages_installation ``` -------------------------------- ### Build images with SLEMicro local image Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Sets environment variables for a local SLE Micro image and registration code, then runs the build script. The image must be uncompressed raw format. ```shell export OS_LOCAL_IMAGE=/path/to/image.raw export EIB_REGISTRATION_CODE= ./03_build_images.sh ``` -------------------------------- ### Verify installed tools after role run Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-kubernetes-tools.md Commands to check that the installed Kubernetes tools are available after running the role. Each command prints the version of the respective tool. ```bash kubectl version --client clusterctl version helm version k9s ``` -------------------------------- ### GET https://:8000/redfish/v1/Systems/ Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/endpoints.md Returns the collection of systems managed by the Redfish emulator. This endpoint lists all available system resources. ```APIDOC ## [GET] https://:8000/redfish/v1/Systems/ ### Description Returns the collection of systems managed by the Redfish emulator. ### Method GET ### Endpoint `https://:8000/redfish/v1/Systems/` ### Parameters #### Path Parameters - **vbmc_ip** (string) - Required - The IP address of the virtual BMC. ### Response #### Success Response (200) - Systems collection (JSON) #### Response Example ```json { "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection", "Members": [] } ``` ``` -------------------------------- ### Customize extra_vars.yml for dual-stack deployment Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Copies the default extra_vars.yml and modifies it to disable DHCP and enable IPv6 for a dual-stack deployment with static IPs. Sets the EXTRA_VARS_FILE environment variable to point to the customized file. ```bash cp extra_vars.yml ~ echo "libvirt_network_dhcp: false" >> ~/extra_vars.yml echo "libvirt_network_ipv6: true" >> ~/extra_vars.yml export EXTRA_VARS_FILE="~/extra_vars.yml" ``` -------------------------------- ### Run setup_management_cluster.yml with do_not_install_vm=true Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/playbooks.md Skips launching the management VM by setting do_not_install_vm=true. Useful when regenerating example manifests without needing the VM. ```bash ansible-playbook \ -i inventories/localhost_inventory.yml \ -e "@extra_vars.yml" \ -e do_not_install_vm=true \ playbooks/setup_management_cluster.yml ``` -------------------------------- ### GET https://:8000/redfish/v1/ Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/endpoints.md Returns the Redfish service root, providing a JSON description of the Redfish service. This is the entry point for the sushy-tools Redfish emulator. ```APIDOC ## [GET] https://:8000/redfish/v1/ ### Description Returns the Redfish service root, providing a JSON description of the Redfish service. ### Method GET ### Endpoint `https://:8000/redfish/v1/` ### Parameters #### Path Parameters - **vbmc_ip** (string) - Required - The IP address of the virtual BMC. ### Response #### Success Response (200) - Redfish service root (JSON) #### Response Example ```json { "@odata.type": "#ServiceRoot.v1_0_0.ServiceRoot", "Id": "RootService", "Name": "Root Service" } ``` ``` -------------------------------- ### BareMetalHost and Secret with static IP networkData Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/metal3-setup.md Disables the libvirt DHCP server via the `libvirt_network_dhcp` ansible variable and configures BareMetalHost resources with a static IP using a secret containing nmstate syntax. The networkData is consumed by nm-configurator during inspection and first-boot. ```yaml apiVersion: metal3.io/v1alpha1 kind: BareMetalHost metadata: name: controlplane-0 labels: cluster-role: control-plane spec: online: true bootMACAddress: "00:bc:1f:c3:8f:f0" bmc: address: redfish-virtualmedia://192.168.125.1:8000/redfish/v1/Systems/112815c5-b60f-4753-86d9-b25063c7bfc3 disableCertificateVerification: true credentialsName: controlplane-0-credentials preprovisioningNetworkDataName: controlplane-0-networkdata --- apiVersion: v1 kind: Secret metadata: name: controlplane-0-networkdata type: Opaque stringData: networkData: | interfaces: - name: enp1s0 type: ethernet state: up mac-address: "00:bc:1f:c3:8f:f0" ipv4: address: - ip: "192.168.125.200" prefix-length: "24" enabled: true dhcp: false dns-resolver: config: server: - "192.168.125.1" routes: config: - destination: 0.0.0.0/0 next-hop-address: "192.168.125.1" next-hop-interface: enp1s0 ``` -------------------------------- ### node_ip_map example Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/types.md Example of the node_ip_map variable, built only when static IPs are used (libvirt_network_dhcp == false). Overridden entries come from node_ip_map_override. Consumed by baremetalhost.yaml.j2 and node_ip_map_tasks.yml. ```yaml node_ip_map: controlplane_0: external_v4: "192.168.125.200" external_v6: "fd55::200" ``` -------------------------------- ### GET/POST https://:8000/redfish/v1/Systems/ Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/endpoints.md Accesses a specific system resource identified by its libvirt UUID. Supports GET to retrieve system details and POST to perform actions such as power control and virtual media operations, which are consumed by Ironic. ```APIDOC ## [GET/POST] https://:8000/redfish/v1/Systems/ ### Description Accesses a specific system resource identified by its libvirt UUID. Supports GET to retrieve system details and POST to perform actions such as power control and virtual media operations, which are consumed by Ironic. ### Method GET, POST ### Endpoint `https://:8000/redfish/v1/Systems/` ### Parameters #### Path Parameters - **vbmc_ip** (string) - Required - The IP address of the virtual BMC. - **libvirt-uuid** (string) - Required - The UUID of the virtual machine. ### Response #### Success Response (200) - System resource (JSON) #### Response Example ```json { "@odata.type": "#ComputerSystem.v1_0_0.ComputerSystem", "Id": "", "PowerState": "On" } ``` ``` -------------------------------- ### GET / Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/endpoints.md Returns the directory index of the image cache webserver, listing available files. This endpoint serves the root of the image cache directory. ```APIDOC ## [GET] / ### Description Returns the directory index of the image cache webserver, listing available files. ### Method GET ### Endpoint `/` ### Response #### Success Response (200) - Directory index (HTML) #### Response Example ```html ... ``` ``` -------------------------------- ### Deprovision cluster and check BareMetalHosts Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-example-manifests.md Delete the agent and control-plane manifests to deprovision. BareMetalHosts return to 'available' once deprovisioning completes; verify with kubectl get bmh. ```bash kubectl delete -f rke2-agent.yaml kubectl delete -f rke2-control-plane.yaml # BareMetalHosts return to 'available' once deprovisioning completes kubectl get bmh ``` -------------------------------- ### IPMI power status error and successful check Source: https://github.com/cledorze/metal3-demo/blob/main/docs/troubleshooting/provisioning.md Example showing an IPMI session failure due to incorrect password, followed by a successful check with the correct password. The first command returns 'Error: Unable to establish IPMI v2 / RMCP+ session', the second returns 'Chassis Power is on'. ```shell metal@metal3:~$ ipmitool -H 192.168.8.53 -I lanplus -U SCALE -P uj2bTkX chassis power status Error: Unable to establish IPMI v2 / RMCP+ session metal@metal3:~$ ipmitool -H 192.168.8.53 -I lanplus -U SCALE -P uj2bTkXV chassis power status Chassis Power is on ``` -------------------------------- ### GET /.sha256 Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/endpoints.md Retrieves the SHA256 checksum file for a given image. This checksum is used as the 'checksum' field in the Metal3MachineTemplate. ```APIDOC ## [GET] /.sha256 ### Description Retrieves the SHA256 checksum file for a given image. This checksum is used as the 'checksum' field in the Metal3MachineTemplate. ### Method GET ### Endpoint `/.sha256` ### Parameters #### Path Parameters - **image** (string) - Required - The base name of the image file. ### Response #### Success Response (200) - Checksum file (text) #### Response Example ``` ``` ``` -------------------------------- ### Mandatory core image variables for local image flow Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-image-cache.md Example variables for using a local OS image instead of downloading from a URL, as documented for the SLE Micro flow. ```yaml vars: os_image_url: "" os_local_image: /data/SLE-Micro.x86_64-6.0-Default-GM.raw os_image_name: SLE-Micro.x86_64-6.0-Default-GM.raw ``` -------------------------------- ### Override package lists with role vars Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-packages-installation.md Overrides the default package lists for Ubuntu and pip3 by passing vars to the role. The example shows a playbook targeting localhost with gather_facts enabled. ```yaml - hosts: localhost connection: local gather_facts: true roles: - role: packages_installation vars: packages: ubuntu: - git - jq pip3: - libvirt-python ``` -------------------------------- ### GET / Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/endpoints.md Retrieves the raw downstream cluster image file, such as an openSUSE Leap Micro raw image. This URL is used in the Metal3MachineTemplate's image URL. ```APIDOC ## [GET] / ### Description Retrieves the raw downstream cluster image file, such as an openSUSE Leap Micro raw image. This URL is used in the Metal3MachineTemplate's image URL. ### Method GET ### Endpoint `/` ### Parameters #### Path Parameters - **os_image_name** (string) - Required - The name of the OS image file. ### Response #### Success Response (200) - Raw image file (binary) #### Response Example ``` (binary data) ``` ``` -------------------------------- ### vm_nodes structure Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/types.md Defines the list of node descriptors for libvirt setup. Each node has a unique name and a flavor key referencing libvirt_flavors. Generated when the caller does not define vm_nodes. ```yaml vm_nodes: - name: controlplane_0 # _ flavor: controlplane # key into libvirt_flavors - name: worker_0 flavor: worker ``` -------------------------------- ### Create and resize overlay disk with qemu-img Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-management-cluster.md Re-creates the per-instance overlay disk using the EIB-built management image as backing file, then resizes it to disk_image_size (default 40G). ```bash qemu-img create -f qcow2 -F qcow2 -o backing_file={{ source_image_file }} {{ disk_image_file }} qemu-img resize {{ disk_image_file }} {{ disk_image_size }} ``` -------------------------------- ### Deploy rendered manifests to management cluster Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-example-manifests.md Apply the rendered RKE2 control-plane and agent manifests, then verify with clusterctl describe. Run from the example-manifests directory. ```bash cd ~/metal3-demo-files/example-manifests kubectl apply -f rke2-control-plane.yaml clusterctl describe cluster sample-cluster kubectl apply -f rke2-agent.yaml clusterctl describe cluster sample-cluster ``` -------------------------------- ### Apply generated baremetal hosts and verify Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-libvirt-setup.md Commands to apply the generated baremetal host manifests to the management cluster and list the BareMetalHost resources. ```bash kubectl apply -f ~/metal3-demo-files/baremetalhosts kubectl get bmh ``` -------------------------------- ### Basic end-to-end run of metal3-demo scripts Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/entry-point-scripts.md Run the four entry-point scripts in order to perform a full deployment. The scripts use `set -eux`, so a failing task aborts the run with a non-zero exit. ```bash cd metal3-demo ./01_prepare_host.sh ./02_configure_host.sh ./03_build_images.sh ./04_launch_mgmt_cluster.sh ``` -------------------------------- ### EIB configuration template (eib-config-mgmt.yaml.j2) Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-edge-image-builder.md Jinja2 template for Edge Image Builder configuration. Includes raw image settings, OS users, packages, and Kubernetes Helm charts. The eib-config-metal3.yaml.j2 variant differs by omitting the kubernetes section, using different kernelArgs, and not sizing the raw disk. ```yaml apiVersion: 1.0 image: imageType: raw arch: x86_64 baseImage: {{ eib_source_image_name }} outputImageName: {{ eib_mgmt_output_image_name }} operatingSystem: rawConfiguration: diskSize: {{ eib_image_size }} kernelArgs: [net.ifnames=1] users: - username: root encryptedPassword: "{{ vm_user_plain_text_password | password_hash }}" - username: {{ vm_user }} sshKeys: {{ vm_authorized_ssh_keys | to_yaml }} encryptedPassword: "{{ vm_user_plain_text_password | password_hash }}" createHomeDir: true packages: packageList: [jq] # sccRegistrationCode: "{{ eib_registration_code }}" (only when eib_source_image_slemicro) kubernetes: version: {{ cluster_rke2_version }} helm: charts: - name: cert-manager # version {{ cert_manager_version }} repo jetstack, ns cert-manager, valuesFile certmanager-values.yaml - name: metal3 # version {{ metal3_version }} repo suse-edge-charts, ns metal3-system, valuesFile metal3-values.yaml - name: rancher # version {{ rancher_version }} repo rancher-charts, ns cattle-system, valuesFile rancher-values.yaml - name: rancher-turtles # version {{ rancher_turtles_version }} repo suse-edge-charts, ns rancher-turtles-system, valuesFile turtles-values.yaml repositories: - {name: jetstack, url: https://charts.jetstack.io} - {name: rancher-charts, url: {{ rancher_helm_repo }}} - {name: suse-edge-charts, url: {{ suse_edge_helm_repo }}} ``` -------------------------------- ### Playbook usage for example-manifests role Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-example-manifests.md Use this playbook to invoke the example-manifests role with required variables. The role renders manifests for a cluster named 'my-cluster' with 3 controlplane hosts and a v4 network CIDR. ```yaml - hosts: localhost connection: local roles: - role: example-manifests vars: cluster_name: my-cluster num_controlplane_hosts: 3 cluster_network_cidr_v4: 10.244.0.0/16 ``` -------------------------------- ### Customize options via alternate vars file (EXTRA_VARS_FILE) Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/entry-point-scripts.md Create an alternate vars file to enable dual-stack and DHCP-less configuration, then export `EXTRA_VARS_FILE` and run `02_configure_host.sh`. The script reads this variable to override defaults. ```bash cp extra_vars.yml ~/extra_vars.yml echo "libvirt_network_dhcp: false" >> ~/extra_vars.yml echo "libvirt_network_ipv6: true" >> ~/extra_vars.yml export EXTRA_VARS_FILE=~/extra_vars.yml ./02_configure_host.sh ``` -------------------------------- ### Run setup_management_cluster.yml directly Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/playbooks.md Invokes the playbook with the same context as the wrapper scripts: sets ANSIBLE_ROLES_PATH, uses the local inventory, and loads extra_vars.yml. Use this when running the playbook directly instead of via the recommended scripts. ```bash export ANSIBLE_ROLES_PATH=/path/to/metal3-demo/roles ansible-playbook \ -i inventories/localhost_inventory.yml \ -e "@extra_vars.yml" \ playbooks/setup_management_cluster.yml ``` -------------------------------- ### Group vars: suse.yml (legacy suse_snap) Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/configuration.md Defines a legacy suse_snap structure (openSUSE snappy repo + snapd package) not referenced by any current task. ```yaml inventories/group_vars/all/suse.yml ``` -------------------------------- ### Import edge-image-builder role with eib_source_image variable Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-edge-image-builder.md YAML excerpt from playbooks/build_images.yml showing how to import the edge-image-builder role and set the eib_source_image variable to the cached OS image. Used in the image build workflow. ```yaml # playbooks/build_images.yml (excerpt — as shipped) - import_role: name: edge-image-builder vars: eib_source_image: "{{ image_cache_dir }}/{{ os_image_name }}" ``` -------------------------------- ### Verify control plane provisioning with clusterctl describe Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/rke2-cluster.md Checks the status of the cluster after control plane deployment. Expected output shows the cluster and control plane as ready. ```shell clusterctl describe cluster sample-cluster ``` ```text NAME READY SEVERITY REASON SINCE MESSAGE Cluster/sample-cluster True 22m ├─ClusterInfrastructure - Metal3Cluster/sample-cluster True 27m ├─ControlPlane - RKE2ControlPlane/sample-cluster True 22m │ └─Machine/sample-cluster-chflc True 23m ``` -------------------------------- ### Copy image to ironic container and update image URL Source: https://github.com/cledorze/metal3-demo/blob/main/docs/troubleshooting/provisioning.md Copy the provisioning image into the ironic container and update the image URL in the YAML. Replace with the actual image file name. ```shell metal@metal3:~$ kubectl cp capm3-ironic-75db6cbd85-dsqkl:/shared/html/images -n capm3-system -c ironic Update the image url in yaml url: http://boot.ironic.suse.baremetal/images/ ``` -------------------------------- ### SLE Micro image flow Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/configuration.md Sets OS_LOCAL_IMAGE and EIB_REGISTRATION_CODE, then runs the image build script. ```bash export OS_LOCAL_IMAGE=/path/to/SLE-Micro.raw export EIB_REGISTRATION_CODE= ./03_build_images.sh ``` -------------------------------- ### Verify agent provisioning with clusterctl describe Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/rke2-cluster.md Checks the cluster status after agent deployment. Expected output shows the worker MachineDeployment and Machine as ready. ```shell clusterctl describe cluster sample-cluster ``` ```text NAME READY SEVERITY REASON SINCE MESSAGE Cluster/sample-cluster True 25m ├─ClusterInfrastructure - Metal3Cluster/sample-cluster True 30m ├─ControlPlane - RKE2ControlPlane/sample-cluster True 25m │ └─Machine/sample-cluster-chflc True 27m └─Workers └─MachineDeployment/sample-cluster True 22m └─Machine/sample-cluster-56df5b4499-zfljj True 23m ``` -------------------------------- ### Error handling pattern for script failure Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/entry-point-scripts.md Check the exit status of `02_configure_host.sh` and print an error message to stderr if it fails. The scripts use `set -eux`, so a failing task aborts with a non-zero exit. ```bash if ! ./02_configure_host.sh; then echo "host configuration failed" >&2 exit 1 fi ``` -------------------------------- ### sushy-emulator.conf template Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-sushy-tools.md Jinja2 template for the sushy-tools Redfish emulator configuration. Uses variables from role defaults, including sushy_tools_port, sushy_ignore_boot_device, and sushy_vmedia_verify_ssl. The file is rendered to {{ sushy_tools_dir }}/sushy-emulator.conf. ```python SUSHY_EMULATOR_LISTEN_IP = u'0.0.0.0' SUSHY_EMULATOR_LISTEN_PORT = '{{ sushy_tools_port }}' SUSHY_EMULATOR_SSL_CERT = u'/etc/sushy/sushy.crt' SUSHY_EMULATOR_SSL_KEY = u'/etc/sushy/sushy.key' SUSHY_EMULATOR_IGNORE_BOOT_DEVICE = {{ sushy_ignore_boot_device }} SUSHY_EMULATOR_VMEDIA_VERIFY_SSL = {{ sushy_vmedia_verify_ssl }} SUSHY_EMULATOR_AUTH_FILE = '/etc/sushy/htpasswd' ``` -------------------------------- ### Check BMC credentials with ipmitool chassis power status Source: https://github.com/cledorze/metal3-demo/blob/main/docs/troubleshooting/provisioning.md Command to verify BMC connectivity and credentials. Replace $ilo_ip, $ilo_user, and $ilo_pwd with actual values. ```shell $ ipmitool -H $ilo_ip -I lanplus -U $ilo_user -P $ilo_pwd chassis power status ``` -------------------------------- ### Bash loop to catch step failures Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/errors.md Use this pattern when driving the repo from automation to stop on the first failing step and report which step failed. The wrapper scripts run ansible-playbook with set -eux and ANSIBLE_FORCE_COLOR=true, so failures are loud and visible; append -vvv for more detail. ```bash set -e for step in 01_prepare_host.sh 02_configure_host.sh 03_build_images.sh 04_launch_mgmt_cluster.sh; do if ! ./"$step"; then echo "step $step failed" >&2 exit 1 fi done ``` -------------------------------- ### Deploy RKE2 control plane Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/rke2-cluster.md Applies the RKE2 control plane manifest from the example-manifests directory. ```shell cd ~/metal3-demo-files/example-manifests kubectl apply -f rke2-control-plane.yaml ``` -------------------------------- ### Verify management cluster after role Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-management-cluster.md Commands to confirm the management cluster is up: list nodes with kubectl and SSH to the default management VM login. ```bash kubectl get nodes ssh metal@192.168.125.99 # default management VM login ``` -------------------------------- ### Podman container definition for sushy-tools Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-sushy-tools.md Ansible task using containers.podman.podman_container to run the sushy-tools container. Mounts the config directory and libvirt socket, runs privileged in host network, and sets environment variables. force_restart: true redeploys on every configure_host run. ```yaml containers.podman.podman_container: name: sushy-tools image: quay.io/metal3-io/sushy-tools:latest volumes: - "{{ sushy_tools_dir }}:/etc/sushy/:Z" - "/var/run/libvirt:/var/run/libvirt:Z" detach: true net: host privileged: true exposed_ports: ["{{ sushy_tools_port }}"] ports: ["{{ sushy_tools_port }}:{{ sushy_tools_port }}"] state: started force_restart: true etc_hosts: imagecache.local: "{{ external_network_bridge_ip_v4 if libvirt_network_ipv4|bool else external_network_bridge_ip_v6 }}" env: SUSHY_EMULATOR_CONFIG: "/etc/sushy/sushy-emulator.conf" command: "/usr/local/bin/sushy-emulator" ``` -------------------------------- ### Inventory: localhost_inventory.yml Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/configuration.md Declares a single local host with local Ansible connection. ```yaml local: hosts: localhost: ansible_connection: local ``` -------------------------------- ### Verbose ansible-playbook arguments appended Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/entry-point-scripts.md Append extra arguments to the script invocation; here `-vvv` enables verbose output from the underlying ansible-playbook run. ```bash ./02_configure_host.sh -vvv ``` -------------------------------- ### Check BareMetalHost deprovisioning status Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/rke2-cluster.md Shows the state of BareMetalHosts during deprovisioning and after completion. The first command shows deprovisioning state, the second shows available state. ```shell > kubectl get bmh NAME STATE CONSUMER ONLINE ERROR AGE controlplane-0 deprovisioning sample-cluster-controlplane-vlrt6 false 10m worker-0 deprovisioning sample-cluster-workers-785x5 false 10m ``` ```shell > kubectl get bmh NAME STATE CONSUMER ONLINE ERROR AGE controlplane-0 available false 15m worker-0 available false 15m ``` -------------------------------- ### Verify served image with curl Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-image-cache.md Checks that the image is being served over HTTPS by requesting the directory listing from the container. ```bash curl -k https://imagecache.local:8443/ # directory listing ``` -------------------------------- ### Include management-cluster role in playbook Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-management-cluster.md Excerpt from playbooks/setup_management_cluster.yml showing how to invoke the role with explicit vm_* vars. The role is skipped when do_not_install_vm is true. ```yaml # playbooks/setup_management_cluster.yml (excerpt — as shipped) - name: Start Management Cluster VM include_role: name: management-cluster when: - (not do_not_install_vm | default(False)) | bool vars: vm_hostname: management-cluster vm_instance_name: management_0 vm_network: "{{ management_cluster_vm_network }}" vm_public_network_ip: "{{ management_cluster_public_ip }}" ``` -------------------------------- ### libvirt_flavors variable definition Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/types.md Defines VM flavors for node generation, including cluster role, memory, disk, and vCPU. The disk value of 0 skips storage volume creation. ```yaml libvirt_flavors: : # e.g. management | controlplane | worker cluster_role: string # e.g. control-plane memory: int # MiB disk: int # GiB; 0 => no storage volume vcpu: int ``` -------------------------------- ### Python main() for AnsibleModule generate_macs Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/module-generate-macs.md Defines the Ansible module entry point with required arguments `nodes` and `networks` (both lists). Calls `generate_vm_interface_macs` and exits via `module.exit_json(**result)`, where each generated MAC map key becomes a separate JSON key. A `ValueError` propagates as a module failure. ```python def main(): module = AnsibleModule( argument_spec=dict( nodes=dict(required=True, type='list'), networks=dict(required=True, type='list') ) ) result = generate_vm_interface_macs(module.params["nodes"], module.params["networks"]) module.exit_json(**result) ``` -------------------------------- ### Catch shell script guard failure Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/errors.md Consumer code that runs `01_prepare_host.sh` and handles its exit status. If the script fails (e.g., due to root execution or unsupported distribution), it prints an error to stderr and exits with status 1. ```bash if ./01_prepare_host.sh; then echo "host prepared" else echo "prepare failed (exit $?)" >&2 exit 1 fi ``` -------------------------------- ### Podman container definition for image-cache Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-image-cache.md Defines the Apache httpd container that serves the cached OS image over HTTPS. Mounts the image cache and configuration directories, exposes ports 8080 and 8443, and recreates the container if it already exists. ```yaml containers.podman.podman_container: name: image-cache image: docker.io/library/httpd:2.4 volumes: - "{{ image_cache_dir }}:/usr/local/apache2/htdocs" - "{{ image_cache_conf_dir }}/httpd.conf:/usr/local/apache2/conf/httpd.conf" - "{{ image_cache_conf_dir }}/server.key:/usr/local/apache2/conf/server.key" - "{{ image_cache_conf_dir }}/server.crt:/usr/local/apache2/conf/server.crt" detach: true exposed_ports: [80, 443] ports: ["8080:80", "8443:443"] state: started recreate: true ``` -------------------------------- ### Query Redfish Systems endpoint Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/role-sushy-tools.md SSH command to query the sushy-tools Redfish API from the management cluster VM. Uses curl with Basic auth to list systems; useful for debugging. ```bash ssh metal@192.168.125.99 "curl -sk -u admin:password https://192.168.125.1:8000/redfish/v1/Systems | jq" ``` -------------------------------- ### Deploy RKE2 agent Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/rke2-cluster.md Applies the RKE2 agent manifest to add worker nodes. ```shell kubectl apply -f rke2-agent.yaml ``` -------------------------------- ### generate_vm_interface_macs(nodes, networks) Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/module-generate-macs.md Generates deterministic locally administered Ethernet MAC addresses for fake bare-metal VMs. It takes lists of nodes and networks and returns a mapping of node names to network names to MAC addresses. ```APIDOC ## generate_vm_interface_macs(nodes, networks) ### Description Generates deterministic locally administered Ethernet MAC addresses for fake bare-metal VMs. It takes lists of nodes and networks and returns a mapping of node names to network names to MAC addresses. ### Method Function call ### Endpoint `generate_vm_interface_macs(nodes, networks)` ### Parameters #### Function Parameters - **nodes** (list of dicts) - Required - Each dict must contain `name` (string); output map is keyed by `node['name']`. In the role, this is `vm_nodes` shaped `[{'name': 'controlplane_0', 'flavor': 'controlplane'}, ...]`. - **networks** (list of dicts) - Required - Each dict must contain `name` (string); output map is keyed by `network['name']`. In the role, this is `libvirt_networks`. ### Return Value - **dict** - A mapping `{node_name: {network_name: mac}}` where each `mac` is a lowercase `xx:xx:xx:xx:xx:xx` string. Properties of the generated MACs: - 6-byte MACs with the first byte `00` and 4 random middle bytes; the number of MACs required is `len(nodes) * len(networks)`. - The final byte is sequential: MACs are emitted in steps of 2 starting from a random base (reclamped to `0xff - count * 2` when the range overflows), so each node's MACs are sequential and spaced by 2 — mirroring real NIC layouts and keeping the locally administered bit behavior consistent. ### Exceptions - **ValueError** - Raised when `len(nodes) * len(networks) > MAX_NUM_MACS` (= 127). ``` -------------------------------- ### generate_vm_interface_macs function Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/module-generate-macs.md Deterministically generates locally administered Ethernet MAC addresses for fake bare-metal VMs. Raises ValueError if the number of required MACs exceeds MAX_NUM_MACS (127). ```python MAX_NUM_MACS = math.trunc(0xff / 2) def generate_vm_interface_macs(nodes, networks): """Generate an Ethernet MAC address suitable for VM testing.""" # NOTE(dprince): We generate our own bare metal MAC address's here # instead of relying on libvirt so that we can ensure the # locally administered bit is set low. (The libvirt default is # to set the 2nd MSB high.) This effectively allows our # fake baremetal VMs to more accurately behave like real hardware # and fixes issues with bridge/DHCP configurations which rely # on the fact that bridges assume the MAC address of the lowest # attached NIC. # MACs generated for a given machine will also be in sequential # order, which matches how most BM machines are laid out as well. # Additionally we increment each MAC by two places. macs = [] count = len(nodes) * len(networks) if count > MAX_NUM_MACS: raise ValueError("The MAX num of MACS supported is %i " "(you specified %i)." % (MAX_NUM_MACS, count)) base_nums = [0x00, random.randint(0x00, 0xff), random.randint(0x00, 0xff), random.randint(0x00, 0xff), random.randint(0x00, 0xff)] base_mac = ':'.join(["%02x" % x for x in base_nums]) start = random.randint(0x00, 0xff) if (start + (count * 2)) > 0xff: # leave room to generate macs in sequence start = 0xff - count * 2 for num in range(0, count * 2, 2): mac = start + num macs.append(base_mac + ":" + ("%02x" % mac)) result = {} for node in nodes: result[node['name']] = {} for network in networks: result[node['name']][network['name']] = macs.pop(0) return result ``` -------------------------------- ### node_mac_map structure Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/types.md Maps each node name to a dictionary of network names to MAC addresses. Generated by the generate_macs module and persisted to node_mac_map.json. MACs are sequential with a step of 2. ```yaml node_mac_map: controlplane_0: external: "00:a1:b2:c3:d4:e5" # lowercase colon-hex MAC worker_0: external: "00:a1:b2:c3:d4:e7" # sequential, step of 2 ``` -------------------------------- ### Deprovision RKE2 workload cluster Source: https://github.com/cledorze/metal3-demo/blob/main/docs/setup/rke2-cluster.md Deletes the agent and control plane manifests to trigger deprovisioning of BareMetalHost resources. ```shell cd ~/metal3-demo-files/example-manifests kubectl delete -f rke2-agent.yaml kubectl delete -f rke2-control-plane.yaml ``` -------------------------------- ### Ansible set_fact to load existing node_mac_map Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/module-generate-macs.md Loads data from an existing `node_mac_map` file if defined, otherwise falls back to the registered `gen_node_mac_map` result. This is part of the error handling/idempotency pattern used in the role. ```yaml - name: Load data from existing node_mac_map file set_fact: node_mac_map: "{{ file_node_mac_map if file_node_mac_map is defined else gen_node_mac_map }}" ``` -------------------------------- ### Ansible task calling generate_macs with registration Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/module-generate-macs.md Role task that invokes the `generate_macs` module with `nodes` and `networks` variables, registers the result as `gen_node_mac_map`, and runs only when `node_mac_map_file.stat.exists` is false. This is part of the idempotency pattern to keep MACs stable across re-runs. ```yaml # roles/libvirt-setup/tasks/common_setup_tasks.yml - name: get a list of MACs to use generate_macs: nodes: "{{ vm_nodes }}" networks: "{{ libvirt_networks }}" register: gen_node_mac_map when: not node_mac_map_file.stat.exists ``` -------------------------------- ### node_ip_map_override variable definition Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/types.md Overrides sequential IP assignment for specific nodes by providing fixed IPv4 and IPv6 addresses. ```yaml node_ip_map_override: management_0: external_v4: "{{ management_cluster_public_ip }}" # 192.168.125.99 external_v6: "{{ management_cluster_public_ip_v6 }}" # fd55::99 ``` -------------------------------- ### generate_macs Source: https://github.com/cledorze/metal3-demo/blob/main/_autodocs/api-reference/module-generate-macs.md An Ansible module that generates MAC addresses for VM interfaces based on provided nodes and networks. It returns a mapping of generated MACs as JSON keys in the module result. ```APIDOC ## generate_macs ### Description Generates MAC addresses for VM interfaces based on the provided nodes and networks. Returns a mapping of generated MACs as JSON keys in the module result. ### Module Ansible Module ### Arguments - **nodes** (list) - Required - List of nodes for which to generate MACs. - **networks** (list) - Required - List of networks to associate with the MACs. ### Success Response Returns a JSON object where each generated MAC map key becomes a separate JSON key in the module result. ### Failure Response Raises a `ValueError` which propagates as a module failure, reported by Ansible as "MODULE FAILURE" with the message. ### Usage Example ```yaml - name: get a list of MACs to use generate_macs: nodes: "{{ vm_nodes }}" networks: "{{ libvirt_networks }}" register: gen_node_mac_map when: not node_mac_map_file.stat.exists ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.