Troubleshooting the installation program workflow

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


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.


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.


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.


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.

  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.

Troubleshooting bootstrap VM issues

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

  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."

  2. If the bootstrap VM is not running after 10-15 minutes, verify libvirtd is running on the system by executing the following command:

    $ 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)
     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: 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

  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@

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

  • You cannot reach the 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

  1. Log in to the bootstrap VM:

    $ ssh core@
  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.


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.

  1. Log in to the bootstrap VM:

    $ ssh core@
  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

Investigating an unavailable Kubernetes API

When the Kubernetes API is unavailable, check the control plane nodes to ensure that they are running the correct components. Also, check the hostname resolution.

  1. Ensure that etcd is running on each of the control plane nodes by running the following command:

    $ sudo crictl logs $(sudo crictl ps --pod=$(sudo crictl pods --name=etcd-member --quiet) --quiet)
  2. If the previous command fails, ensure that Kubelet created the etcd pods by running the following command:

    $ sudo crictl pods --name=etcd-member

    If there are no pods, investigate etcd.

  3. Check the cluster nodes to ensure they have a fully qualified domain name, and not just localhost.localdomain, by using the following command:

    $ hostname

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

    $ sudo hostnamectl set-hostname <hostname>
  4. Ensure that each node has the correct name resolution in the DNS server using the dig command:

    $ 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
    ; EDNS: version: 0, flags:; udp: 4096
    ; COOKIE: 866929d2f8e8563582af23f05ec44203d313e50948d43f60 (good)
    ;api.<cluster_name>.example.com. IN A
    api.<cluster_name>.example.com. 10800 IN	A
    <cluster_name>.example.com. 10800 IN NS	<cluster_name>.example.com.
    <cluster_name>.example.com. 10800 IN A
    ;; Query time: 0 msec
    ;; SERVER:
    ;; 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 This IP address should reside on the baremetal network.

Troubleshooting a failure to initialize the cluster

The installation program uses the Cluster Version Operator to create all the components of an OpenShift Container Platform cluster. When the installation program fails to initialize the cluster, you can retrieve the most important information from the ClusterVersion and ClusterOperator objects.

  1. Inspect the ClusterVersion object by running the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusterversion -o yaml
    Example output
    apiVersion: config.openshift.io/v1
    kind: ClusterVersion
      creationTimestamp: 2019-02-27T22:24:21Z
      generation: 1
      name: version
      resourceVersion: "19927"
      selfLink: /apis/config.openshift.io/v1/clusterversions/version
      uid: 6e0f4cf8-3ade-11e9-9034-0a923b47ded4
      channel: stable-4.1
      clusterID: 5ec312f9-f729-429d-a454-61d4906896ca
      availableUpdates: null
      - lastTransitionTime: 2019-02-27T22:50:30Z
        message: Done applying 4.1.1
        status: "True"
        type: Available
      - lastTransitionTime: 2019-02-27T22:50:30Z
        status: "False"
        type: Failing
      - lastTransitionTime: 2019-02-27T22:50:30Z
        message: Cluster version is 4.1.1
        status: "False"
        type: Progressing
      - lastTransitionTime: 2019-02-27T22:24:31Z
        message: 'Unable to retrieve available updates: unknown version 4.1.1
        reason: RemoteFailed
        status: "False"
        type: RetrievedUpdates
        image: registry.svc.ci.openshift.org/openshift/origin-release@sha256:91e6f754975963e7db1a9958075eb609ad226968623939d262d1cf45e9dbc39a
        version: 4.1.1
      - completionTime: 2019-02-27T22:50:30Z
        image: registry.svc.ci.openshift.org/openshift/origin-release@sha256:91e6f754975963e7db1a9958075eb609ad226968623939d262d1cf45e9dbc39a
        startedTime: 2019-02-27T22:24:31Z
        state: Completed
        version: 4.1.1
      observedGeneration: 1
      versionHash: Wa7as_ik1qE=
  2. View the conditions by running the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusterversion version \
         -o=jsonpath='{range .status.conditions[*]}{.type}{" "}{.status}{" "}{.message}{"\n"}{end}'

    Some of most important conditions include Failing, Available and Progressing.

    Example output
    Available True Done applying 4.1.1
    Failing False
    Progressing False Cluster version is 4.0.0-0.alpha-2019-02-26-194020
    RetrievedUpdates False Unable to retrieve available updates: unknown version 4.1.1
  3. Inspect the ClusterOperator object by running the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusteroperator

    The command returns the status of the cluster Operators.

    Example output
    NAME                                  VERSION   AVAILABLE   PROGRESSING   FAILING   SINCE
    cluster-baremetal-operator                      True        False         False     17m
    cluster-autoscaler                              True        False         False     17m
    cluster-storage-operator                        True        False         False     10m
    console                                         True        False         False     7m21s
    dns                                             True        False         False     31m
    image-registry                                  True        False         False     9m58s
    ingress                                         True        False         False     10m
    kube-apiserver                                  True        False         False     28m
    kube-controller-manager                         True        False         False     21m
    kube-scheduler                                  True        False         False     25m
    machine-api                                     True        False         False     17m
    machine-config                                  True        False         False     17m
    marketplace-operator                            True        False         False     10m
    monitoring                                      True        False         False     8m23s
    network                                         True        False         False     13m
    node-tuning                                     True        False         False     11m
    openshift-apiserver                             True        False         False     15m
    openshift-authentication                        True        False         False     20m
    openshift-cloud-credential-operator             True        False         False     18m
    openshift-controller-manager                    True        False         False     10m
    openshift-samples                               True        False         False     8m42s
    operator-lifecycle-manager                      True        False         False     17m
    service-ca                                      True        False         False     30m
  4. Inspect individual cluster Operators by running the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusteroperator <operator> -oyaml (1)
    1 Replace <operator> with the name of a cluster Operator. This command is useful for identifying why an cluster Operator has not achieved the Available state or is in the Failed state.
    Example output
    apiVersion: config.openshift.io/v1
    kind: ClusterOperator
      creationTimestamp: 2019-02-27T22:47:04Z
      generation: 1
      name: monitoring
      resourceVersion: "24677"
      selfLink: /apis/config.openshift.io/v1/clusteroperators/monitoring
      uid: 9a6a5ef9-3ae1-11e9-bad4-0a97b6ba9358
    spec: {}
      - lastTransitionTime: 2019-02-27T22:49:10Z
        message: Successfully rolled out the stack.
        status: "True"
        type: Available
      - lastTransitionTime: 2019-02-27T22:49:10Z
        status: "False"
        type: Progressing
      - lastTransitionTime: 2019-02-27T22:49:10Z
        status: "False"
        type: Failing
      extension: null
      relatedObjects: null
      version: ""
  5. To get the cluster Operator’s status condition, run the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusteroperator <operator> \
         -o=jsonpath='{range .status.conditions[*]}{.type}{" "}{.status}{" "}{.message}{"\n"}{end}'

    Replace <operator> with the name of one of the operators above.

    Example output
    Available True Successfully rolled out the stack
    Progressing False
    Failing False
  6. To retrieve the list of objects owned by the cluster Operator, execute the following command:

    oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusteroperator kube-apiserver \
    Example output
    [map[resource:kubeapiservers group:operator.openshift.io name:cluster] map[group: name:openshift-config resource:namespaces] map[group: name:openshift-config-managed resource:namespaces] map[group: name:openshift-kube-apiserver-operator resource:namespaces] map[group: name:openshift-kube-apiserver resource:namespaces]]

