Skip to content

[enterprise-4.12] : Replace nmcli commands with YAML declarative for confi… #102303

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 11, 2025
Merged

[enterprise-4.12] : Replace nmcli commands with YAML declarative for confi… #102303

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 148 additions & 71 deletions modules/ipi-install-configuring-networking.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,109 +6,186 @@
[id="configuring-networking_{context}"]
= Configuring networking

Before installation, you must configure the networking on the provisioner node. Installer-provisioned clusters deploy with a bare-metal bridge and network, and an optional provisioning bridge and network.
Before installation, you must configure networking settings for the provisioner node. Installer-provisioned clusters deploy with a bare-metal bridge and network resources, and an optional provisioning bridge and network resources.

image::210_OpenShift_Baremetal_IPI_Deployment_updates_0122_1.png[Configure networking]

[NOTE]
====
You can also configure networking from the web console.
You can also configure networking settings from the {product-title} web console.
====

.Procedure
.Prerequisites

. Export the bare-metal network NIC name by running the following command:
+
[source,terminal]
----
$ export PUB_CONN=<baremetal_nic_name>
----
* You installed the `nmstate` package with the `sudo dnf install -y <package_name>` command. The package includes the `nmstatectl` CLI.

.Procedure

. Configure the bare-metal network:
+
[NOTE]
====
The SSH connection might disconnect after executing these steps.
When configuring the bare-metal network and the secure shell (SSH) connection disconnects, NMState has a rollback mechanism that automatically reverts any configurations. You can also use the `nmstatectl gc` tool to generate configuration files for specified network state files.
====

.. For a network using DHCP, run the following command:
+
[source,terminal]
.. For a network using DHCP, run the following command to delete the `/etc/sysconfig/network-scripts/ifcfg-eth0` legacy style:
+
[source,yaml,subs="+quotes"]
----
$ nmcli con delete "System <baremetal_nic_name>"
----
$ sudo nohup bash -c "
nmcli con down \"$PUB_CONN\"
nmcli con delete \"$PUB_CONN\"
# RHEL 8.1 appends the word \"System\" in front of the connection, delete in case it exists
nmcli con down \"System $PUB_CONN\"
nmcli con delete \"System $PUB_CONN\"
nmcli connection add ifname baremetal type bridge <con_name> baremetal bridge.stp no <1>
nmcli con add type bridge-slave ifname \"$PUB_CONN\" master baremetal
pkill dhclient;dhclient baremetal
"
----
<1> Replace `<con_name>` with the connection name.

.. For a network using static IP addressing and no DHCP network, run the following command:
+
[source,terminal]
where:
+
`<baremetal_nic_name>`:: Replace `<baremetal_nic_name>` with the name of your network interface controller (NIC).
+
.. For a network that uses Dynamic Host Configuration Protocol (DHCP), create an NMState YAML file and specify the bare-metal bridge interface and any physical interfaces in the file:
+
.Example bare-metal bridge interface configuration that uses DHCP
[source,yaml]
----
# ...
interfaces:
- name: <physical_interface_name>
type: ethernet
state: up
ipv4:
enabled: false
ipv6:
enabled: false
- name: baremetal
type: linux-bridge
state: up
ipv4:
enabled: true
dhcp: true
bridge:
options:
stp:
enabled: false
port:
- name: <physical_interface_name>
# ...
----
+
.. For a network using static IP addressing and no DHCP network, create an NMState YAML file and specify the bare-metal bridge interface details in the file:
+
.Example bare-metal bridge interface configuration that uses static IP addressing and no DHCP network
[source,yaml]
----
# ...
dns-resolver:
config:
server:
- <dns_ip_address>
routes:
config:
- destination: 0.0.0.0/0
next-hop-interface: baremetal
next-hop-address: <gateway_ip>
interfaces:
- name: <physical_interface_name>
type: ethernet
state: up
ipv4:
enabled: false
ipv6:
enabled: false
- name: baremetal
type: linux-bridge
state: up
ipv4:
enabled: true
dhcp: false
address:
- ip: <static_ip_address>
prefix-length: 24
bridge:
options:
stp:
enabled: false
port:
- name: <physical_interface_name>
# ...
----
$ sudo nohup bash -c "
nmcli con down \"$PUB_CONN\"
nmcli con delete \"$PUB_CONN\"
# RHEL 8.1 appends the word \"System\" in front of the connection, delete in case it exists
nmcli con down \"System $PUB_CONN\"
nmcli con delete \"System $PUB_CONN\"
nmcli connection add ifname baremetal type bridge con-name baremetal bridge.stp no ipv4.method manual ipv4.addr "x.x.x.x/yy" ipv4.gateway "a.a.a.a" ipv4.dns "b.b.b.b" <1>
nmcli con add type bridge-slave ifname \"$PUB_CONN\" master baremetal
nmcli con up baremetal
"
----
<1> Replace `<con_name>` with the connection name. Replace `x.x.x.x/yy` with the IP address and CIDR for the network. Replace `a.a.a.a` with the network gateway. Replace `b.b.b.b` with the IP address of the DNS server.
+
where:
+
`<dns-resolver>`:: Defines the DNS server for your bare-metal system.
`<server>`:: Replace `<dns_ip_address>` with the IP address for the DNS server.
`<type>`:: Defines the bridge interface and its static IP configuration.
`<gateway>`:: Replace `<gateway_ip>` with the IP address of the gateway.
`<name>`:: Details the physical interface that you set as the bridge port.

