Este contenido no está disponible en el idioma seleccionado.
Chapter 25. Troubleshooting installation issues
To assist in troubleshooting a failed OpenShift Container Platform installation, you can gather logs from the bootstrap and control plane machines. You can also get debug information from the installation program. If you are unable to resolve the issue using the logs and debug information, see Determining where installation issues occur for component-specific troubleshooting.
If your OpenShift Container Platform installation fails and the debug output or logs contain network timeouts or other connectivity errors, review the guidelines for configuring your firewall. Gathering logs from your firewall and load balancer can help you diagnose network-related errors.
25.1. Prerequisites
- You attempted to install an OpenShift Container Platform cluster and the installation failed.
25.2. Gathering logs from a failed installation
If you gave an SSH key to your installation program, you can gather data about your failed installation.
You use a different command to gather logs about an unsuccessful installation than to gather logs from a running cluster. If you must gather logs from a running cluster, use the oc adm must-gather
command.
Prerequisites
- Your OpenShift Container Platform installation failed before the bootstrap process finished. The bootstrap node is running and accessible through SSH.
-
The
ssh-agent
process is active on your computer, and you provided the same SSH key to both thessh-agent
process and the installation program. - If you tried to install a cluster on infrastructure that you provisioned, you must have the fully qualified domain names of the bootstrap and control plane nodes.
Procedure
Generate the commands that are required to obtain the installation logs from the bootstrap and control plane machines:
If you used installer-provisioned infrastructure, change to the directory that contains the installation program and run the following command:
$ ./openshift-install gather bootstrap --dir <installation_directory> 1
- 1
installation_directory
is the directory you specified when you ran./openshift-install create cluster
. This directory contains the OpenShift Container Platform definition files that the installation program creates.
For installer-provisioned infrastructure, the installation program stores information about the cluster, so you do not specify the hostnames or IP addresses.
If you used infrastructure that you provisioned yourself, change to the directory that contains the installation program and run the following command:
$ ./openshift-install gather bootstrap --dir <installation_directory> \ 1 --bootstrap <bootstrap_address> \ 2 --master <master_1_address> \ 3 --master <master_2_address> \ 4 --master <master_3_address>" 5
- 1
- For
installation_directory
, specify the same directory you specified when you ran./openshift-install create cluster
. This directory contains the OpenShift Container Platform definition files that the installation program creates. - 2
<bootstrap_address>
is the fully qualified domain name or IP address of the cluster’s bootstrap machine.- 3 4 5
- For each control plane, or master, machine in your cluster, replace
<master_*_address>
with its fully qualified domain name or IP address.
NoteA default cluster contains three control plane machines. List all of your control plane machines as shown, no matter how many your cluster uses.
Example output
INFO Pulling debug logs from the bootstrap machine INFO Bootstrap gather logs captured here "<installation_directory>/log-bundle-<timestamp>.tar.gz"
If you open a Red Hat support case about your installation failure, include the compressed logs in the case.
25.3. Manually gathering logs with SSH access to your host(s)
Manually gather logs in situations where must-gather
or automated collection methods do not work.
By default, SSH access to the OpenShift Container Platform nodes is disabled on the Red Hat OpenStack Platform (RHOSP) based installations.
Prerequisites
- You must have SSH access to your host(s).
Procedure
Collect the
bootkube.service
service logs from the bootstrap host using thejournalctl
command by running:$ journalctl -b -f -u bootkube.service
Collect the bootstrap host’s container logs using the podman logs. This is shown as a loop to get all of the container logs from the host:
$ for pod in $(sudo podman ps -a -q); do sudo podman logs $pod; done
Alternatively, collect the host’s container logs using the
tail
command by running:# tail -f /var/lib/containers/storage/overlay-containers/*/userdata/ctr.log
Collect the
kubelet.service
andcrio.service
service logs from the master and worker hosts using thejournalctl
command by running:$ journalctl -b -f -u kubelet.service -u crio.service
Collect the master and worker host container logs using the
tail
command by running:$ sudo tail -f /var/log/containers/*
25.4. Manually gathering logs without SSH access to your host(s)
Manually gather logs in situations where must-gather
or automated collection methods do not work.
If you do not have SSH access to your node, you can access the systems journal to investigate what is happening on your host.
Prerequisites
- Your OpenShift Container Platform installation must be complete.
- Your API service is still functional.
- You have system administrator privileges.
Procedure
Access
journald
unit logs under/var/log
by running:$ oc adm node-logs --role=master -u kubelet
Access host file paths under
/var/log
by running:$ oc adm node-logs --role=master --path=openshift-apiserver
25.5. Getting debug information from the installation program
You can use any of the following actions to get debug information from the installation program.
Look at debug messages from a past installation in the hidden
.openshift_install.log
file. For example, enter:$ cat ~/<installation_directory>/.openshift_install.log 1
- 1
- For
installation_directory
, specify the same directory you specified when you ran./openshift-install create cluster
.
Change to the directory that contains the installation program and re-run it with
--log-level=debug
:$ ./openshift-install create cluster --dir <installation_directory> --log-level debug 1
- 1
- For
installation_directory
, specify the same directory you specified when you ran./openshift-install create cluster
.
25.6. Reinstalling the OpenShift Container Platform cluster
If you are unable to debug and resolve issues in the failed OpenShift Container Platform installation, consider installing a new OpenShift Container Platform cluster. Before starting the installation process again, you must complete thorough cleanup. For a user-provisioned infrastructure (UPI) installation, you must manually destroy the cluster and delete all associated resources. The following procedure is for an installer-provisioned infrastructure (IPI) installation.
Procedure
Destroy the cluster and remove all the resources associated with the cluster, including the hidden installer state files in the installation directory:
$ ./openshift-install destroy cluster --dir <installation_directory> 1
- 1
installation_directory
is the directory you specified when you ran./openshift-install create cluster
. This directory contains the OpenShift Container Platform definition files that the installation program creates.
Before reinstalling the cluster, delete the installation directory:
$ rm -rf <installation_directory>
- Follow the procedure for installing a new OpenShift Container Platform cluster.
Additional resources