Chapter 7. Troubleshooting Red Hat CodeReady Containers
The goal of Red Hat CodeReady Containers is to deliver an OpenShift environment for development and testing purposes. Issues occurring during installation or usage of specific OpenShift applications are outside of the scope of CodeReady Containers. Report such issues to the relevant project. For example, OpenShift tracks issues on GitHub.
7.1. Getting shell access to the OpenShift cluster
Direct access to the OpenShift cluster is not needed for regular use and is strongly discouraged. To access the cluster for troubleshooting or debugging purposes, follow this procedure.
Prerequisites
-
Enable
ocaccess to the cluster and log in as thekubeadminuser. For detailed steps, see Accessing the OpenShift cluster withoc.
Procedure
Run
oc get nodes. The output will be similar to this:$ oc get nodes NAME STATUS ROLES AGE VERSION crc-shdl4-master-0 Ready master,worker 7d7h v1.14.6+7e13ab9a7
-
Run
oc debug nodes/<node>where<node>is the name of the node printed in the previous step.
7.2. Troubleshooting expired certificates
As of the CodeReady Containers 1.10.0 release, the certificate renewal process is not working as intended. Follow this procedure to avoid potential errors due to certificate expiration.
The system bundle in each released crc executable expires 30 days after the release. This expiration is due to certificates embedded in the OpenShift cluster. As a result, using an older crc executable or system bundle can result in an expired certificates error.
Starting from CodeReady Containers 1.2.0, the embedded certificates can be automatically renewed by crc. The crc start command triggers the certificate renewal process when needed. Certificate renewal can add up to five minutes to the start time of the cluster.
Procedure
To resolve expired certificate errors that cannot be automatically renewed:
-
Download the latest CodeReady Containers release and place the
crcexecutable in your$PATH. Remove the cluster with certificate errors using the
crc deletecommand:$ crc delete
WarningThe
crc deletecommand results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.Set up the new release:
$ crc setup
Start the new virtual machine:
$ crc start
7.3. Troubleshooting bundle version mismatch
Created CodeReady Containers virtual machines contain bundle information and instance data. Bundle information and instance data is not updated when setting up a new CodeReady Containers release. This information is not updated due to customization in the earlier instance data. This will lead to errors when running the crc start command:
$ crc start ... FATA Bundle 'crc_hyperkit_4.2.8.crcbundle' was requested, but the existing VM is using 'crc_hyperkit_4.2.2.crcbundle'
Procedure
Issue the
crc deletecommand before attempting to start the instance:$ crc delete
WarningThe
crc deletecommand results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.
7.4. Troubleshooting unknown issues
Resolve most issues by restarting CodeReady Containers with a clean state. This involves stopping the virtual machine, deleting it, reverting changes made by the crc setup command, reapplying those changes, and restarting the virtual machine.
Prerequisites
-
You set up the host machine through the
crc setupcommand. For more information, see Setting up CodeReady Containers. -
You started CodeReady Containers through the
crc startcommand. For more information, see Starting the virtual machine. - You are using the latest CodeReady Containers release. Using a version earlier than CodeReady Containers 1.2.0 may result in errors related to expired x509 certificates. For more information, see Troubleshooting expired certificates.
Procedure
To troubleshoot CodeReady Containers, perform the following steps:
Stop the CodeReady Containers virtual machine:
$ crc stop
Delete the CodeReady Containers virtual machine:
$ crc delete
WarningThe
crc deletecommand results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.Clean up remaining changes from the
crc setupcommand:$ crc cleanup
NoteThe
crc cleanupcommand removes an existing CodeReady Containers virtual machine and reverts changes to DNS entries created by thecrc setupcommand. On macOS, thecrc cleanupcommand also removes the system tray.Set up your host machine to reapply the changes:
$ crc setup
Start the CodeReady Containers virtual machine:
$ crc start
NoteThe cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request.
If your issue is not resolved by this procedure, perform the following steps:
- Search open issues for the issue that you are encountering.
-
If no existing issue addresses the encountered issue, create an issue and attach the
~/.crc/crc.logfile to the created issue. The~/.crc/crc.logfile has detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing.