. Optional: If you are deploying with a provisioning network, export the provisioning network NIC name by running the following command:
. Apply the network configuration from the YAML file to the network interfaces for the host by entering the following command:
+
[source,terminal]
----
$ export PROV_CONN=<prov_nic_name>
$ nmstatectl apply <path_to_network_yaml>
----

. Optional: If you are deploying with a provisioning network, configure the provisioning network by running the following command:
. Back up the network configuration YAML file by entering the following command:
+
[source,terminal]
----
$ sudo nohup bash -c "
nmcli con down \"$PROV_CONN\"
nmcli con delete \"$PROV_CONN\"
nmcli connection add ifname provisioning type bridge con-name provisioning
nmcli con add type bridge-slave ifname \"$PROV_CONN\" master provisioning
nmcli connection modify provisioning ipv6.addresses fd00:1101::1/64 ipv6.method manual
nmcli con down provisioning
nmcli con up provisioning
"
$ nmstatectl show > backup-nmstate.yml
----

. Optional: If you are deploying your cluster in a provisioning network, create or edit an NMState YAML file and specify the details in the file.
+
[NOTE]
====
The SSH connection might disconnect after executing these steps.

The IPv6 address can be any address that is not routable through the bare-metal network.
The IPv6 address can be any address that does not route through the bare-metal network.

Ensure that UEFI is enabled and UEFI PXE settings are set to the IPv6 protocol when using IPv6 addressing.
Ensure that you enabled Unified Extensible Firmware Interface (UEFI) and set UEFI PXE settings for the IPv6 protocol when using IPv6 addressing.
====

. Optional: If you are deploying with a provisioning network, configure the IPv4 address on the provisioning network connection by running the following command:
+
[source,terminal]
----
$ nmcli connection modify provisioning ipv4.addresses 172.22.0.254/24 ipv4.method manual
----

. SSH back into the `provisioner` node (if required) by running the following command:
.Example NMState YAML file for a provisioning network
[source,yaml]
----
# ...
interfaces:
- name: eth1
type: ethernet
state: up
ipv4:
enabled: false
ipv6:
enabled: false
- name: provisioning
type: linux-bridge
state: up
ipv4:
enabled: true
dhcp: false
address:
- ip: 172.22.0.254
prefix-length: 24
ipv6:
enabled: true
dhcp: false
address:
- ip: fd00:1101::1
prefix-length: 64
bridge:
options:
stp:
enabled: false
port:
- name: eth1
# ...
----

. Optional: Establish an SSH connection into the `provisioner` node by running the following command:
+
[source,terminal]
----
# ssh kni@provisioner.<cluster-name>.<domain>
# ssh kni@provisioner.<cluster_name>.<domain>
----
+
where
+
`<cluster_name>.<domain>`:: Replace `<cluster_name>` with the name of your cluster and `<domain>` with the fully qualified domain name (FQDN) of your cluster.

. Verify that the connection bridges have been properly created by running the following command:
+
Expand All @@ -120,10 +197,10 @@ $ sudo nmcli con show
.Example output
[source,terminal]
----
NAME UUID TYPE DEVICE
baremetal 4d5133a5-8351-4bb9-bfd4-3af264801530 bridge baremetal
provisioning 43942805-017f-4d7d-a2c2-7cb3324482ed bridge provisioning
virbr0 d9bca40f-eee1-410b-8879-a2d4bb0465e7 bridge virbr0
bridge-slave-eno1 76a8ed50-c7e5-4999-b4f6-6d9014dd0812 ethernet eno1
bridge-slave-eno2 f31c3353-54b7-48de-893a-02d2b34c4736 ethernet eno2
NAME UUID TYPE DEVICE
baremetal 832f645a-9337-4afc-b48e-4a55c5779eab bridge baremetal
provisioning e7756e01-d026-4a38-b460-129afaac0ec2 bridge provisioning
Wired connection 1 49ff4c9c-db76-3139-8c18-c49fa7deb39a ethernet eth0
Wired connection 2 c1fb12b1-88a6-3c07-93b9-187c99204c43 ethernet eth1
lo aa030e0f-21ca-498f-b6ce-bac7d4d793f0 loopback lo
----