×

Troubleshooting the installation program workflow

Before troubleshooting the installation environment, it is critical to understand the overall flow of the installer-provisioned installation on bare metal. The following diagrams illustrate a troubleshooting flow with a step-by-step breakdown for the environment.

Flow-Diagram-1

Workflow 1 of 4 illustrates a troubleshooting workflow when the install-config.yaml file has errors or the Red Hat Enterprise Linux CoreOS (RHCOS) images are inaccessible. Troubleshooting suggestions can be found at Troubleshooting install-config.yaml.

Flow-Diagram-2

Workflow 2 of 4 illustrates a troubleshooting workflow for bootstrap VM issues, bootstrap VMs that cannot boot up the cluster nodes, and inspecting logs. When installing an OpenShift Container Platform cluster without the provisioning network, this workflow does not apply.

Flow-Diagram-3

Workflow 3 of 4 illustrates a troubleshooting workflow for cluster nodes that will not PXE boot. If installing using Redfish virtual media, each node must meet minimum firmware requirements for the installation program to deploy the node. See Firmware requirements for installing with virtual media in the Prerequisites section for additional details.

Flow-Diagram-4

Workflow 4 of 4 illustrates a troubleshooting workflow from a non-accessible API to a validated installation.

Troubleshooting install-config.yaml

The install-config.yaml configuration file represents all of the nodes that are part of the OpenShift Container Platform cluster. The file contains the necessary options consisting of but not limited to apiVersion, baseDomain, imageContentSources and virtual IP addresses. If errors occur early in the deployment of the OpenShift Container Platform cluster, the errors are likely in the install-config.yaml configuration file.

Procedure
  1. Use the guidelines in YAML-tips.

  2. Verify the YAML syntax is correct using syntax-check.

  3. Verify the Red Hat Enterprise Linux CoreOS (RHCOS) QEMU images are properly defined and accessible via the URL provided in the install-config.yaml. For example:

    $ curl -s -o /dev/null -I -w "%{http_code}\n" http://webserver.example.com:8080/rhcos-44.81.202004250133-0-qemu.<architecture>.qcow2.gz?sha256=7d884b46ee54fe87bbc3893bf2aa99af3b2d31f2e19ab5529c60636fbd0f1ce7

    If the output is 200, there is a valid response from the webserver storing the bootstrap VM image.

Bootstrap VM issues

The OpenShift Container Platform installation program spawns a bootstrap node virtual machine, which handles provisioning the OpenShift Container Platform cluster nodes.

Procedure
  1. About 10 to 15 minutes after triggering the installation program, check to ensure the bootstrap VM is operational using the virsh command:

    $ sudo virsh list
     Id    Name                           State
     --------------------------------------------
     12    openshift-xf6fq-bootstrap      running

    The name of the bootstrap VM is always the cluster name followed by a random set of characters and ending in the word "bootstrap."

    If the bootstrap VM is not running after 10-15 minutes, troubleshoot why it is not running. Possible issues include:

  2. Verify libvirtd is running on the system:

    $ systemctl status libvirtd
    ● libvirtd.service - Virtualization daemon
       Loaded: loaded (/usr/lib/systemd/system/libvirtd.service; enabled; vendor preset: enabled)
       Active: active (running) since Tue 2020-03-03 21:21:07 UTC; 3 weeks 5 days ago
         Docs: man:libvirtd(8)
               https://libvirt.org
     Main PID: 9850 (libvirtd)
        Tasks: 20 (limit: 32768)
       Memory: 74.8M
       CGroup: /system.slice/libvirtd.service
               ├─ 9850 /usr/sbin/libvirtd

    If the bootstrap VM is operational, log in to it.

  3. Use the virsh console command to find the IP address of the bootstrap VM:

    $ sudo virsh console example.com
    Connected to domain example.com
    Escape character is ^]
    Red Hat Enterprise Linux CoreOS 43.81.202001142154.0 (Ootpa) 4.3
    SSH host key: SHA256:BRWJktXZgQQRY5zjuAV0IKZ4WM7i4TiUyMVanqu9Pqg (ED25519)
    SSH host key: SHA256:7+iKGA7VtG5szmk2jB5gl/5EZ+SNcJ3a2g23o0lnIio (ECDSA)
    SSH host key: SHA256:DH5VWhvhvagOTaLsYiVNse9ca+ZSW/30OOMed8rIGOc (RSA)
    ens3:  fd35:919d:4042:2:c7ed:9a9f:a9ec:7
    ens4: 172.22.0.2 fe80::1d05:e52e:be5d:263f
    localhost login:

    When deploying an OpenShift Container Platform cluster without the provisioning network, you must use a public IP address and not a private IP address like 172.22.0.2.

  4. After you obtain the IP address, log in to the bootstrap VM using the ssh command:

    In the console output of the previous step, you can use the IPv6 IP address provided by ens3 or the IPv4 IP provided by ens4.

    $ ssh core@172.22.0.2

