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 and workflow for single-node OpenShift network reconfiguration

Changing a single-node OpenShift cluster’s core networking, such as node IP addresses, machine network CIDRs, default gateway, VLAN, and DNS settings, is a high-risk operation because it affects both host networking and cluster configuration. The Lifecycle Agent provides a declarative, stage-driven workflow to perform these changes safely using the IPConfig custom resource (CR).

Network reconfiguration addresses critical edge computing scenarios where changing network properties without a full cluster redeployment is essential:

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, if a primary 5G network using IPv6 goes down due to a natural disaster, you can reconfigure the cluster to use an IPv4 satellite connection as a backup, enabling continued operations until the primary network is restored.

Network rehoming and site migration

During network consolidation or equipment upgrades, you can migrate single-node OpenShift clusters to a new L2 or L3 environment with a deterministic, reversible process and minimal downtime. This supports scenarios such as cell on wheels for increased cellular coverage at events, mobile satellite telco equipment changing networks, IoT devices transitioning between networks, and new cell site deployments using satellite connectivity until physical network installation is complete.

The Lifecycle Agent uses a stage-driven workflow controlled through the spec.stage field in the IPConfig CR. The workflow consists of three 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