Chapter 6. Troubleshooting Red Hat CodeReady Containers

Note

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 and should be reported to the relevant project. For example, OpenShift issues are tracked on GitHub.

6.1. Basic troubleshooting

The majority of issues can be resolved by stopping a running CodeReady Containers virtual machine, deleting the virtual machine, and starting a new instance of the virtual machine.

Prerequisites

Procedure

To troubleshoot CodeReady Containers, perform the following steps:

  1. Stop the CodeReady Containers virtual machine: 

    $ crc stop

  2. Delete the CodeReady Containers virtual machine: 

    $ crc delete

  3. Start the CodeReady Containers virtual machine: 

    $ crc start
    Note

    The cluster takes a minimum of four minutes to start the necessary containers and operators before serving a request.

If your issue has not been resolved by this procedure, perform the following steps:

  1. Search open issues for the issue that you are encountering.
  2. If no existing issue addresses the encountered issue, create an issue and attach the ~/.crc/crc.log file to the created issue. The ~/.crc/crc.log file contains detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing.

6.2. Getting shell access to the OpenShift cluster

Direct access to the OpenShift cluster is not needed for regular use and is strongly discouraged. If direct access to the cluster is needed for troubleshooting or debugging purposes, follow this procedure.

Prerequisites

Procedure

  1. 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
  2. Run oc debug nodes/<node> where <node> is the name of the node which was printed in the previous step.

6.3. Troubleshooting expired certificates

Prior to Red Hat CodeReady Containers 1.2.0, the system bundle included in each released crc binary expired 30 days after the release due to certificates embedded in the OpenShift cluster. Using an older crc binary or system bundle will result in an expired certificates error.

Starting from CodeReady Containers 1.2.0, the embedded certificates can be automatically renewed by crc. The certificate renewal process is triggered when needed when crc start is run. When certificates need to be renewed, this can add up to five minutes to the start time of the cluster.

Procedure

With CodeReady Containers releases older than 1.2.0, to resolve expired certificate errors:

  1. Download the latest CodeReady Containers release and place the crc binary in your $PATH.

  2. Remove the cluster with certificate errors using the crc delete command: 

    $ crc delete
    Warning

    The crc delete command will result in the loss of data stored in the CodeReady Containers virtual machine. Save any desired instance information before running this command.

  3. Set up the new release: 

    $ crc setup

  4. Start the new cluster: 

    $ crc start

6.4. Troubleshooting bundle version mismatch

CodeReady Containers instances are created with bundle information and instance data. When a new CodeReady Containers release is set up, the bundle information and instance data is not updated due to customization in the previous 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

  1. Issue the crc delete command before attempting to start the instance: 

    $ crc delete
    Warning

    The crc delete command will result in the loss of data stored in the CodeReady Containers virtual machine. Save any desired instance information before running this command.