Troubleshooting a failure to fetch the console URL

The installation program retrieves the URL for the OpenShift Container Platform console by using [route][route-object] within the openshift-console namespace. If the installation program fails the retrieve the URL for the console, use the following procedure.

  1. Check if the console router is in the Available or Failing state by running the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get clusteroperator console -oyaml
    apiVersion: config.openshift.io/v1
    kind: ClusterOperator
      creationTimestamp: 2019-02-27T22:46:57Z
      generation: 1
      name: console
      resourceVersion: "19682"
      selfLink: /apis/config.openshift.io/v1/clusteroperators/console
      uid: 960364aa-3ae1-11e9-bad4-0a97b6ba9358
    spec: {}
      - lastTransitionTime: 2019-02-27T22:46:58Z
        status: "False"
        type: Failing
      - lastTransitionTime: 2019-02-27T22:50:12Z
        status: "False"
        type: Progressing
      - lastTransitionTime: 2019-02-27T22:50:12Z
        status: "True"
        type: Available
      - lastTransitionTime: 2019-02-27T22:46:57Z
        status: "True"
        type: Upgradeable
      extension: null
      - group: operator.openshift.io
        name: cluster
        resource: consoles
      - group: config.openshift.io
        name: cluster
        resource: consoles
      - group: oauth.openshift.io
        name: console
        resource: oauthclients
      - group: ""
        name: openshift-console-operator
        resource: namespaces
      - group: ""
        name: openshift-console
        resource: namespaces
      versions: null
  2. Manually retrieve the console URL by executing the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get route console -n openshift-console \
         -o=jsonpath='{.spec.host}' console-openshift-console.apps.adahiya-1.devcluster.openshift.com

Troubleshooting a failure to add the ingress certificate to kubeconfig

The installation program adds the default ingress certificate to the list of trusted client certificate authorities in ${INSTALL_DIR}/auth/kubeconfig. If the installation program fails to add the ingress certificate to the kubeconfig file, you can retrieve the certificate from the cluster and add it.

  1. Retrieve the certificate from the cluster using the following command:

    $ oc --kubeconfig=${INSTALL_DIR}/auth/kubeconfig get configmaps default-ingress-cert \
         -n openshift-config-managed -o=jsonpath='{.data.ca-bundle\.crt}'
    -----END CERTIFICATE-----
  2. Add the certificate to the client-certificate-authority-data field in the ${INSTALL_DIR}/auth/kubeconfig file.

Troubleshooting SSH access to cluster nodes

For added security, you cannot SSH into the cluster from outside the cluster by default. However, you can access control plane and worker nodes from the provisioner node. If you cannot SSH into the cluster nodes from the provisioner node, the nodes might be waiting on the bootstrap VM. The control plane nodes retrieve their boot configuration from the bootstrap VM, and they cannot boot successfully if they do not retrieve the boot configuration.

  1. If you have physical access to the nodes, check their console output to determine if they have successfully booted. If the nodes are still retrieving their boot configuration, there might be problems with the bootstrap VM .

  2. Ensure you have configured the sshKey: '<ssh_pub_key>' setting in the install-config.yaml file, where <ssh_pub_key> is the public key of the kni user on the provisioner node.

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.

  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