If you are not successful logging in to the bootstrap VM, you have likely encountered one of the following scenarios:

  • You cannot reach the 172.22.0.0/24 network. Verify the network connectivity between the provisioner and the provisioning network bridge. This issue might occur if you are using a provisioning network. `

  • You cannot reach the bootstrap VM through the public network. When attempting to SSH via baremetal network, verify connectivity on the provisioner host specifically around the baremetal network bridge.

  • You encountered Permission denied (publickey,password,keyboard-interactive). When attempting to access the bootstrap VM, a Permission denied error might occur. Verify that the SSH key for the user attempting to log in to the VM is set within the install-config.yaml file.

Bootstrap VM cannot boot up the cluster nodes

During the deployment, it is possible for the bootstrap VM to fail to boot the cluster nodes, which prevents the VM from provisioning the nodes with the RHCOS image. This scenario can arise due to:

  • A problem with the install-config.yaml file.

  • Issues with out-of-band network access when using the baremetal network.

To verify the issue, there are three containers related to ironic:

  • ironic

  • ironic-inspector

Procedure
  1. Log in to the bootstrap VM:

    $ ssh core@172.22.0.2
  2. To check the container logs, execute the following:

    [core@localhost ~]$ sudo podman logs -f <container_name>

    Replace <container_name> with one of ironic or ironic-inspector. If you encounter an issue where the control plane nodes are not booting up from PXE, check the ironic pod. The ironic pod contains information about the attempt to boot the cluster nodes, because it attempts to log in to the node over IPMI.

Potential reason

The cluster nodes might be in the ON state when deployment started.

Solution

Power off the OpenShift Container Platform cluster nodes before you begin the installation over IPMI:

$ ipmitool -I lanplus -U root -P <password> -H <out_of_band_ip> power off

Inspecting logs

When experiencing issues downloading or accessing the RHCOS images, first verify that the URL is correct in the install-config.yaml configuration file.

Example of internal webserver hosting RHCOS images
bootstrapOSImage: http://<ip:port>/rhcos-43.81.202001142154.0-qemu.<architecture>.qcow2.gz?sha256=9d999f55ff1d44f7ed7c106508e5deecd04dc3c06095d34d36bf1cd127837e0c
clusterOSImage: http://<ip:port>/rhcos-43.81.202001142154.0-openstack.<architecture>.qcow2.gz?sha256=a1bda656fa0892f7b936fdc6b6a6086bddaed5dafacedcd7a1e811abb78fe3b0

The coreos-downloader container downloads resources from a webserver or from the external quay.io registry, whichever the install-config.yaml configuration file specifies. Verify that the coreos-downloader container is up and running and inspect its logs as needed.

Procedure
  1. Log in to the bootstrap VM:

    $ ssh core@172.22.0.2
  2. Check the status of the coreos-downloader container within the bootstrap VM by running the following command:

    [core@localhost ~]$ sudo podman logs -f coreos-downloader

    If the bootstrap VM cannot access the URL to the images, use the curl command to verify that the VM can access the images.

  3. To inspect the bootkube logs that indicate if all the containers launched during the deployment phase, execute the following:

    [core@localhost ~]$ journalctl -xe
    [core@localhost ~]$ journalctl -b -f -u bootkube.service
  4. Verify all the pods, including dnsmasq, mariadb, httpd, and ironic, are running:

    [core@localhost ~]$ sudo podman ps
  5. If there are issues with the pods, check the logs of the containers with issues. To check the logs of the ironic service, run the following command:

    [core@localhost ~]$ sudo podman logs ironic

Cluster nodes will not PXE boot

When OpenShift Container Platform cluster nodes will not PXE boot, execute the following checks on the cluster nodes that will not PXE boot. This procedure does not apply when installing an OpenShift Container Platform cluster without the provisioning network.

Procedure
  1. Check the network connectivity to the provisioning network.

  2. Ensure PXE is enabled on the NIC for the provisioning network and PXE is disabled for all other NICs.

  3. Verify that the install-config.yaml configuration file includes the rootDeviceHints parameter and boot MAC address for the NIC connected to the provisioning network. For example:

    control plane node settings
    bootMACAddress: 24:6E:96:1B:96:90 # MAC of bootable provisioning NIC
    Worker node settings
    bootMACAddress: 24:6E:96:1B:96:90 # MAC of bootable provisioning NIC

Unable to discover new bare metal hosts using the BMC

In some cases, the installation program will not be able to discover the new bare metal hosts and issue an error, because it cannot mount the remote virtual media share.

For example:

ProvisioningError 51s metal3-baremetal-controller Image provisioning failed: Deploy step deploy.deploy failed with BadRequestError: HTTP POST
https://<bmc_address>/redfish/v1/Managers/iDRAC.Embedded.1/VirtualMedia/CD/Actions/VirtualMedia.InsertMedia
returned code 400.
Base.1.8.GeneralError: A general error has occurred. See ExtendedInfo for more information
Extended information: [
  {
    "Message": "Unable to mount remote share https://<ironic_address>/redfish/boot-<uuid>.iso.",
    "MessageArgs": [
      "https://<ironic_address>/redfish/boot-<uuid>.iso"
    ],
    "MessageArgs@odata.count": 1,
    "MessageId": "IDRAC.2.5.RAC0720",
    "RelatedProperties": [
      "#/Image"
    ],
    "RelatedProperties@odata.count": 1,
    "Resolution": "Retry the operation.",
    "Severity": "Informational"
  }
].

In this situation, if you are using virtual media with an unknown certificate authority, you can configure your baseboard management controller (BMC) remote file share settings to trust an unknown certificate authority to avoid this error.

This resolution was tested on OpenShift Container Platform 4.11 with Dell iDRAC 9 and firmware version 5.10.50.

The API is not accessible

When the cluster is running and clients cannot access the API, domain name resolution issues might impede access to the API.

Procedure
  1. Hostname Resolution: Check the cluster nodes to ensure they have a fully qualified domain name, and not just localhost.localdomain. For example:

    $ hostname

    If a hostname is not set, set the correct hostname. For example:

    $ hostnamectl set-hostname <hostname>
  2. Incorrect Name Resolution: Ensure that each node has the correct name resolution in the DNS server using dig and nslookup. For example:

    $ dig api.<cluster_name>.example.com
    ; <<>> DiG 9.11.4-P2-RedHat-9.11.4-26.P2.el8 <<>> api.<cluster_name>.example.com
    ;; global options: +cmd
    ;; Got answer:
    ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 37551
    ;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 2
    
    ;; OPT PSEUDOSECTION:
    ; EDNS: version: 0, flags:; udp: 4096
    ; COOKIE: 866929d2f8e8563582af23f05ec44203d313e50948d43f60 (good)
    ;; QUESTION SECTION:
    ;api.<cluster_name>.example.com. IN A
    
    ;; ANSWER SECTION:
    api.<cluster_name>.example.com. 10800 IN	A 10.19.13.86
    
    ;; AUTHORITY SECTION:
    <cluster_name>.example.com. 10800 IN NS	<cluster_name>.example.com.
    
    ;; ADDITIONAL SECTION:
    <cluster_name>.example.com. 10800 IN A	10.19.14.247
    
    ;; Query time: 0 msec
    ;; SERVER: 10.19.14.247#53(10.19.14.247)
    ;; WHEN: Tue May 19 20:30:59 UTC 2020
    ;; MSG SIZE  rcvd: 140

    The output in the foregoing example indicates that the appropriate IP address for the api.<cluster_name>.example.com VIP is 10.19.13.86. This IP address should reside on the baremetal network.

Troubleshooting worker nodes that cannot join the cluster

Installer-provisioned clusters deploy with a DNS server that includes a DNS entry for the api-int.<cluster_name>.<base_domain> URL. If the nodes within the cluster use an external or upstream DNS server to resolve the api-int.<cluster_name>.<base_domain> URL and there is no such entry, worker nodes might fail to join the cluster. Ensure that all nodes in the cluster can resolve the domain name.

Procedure
  1. Add a DNS A/AAAA or CNAME record to internally identify the API load balancer. For example, when using dnsmasq, modify the dnsmasq.conf configuration file:

    $ sudo nano /etc/dnsmasq.conf
    address=/api-int.<cluster_name>.<base_domain>/<IP_address>
    address=/api-int.mycluster.example.com/192.168.1.10
    address=/api-int.mycluster.example.com/2001:0db8:85a3:0000:0000:8a2e:0370:7334
  2. Add a DNS PTR record to internally identify the API load balancer. For example, when using dnsmasq, modify the dnsmasq.conf configuration file:

    $ sudo nano /etc/dnsmasq.conf
    ptr-record=<IP_address>.in-addr.arpa,api-int.<cluster_name>.<base_domain>
    ptr-record=10.1.168.192.in-addr.arpa,api-int.mycluster.example.com
  3. Restart the DNS server. For example, when using dnsmasq, execute the following command:

    $ sudo systemctl restart dnsmasq

These records must be resolvable from all the nodes within the cluster.

Cleaning up previous installations

In case of an earlier failed deployment, remove the artifacts from the failed attempt before trying to deploy OpenShift Container Platform again.

Procedure
  1. Power off all bare-metal nodes before installing the OpenShift Container Platform cluster by using the following command:

    $ ipmitool -I lanplus -U <user> -P <password> -H <management_server_ip> power off
  2. Remove all old bootstrap resources if any remain from an earlier deployment attempt by using the following script:

    for i in $(sudo virsh list | tail -n +3 | grep bootstrap | awk {'print $2'});
    do
      sudo virsh destroy $i;
      sudo virsh undefine $i;
      sudo virsh vol-delete $i --pool $i;
      sudo virsh vol-delete $i.ign --pool $i;
      sudo virsh pool-destroy $i;
      sudo virsh pool-undefine $i;
    done
  3. Delete the artifacts that the earlier installation generated by using the following command:

    $ cd ; /bin/rm -rf auth/ bootstrap.ign master.ign worker.ign metadata.json \
    .openshift_install.log .openshift_install_state.json
  4. Re-create the OpenShift Container Platform manifests by using the following command:

    $ ./openshift-baremetal-install --dir ~/clusterconfigs create manifests

Issues with creating the registry

When creating a disconnected registry, you might encounter a "User Not Authorized" error when attempting to mirror the registry. This error might occur if you fail to append the new authentication to the existing pull-secret.txt file.

Procedure
  1. Check to ensure authentication is successful:

    $ /usr/local/bin/oc adm release mirror \
      -a pull-secret-update.json
      --from=$UPSTREAM_REPO \
      --to-release-image=$LOCAL_REG/$LOCAL_REPO:${VERSION} \
      --to=$LOCAL_REG/$LOCAL_REPO

    Example output of the variables used to mirror the install images:

    UPSTREAM_REPO=${RELEASE_IMAGE}
    LOCAL_REG=<registry_FQDN>:<registry_port>
    LOCAL_REPO='ocp4/openshift4'

    The values of RELEASE_IMAGE and VERSION were set during the Retrieving OpenShift Installer step of the Setting up the environment for an OpenShift installation section.

  2. After mirroring the registry, confirm that you can access it in your disconnected environment:

    $ curl -k -u <user>:<password> https://registry.example.com:<registry_port>/v2/_catalog
    {"repositories":["<Repo_Name>"]}

Miscellaneous issues

Addressing the runtime network not ready error

After the deployment of a cluster you might receive the following error:

`runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: Missing CNI default network`

The Cluster Network Operator is responsible for deploying the networking components in response to a special object created by the installer. It runs very early in the installation process, after the control plane (master) nodes have come up, but before the bootstrap control plane has been torn down. It can be indicative of more subtle installer issues, such as long delays in bringing up control plane (master) nodes or issues with apiserver communication.

Procedure
  1. Inspect the pods in the openshift-network-operator namespace:

    $ oc get all -n openshift-network-operator
    NAME                                    READY STATUS            RESTARTS   AGE
    pod/network-operator-69dfd7b577-bg89v   0/1   ContainerCreating 0          149m
  2. On the provisioner node, determine that the network configuration exists:

    $ kubectl get network.config.openshift.io cluster -oyaml
    apiVersion: config.openshift.io/v1
    kind: Network
    metadata:
      name: cluster
    spec:
      serviceNetwork:
      - 172.30.0.0/16
      clusterNetwork:
      - cidr: 10.128.0.0/14
        hostPrefix: 23
      networkType: OVNKubernetes

    If it does not exist, the installer did not create it. To determine why the installer did not create it, execute the following:

    $ openshift-install create manifests
  3. Check that the network-operator is running:

    $ kubectl -n openshift-network-operator get pods
  4. Retrieve the logs:

    $ kubectl -n openshift-network-operator logs -l "name=network-operator"

    On high availability clusters with three or more control plane (master) nodes, the Operator will perform leader election and all other Operators will sleep. For additional details, see Troubleshooting.

Addressing the "No disk found with matching rootDeviceHints" error message

After you deploy a cluster, you might receive the following error message:

No disk found with matching rootDeviceHints

To address the No disk found with matching rootDeviceHints error message, a temporary workaround is to change the rootDeviceHints to minSizeGigabytes: 300.

After you change the rootDeviceHints settings, boot the CoreOS and then verify the disk information by using the following command:

$ udevadm info /dev/sda

If you are using DL360 Gen 10 servers, be aware that they have an SD-card slot that might be assigned the /dev/sda device name. If no SD card is present in the server, it can cause conflicts. Ensure that the SD card slot is disabled in the server’s BIOS settings.

If the minSizeGigabytes workaround is not fulfilling the requirements, you might need to revert rootDeviceHints back to /dev/sda. This change allows ironic images to boot successfully.

An alternative approach to fixing this problem is by using the serial ID of the disk. However, be aware that finding the serial ID can be challenging and might make the configuration file less readable. If you choose this path, ensure that you gather the serial ID using the previously documented command and incorporate it into your configuration.

Cluster nodes not getting the correct IPv6 address over DHCP

If the cluster nodes are not getting the correct IPv6 address over DHCP, check the following:

  1. Ensure the reserved IPv6 addresses reside outside the DHCP range.

  2. In the IP address reservation on the DHCP server, ensure the reservation specifies the correct DHCP Unique Identifier (DUID). For example:

    # This is a dnsmasq dhcp reservation, 'id:00:03:00:01' is the client id and '18:db:f2:8c:d5:9f' is the MAC Address for the NIC
    id:00:03:00:01:18:db:f2:8c:d5:9f,openshift-master-1,[2620:52:0:1302::6]
  3. Ensure that route announcements are working.

  4. Ensure that the DHCP server is listening on the required interfaces serving the IP address ranges.

Cluster nodes not getting the correct hostname over DHCP

During IPv6 deployment, cluster nodes must get their hostname over DHCP. Sometimes the NetworkManager does not assign the hostname immediately. A control plane (master) node might report an error such as:

Failed Units: 2
  NetworkManager-wait-online.service
  nodeip-configuration.service

This error indicates that the cluster node likely booted without first receiving a hostname from the DHCP server, which causes kubelet to boot with a localhost.localdomain hostname. To address the error, force the node to renew the hostname.

Procedure
  1. Retrieve the hostname:

    [core@master-X ~]$ hostname

    If the hostname is localhost, proceed with the following steps.

    Where X is the control plane node number.

  2. Force the cluster node to renew the DHCP lease:

    [core@master-X ~]$ sudo nmcli con up "<bare_metal_nic>"

    Replace <bare_metal_nic> with the wired connection corresponding to the baremetal network.

  3. Check hostname again:

    [core@master-X ~]$ hostname
  4. If the hostname is still localhost.localdomain, restart NetworkManager:

    [core@master-X ~]$ sudo systemctl restart NetworkManager
  5. If the hostname is still localhost.localdomain, wait a few minutes and check again. If the hostname remains localhost.localdomain, repeat the previous steps.

  6. Restart the nodeip-configuration service:

    [core@master-X ~]$ sudo systemctl restart nodeip-configuration.service

    This service will reconfigure the kubelet service with the correct hostname references.

  7. Reload the unit files definition since the kubelet changed in the previous step:

    [core@master-X ~]$ sudo systemctl daemon-reload
  8. Restart the kubelet service:

    [core@master-X ~]$ sudo systemctl restart kubelet.service
  9. Ensure kubelet booted with the correct hostname:

    [core@master-X ~]$ sudo journalctl -fu kubelet.service

If the cluster node is not getting the correct hostname over DHCP after the cluster is up and running, such as during a reboot, the cluster will have a pending csr. Do not approve a csr, or other issues might arise.

Addressing a csr
  1. Get CSRs on the cluster:

    $ oc get csr
  2. Verify if a pending csr contains Subject Name: localhost.localdomain:

    $ oc get csr <pending_csr> -o jsonpath='{.spec.request}' | base64 --decode | openssl req -noout -text
  3. Remove any csr that contains Subject Name: localhost.localdomain:

    $