Chapter 7. 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. Report such issues to the relevant project. For example, OpenShift tracks issues on GitHub.

7.1. Getting shell access to the OpenShift cluster

To access the cluster for troubleshooting or debugging purposes, follow this procedure.

Note

Direct access to the OpenShift cluster is not needed for regular use and is strongly discouraged.

Prerequisites

Procedure

  1. Run the oc get nodes command to identify the desired node. 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 printed in the previous step.

7.2. Troubleshooting expired certificates

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. The crc start command triggers an automatic certificate renewal process when needed. Certificate renewal can add up to five minutes to the start time of the cluster.

To avoid this additional startup time, or in case of failures in the certificate renewal process, use the following procedure:

Procedure

To resolve expired certificate errors that cannot be automatically renewed:

  1. Download the latest CodeReady Containers release and place the crc executable in your $PATH.
  2. Remove the cluster with certificate errors using the crc delete command:

    $ crc delete
    Warning

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

  3. Set up the new release:

    $ crc setup
  4. Start the new instance:

    $ crc start

7.3. Troubleshooting bundle version mismatch

Created CodeReady Containers instances 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

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

    $ crc delete
    Warning

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

7.4. Troubleshooting unknown issues

Resolve most issues by restarting CodeReady Containers with a clean state. This involves stopping the instance, deleting it, reverting changes made by the crc setup command, reapplying those changes, and restarting the instance.

Prerequisites

  • You set up the host machine with the crc setup command. For more information, see Setting up CodeReady Containers.
  • You started CodeReady Containers with the crc start command. For more information, see Starting the instance.
  • 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:

  1. Stop the CodeReady Containers instance:

    $ crc stop
  2. Delete the CodeReady Containers instance:

    $ crc delete
    Warning

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

  3. Clean up remaining changes from the crc setup command:

    $ crc cleanup
    Note

    The crc cleanup command removes an existing CodeReady Containers instance and reverts changes to DNS entries created by the crc setup command. On macOS, the crc cleanup command also removes the system tray.

  4. Set up your host machine to reapply the changes:

    $ crc setup
  5. Start the CodeReady Containers instance:

    $ 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 is not 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 has detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.