diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index 7ba6ab4762..23c25eff35 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_topic_maps/_topic_map_ms.yml @@ -404,6 +404,8 @@ Topics: File: microshift-networking-settings - Name: Firewall configuration File: microshift-firewall +- Name: Networking settings for fully disconnected hosts + File: microshift-disconnected-network-config --- Name: Storage Dir: microshift_storage diff --git a/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc b/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc index 55c27d6565..4021be46ce 100644 --- a/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc +++ b/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc @@ -33,3 +33,4 @@ include::modules/microshift-creating-ostree-iso.adoc[leveloffset=+2] * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image_composing-a-customized-rhel-system-image#con_the-container-registry-credentials_assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image[Pushing a container to a registry and embedding it into an image] * link:https://www.osbuild.org/guides/image-builder-on-premises/container-auth.html[Container registry credentials] +* xref:../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] diff --git a/microshift_networking/microshift-disconnected-network-config.adoc b/microshift_networking/microshift-disconnected-network-config.adoc new file mode 100644 index 0000000000..11b7d7883a --- /dev/null +++ b/microshift_networking/microshift-disconnected-network-config.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-disconnected-network-config"] += Configuring network settings for fully disconnected hosts +include::_attributes/attributes-microshift.adoc[] +:context: microshift-networking-disconnected-hosts +toc::[] + +Learn how to apply networking customization and settings to run {microshift-short} on fully disconnected hosts. A disconnected host should be the {op-system-base-full} operating system, versions 9.0+, whether real or virtual, that runs without network connectivity. + +include::modules/microshift-disconnected-host-con.adoc[leveloffset=+1] + +include::modules/microshift-undo-network-config.adoc[leveloffset=+1] + +include::modules/microshift-disconnected-host-procedure.adoc[leveloffset=+1] diff --git a/modules/microshift-disconnected-host-con.adoc b/modules/microshift-disconnected-host-con.adoc new file mode 100644 index 0000000000..c6f5457df1 --- /dev/null +++ b/modules/microshift-disconnected-host-con.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * microshift_networking/microshift-disconnected-network-config.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-disconnected-host-preparation_{context}"] += Preparing networking for fully disconnected hosts + +Use the procedure that follows to start and run {microshift-short} clusters on devices running fully disconnected operating systems. A {microshift-short} host is considered fully disconnected if it has no external network connectivity. + +Typically this means that the device does not have an attached network interface controller (NIC) to provide a subnet. These steps can also be completed on a host with a NIC that is removed after setup. You can also automate these steps on a host that does not have a NIC by using the `%post` phase of a Kickstart file. + +[IMPORTANT] +==== +Configuring networking settings for disconnected environments is necessary because {microshift-short} requires a network device to support cluster communication. To meet this requirement, you must configure {microshift-short} networking settings to use the "fake" IP address you assign to the system loopback device during setup. +==== + +[id="microshift-disconnected-host-procedure-summary{context}"] +== Procedure summary + +To run {microshift-short} on a disconnected host, the following steps are required: + +Prepare the host:: +* Stop {microshift-short} if it is currently running and clean up changes the service has made to the network. +* Set a persistent hostname. +* Add a “fake” IP address on the loopback interface. +* Configure DNS to use the fake IP as local name server. +* Add an entry for the hostname to `/etc/hosts`. + +Update the {microshift-short} configuration:: +* Define the `nodeIP` parameter as the new loopback IP address. +* Set the `.node.hostnameOverride` parameter to the persistent hostname. + +For the changes to take effect:: +* Disable the default NIC if attached. +* Restart the host or device. + +After starting, {microshift-short} runs using the loopback device for within-cluster communication. diff --git a/modules/microshift-disconnected-host-procedure.adoc b/modules/microshift-disconnected-host-procedure.adoc new file mode 100644 index 0000000000..0ec6e96387 --- /dev/null +++ b/modules/microshift-disconnected-host-procedure.adoc @@ -0,0 +1,120 @@ +// Module included in the following assemblies: +// +// * microshift_networking/microshift-disconnected-network-config.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-disconnected-host-network-config_{context}"] += Configuring the networking settings for fully disconnected hosts + +To configure the networking settings for running {microshift-short} on a fully disconnected host, you must prepare the host, update the networking configuration, then restart to apply the new settings. All commands are executed from the host CLI. + +.Prerequisites +* RHEL 9 or newer. +* {microshift-short} 4.14 or newer. +* Access to the host CLI. +* A valid IP address chosen to avoid both internal and potential future external IP conflicts when running {microshift-short}. +* {microshift-short} networking settings are set to defaults. + +[IMPORTANT] +==== +The following procedure is for use cases in which access to the {microshift-short} cluster is not required after devices are deployed in the field. There is no remote cluster access after the network connection is removed. +==== + +.Procedure + +. Add a fake IP address to the loopback interface by running the following command: ++ +[source,terminal] +---- +$ IP="10.44.0.1" <1> +$ sudo nmcli con add type loopback con-name stable-microshift ifname lo ip4 ${IP}/32 +---- +<1> The fake IP address used in this example is “10.44.0.1”. ++ +[NOTE] +==== +Any valid IP works if it avoids both internal {microshift-short} and potential future external IP conflicts. This can be any subnet that does not collide with the {microshift-short} node subnet or is be accessed by other services on the device. +==== + +. Configure the DNS interface to use the local name server by setting modifying the settings to ignore automatic DNS and reset it to the local name server: ++ +.. Bypass the automatic DNS by running the following command: ++ +[source,terminal] +---- +$ sudo nmcli conn modify stable-microshift ipv4.ignore-auto-dns yes +---- ++ +.. Point the DNS interface to use the local name server: ++ +[source,terminal] +---- +$ sudo nmcli conn modify stable-microshift ipv4.dns "10.44.1.1" +---- + +. Get the hostname of the device by running the following command: ++ +[source,terminal] +---- +$ NAME="$(hostnamectl hostname)" +---- + +. Add an entry for the hostname of the node in the `/etc/hosts` file by running the following command: ++ +[source,terminal] +---- +$ echo "$IP $NAME" | sudo tee -a /etc/hosts >/dev/null +---- + +. Update the {microshift-short} configuration file by adding the following YAML snippet to `/etc/microshift/config.yaml`: ++ +[source,terminal] +---- +sudo tee /etc/microshift/config.yaml > /dev/null < +---- +<1> This step restarts the cluster. Wait for the greenboot health check to report the system healthy before implementing verification. + +.Verification + +At this point, network access to the {microshift-short} host has been severed. If you have access to the host terminal, you can use the host CLI to verify that the cluster has started in a stable state. + +. Verify that the {microshift-short} cluster is running by entering the following command: ++ +[source,terminal] +---- +$ export KUBECONFIG=/var/lib/microshift/resources/kubeadmin/kubeconfig +$ sudo -E oc get pods -A +---- ++ +.Example output +[source,terminal] +---- +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system csi-snapshot-controller-74d566564f-66n2f 1/1 Running 0 1m +kube-system csi-snapshot-webhook-69bdff8879-xs6mb 1/1 Running 0 1m +openshift-dns dns-default-dxglm 2/2 Running 0 1m +openshift-dns node-resolver-dbf5v 1/1 Running 0 1m +openshift-ingress router-default-8575d888d8-xmq9p 1/1 Running 0 1m +openshift-ovn-kubernetes ovnkube-master-gcsx8 4/4 Running 1 1m +openshift-ovn-kubernetes ovnkube-node-757mf 1/1 Running 1 1m +openshift-service-ca service-ca-7d7c579f54-68jt4 1/1 Running 0 1m +openshift-storage topolvm-controller-6d777f795b-bx22r 5/5 Running 0 1m +openshift-storage topolvm-node-fcf8l 4/4 Running 0 1m +---- diff --git a/modules/microshift-undo-network-config.adoc b/modules/microshift-undo-network-config.adoc new file mode 100644 index 0000000000..a33e150e56 --- /dev/null +++ b/modules/microshift-undo-network-config.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * microshift_networking/microshift-disconnected-network-config.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-undo-network-config_{context}"] += Restoring {microshift-short} networking settings to default + +You can remove networking customizations and return the network to default settings by stopping {microshift-short} and running a clean-up script. + +.Prerequisites +* RHEL 9 or newer. +* MicroShift 4.14 or newer. +* Access to the host CLI. + +.Procedure + +. Stop the {microshift-short} service by running the following command: ++ +[source,terminal] +---- +$ sudo systemctl stop microshift +---- + +. Stop the `kubepods.slice` systemd unit by running the following command: ++ +[source,terminal] +---- +$ sudo systemctl stop kubepods.slice +---- + +. {microshift-short} installs a helper script to undo network changes made by OVN-K. Run the cleanup script by entering the following command: ++ +[source,terminal] +---- +$ sudo /usr/bin/microshift-cleanup-data --ovn +---- + +//Q: any sample output? what should we see when we run the script? \ No newline at end of file