1. Documentation
×

Understand single-node OpenShift network reconfiguration

Use the Lifecycle Agent to change the network configuration of a single-node OpenShift cluster without performing a full redeployment. This is critical for many edge computing use cases such as disaster recovery and network rehoming.

Use cases for single-node OpenShift network reconfiguration

At the network far edge, changing a single-node OpenShift cluster’s core networking is an essential operation in many scenarios. For example, during disaster recovery, mobile deployments, or network migrations, you might need to change node IP addresses, gateways, DNS servers, or VLAN settings. However, these operations are high-risk because a misconfiguration can make the cluster unreachable and require a full redeployment.

The Lifecycle Agent uses the IPConfig custom resource (CR) to provide a declarative, stage-driven workflow that performs these changes safely and without a full cluster redeployment.

The following use cases highlight key scenarios for single-node OpenShift network reconfiguration:

Disaster recovery

After a site outage or major connectivity change, a single-node OpenShift cluster might need to move to a different uplink network. For example, you can reconfigure a cluster to use an IPv4 satellite connection as a backup if a primary 5G IPv6 network goes down.

Temporary and mobile deployments

Mobile infrastructure, such as cell-on-wheels units or new cell sites, often relies on temporary network connections. You can reconfigure these clusters as they move between uplink networks.

IoT network transitions

IoT gateway clusters at remote sites can be reconfigured when the underlying network infrastructure changes, such as switching ISPs or migrating to new IP address ranges across a facility.

Network consolidation and equipment upgrades

During network consolidation or infrastructure upgrades, you can migrate single-node OpenShift clusters to a new L2 or L3 environment with a deterministic, reversible process and minimal downtime.

Workflow for single-node OpenShift network reconfiguration

The Lifecycle Agent uses a stage-driven workflow controlled through the spec.stage field in the IPConfig CR. The workflow consists of three stages.

single-node OpenShift network reconfiguration stages
Figure 1. single-node OpenShift network reconfiguration stages
Idle stage

The initial and final stage. In this stage, the Lifecycle Agent runs health checks, performs cleanup operations, and prepares the cluster for configuration changes. Transitioning to Idle after a successful configuration is the finalization point that removes rollback capability.

Config stage

Executes the network reconfiguration in two phases. The pre-pivot phase prepares a new stateroot, which is a bootable system state that has the updated network configuration, and reboots into it. The post-pivot phase applies the network changes, regenerates certificates, and waits for cluster stabilization.

Rollback stage

Reboots into the earlier stateroot. You can trigger a rollback manually or configure automatic rollback on failure.

The network reconfiguration flow preserves the currently booted stateroot as a rollback target while preparing the new configuration in a new stateroot. This approach means the original configuration remains available for rollback until you finalize the change, only one reboot is required for the IP change, and the rollback process is fast because the earlier stateroot is already prepared.

Supported network property changes

The IPConfig CR supports the following network property changes:

  • IPv4 and IPv6 address changes for single-stack or dual-stack clusters

  • Machine network CIDR changes

  • Default gateway changes

  • DNS server list updates

  • Optional VLAN ID changes on the br-ex uplink path

  • Optional DNS response filtering changes on dual-stack clusters to filter IPv4 or IPv6

Requirements and limitations for network reconfiguration

Network reconfiguration by using the IPConfig CR has the following requirements:

  • The cluster must be a single-node OpenShift cluster.

  • The Lifecycle Agent must be installed.

  • A baseline dnsmasq MachineConfig resource must exist, which is automatically installed by any single-node OpenShift installed directly or indirectly by the Assisted Installer, including Agent-based Installer (ABI), multicluster engine (MCE), and Red Hat Advanced Cluster Management (RHACM).

  • All cluster operators must be available before starting a network reconfiguration.

Network reconfiguration by using the IPConfig CR has the following limitations:

  • For dual-stack clusters, exactly one IPv4 address and one IPv6 address are supported per node.

  • Only one NIC is supported. No bonding or link aggregation.

  • You can configure a maximum of one VLAN ID on the br-ex uplink path.

  • You must configure static networking on the host network. DHCP is not supported.

  • You cannot add a VLAN to a cluster that does not already have VLAN configuration.

  • Changing gateway or machine network without changing the address is not supported.

  • Changing DNS servers without changing at least one IP address is not supported.

  • You cannot set spec.ipv4 on an IPv6-only cluster or spec.ipv6 on an IPv4-only cluster.

  • The resulting routing table must not have routes that overlap or conflict with the default route through the configured gateways.

  • The cluster must not have a proxy network configuration.

  • You cannot perform an image-based upgrade and a network reconfiguration at the same time.

Additional resources