1. Documentation
×

Troubleshoot single-node OpenShift network reconfiguration

Use the following information to diagnose and resolve network reconfiguration issues on single-node OpenShift clusters.

Gather diagnostic information for network reconfiguration issues

You can gather diagnostic information to help troubleshoot network reconfiguration issues on single-node OpenShift clusters.

Procedure

  1. Inspect the IPConfig custom resource (CR) status by running the following command:

    $ oc get ipc ipconfig -o yaml

    Review the status.conditions field for the current state, reason, and message. Check status.validNextStages for possible stage transitions, and status.history for timestamps of stage progression.

  2. View the Lifecycle Agent controller logs by running the following command:

    $ oc logs -n openshift-lifecycle-agent deployment/lifecycle-agent-controller-manager -c manager

  3. Create a debug session on the target node by running the following command:

    $ oc debug node/<node_name>
# chroot /host

    • Replace <node_name> with the name of your single-node OpenShift node.

  4. View the relevant service logs depending on which phase you are troubleshooting by running one of the following commands:

    • View the logs for pre-pivot issues by running the following command:

      $ sudo journalctl -u lca-ipconfig-pre-pivot -b --no-pager

    • View the logs for post-pivot issues by running the following command:

      $ sudo journalctl -u ip-configuration.service -b --no-pager

    • View the logs for init-monitor watchdog issues by running the following command:

      $ sudo journalctl -u lca-init-monitor.service -b --no-pager

    • View the logs for rollback issues by running the following command:

      $ sudo journalctl -u lca-ipconfig-rollback -b --no-pager

Network reconfiguration troubleshooting reference

Use the following reference information to help diagnose and resolve network reconfiguration issues on single-node OpenShift clusters.

Table 1. On-node artifacts for troubleshooting
File Description

/var/lib/lca/workspace/ip-config-pre-pivot.json

Pre-pivot configuration data

/var/lib/lca/workspace/ip-config-post-pivot.json

Post-pivot configuration data

/var/lib/lca/workspace/nmstate.yaml

Generated nmstate configuration for network changes

/var/lib/lca/workspace/recert_config.json

Configuration for certificate regeneration

/var/lib/lca/workspace/ip-config-autorollback-config.json

Auto-rollback configuration

/var/lib/lca/workspace/recert-pull-secret.json

Pull secret for the recert image, if a custom pull secret was specified

/var/lib/lca/ipc.json

Persistence file that stores IPConfig state for rollback and status continuity across restarts
Table 2. Common failure patterns
Issue Cause Solution

Stage transition rejected

You attempted to transition to a stage not in status.validNextStages.

Check status.validNextStages and only transition to an allowed stage.

Specification fields cannot be changed

You attempted to modify spec fields while the CR is not in the Idle stage.

Wait for the current operation to complete and the CR to return to Idle.

Health checks never pass

Cluster health blockers are preventing progress.

Investigate cluster health issues.

Post-pivot phase failed

An error occurred during network configuration or certificate regeneration.

Review the post-pivot service logs. If auto-rollback is enabled, the node automatically reverts. Otherwise, manually trigger rollback by setting spec.stage: Rollback.

Pods not receiving new IP family

Pre-existing pods might not automatically receive an IP address from the new family because of CNI behavior.

Delete and re-create the affected pods to obtain addresses from the new IP family.

Configuration stuck in disconnected environment

The Lifecycle Agent or recert container might be attempting to pull images not available in the disconnected registry.

Ensure all required images are mirrored to your disconnected registry before starting. Verify the lca.openshift.io/recert-pull-secret annotation references a valid pull secret.
Additional resources