1. Getting started with Red Hat CodeReady Containers

1.1. Understanding CodeReady Containers

Red Hat CodeReady Containers brings a minimal OpenShift 4.0 or newer cluster to your local computer.

CodeReady Containers includes the crc command-line interface (CLI) to interact with the CodeReady Containers virtual machine running the OpenShift cluster.

1.2. Differences with a production OpenShift install

Red Hat CodeReady Containers is a regular OpenShift installation with the following notable differences:

  • It uses a single node which behaves both as a master and as a worker node.

  • The machine-config, marketplace and monitoring Operators are disabled by default.

  • These disabled Operators will cause the corresponding parts of the web console to be non functional.

  • The OpenShift instance is running in a virtual machine, which could cause some other differences, in particular in relation with external networking.

1.3. Installing CodeReady Containers

Prerequisites
  • CodeReady Containers requires the following system resources in order to run OpenShift:

    • 4 virtual CPUs (vCPUs)

    • 8 GB of memory

    • 35 GB of storage space

Note

These requirements must be met in order to run OpenShift in the CodeReady Containers virtual machine. Other applications running on top of OpenShift may require additional resources to run.

  • On Microsoft Windows, CodeReady Containers requires the Windows 10 Fall Creators Update (version 1709). CodeReady Containers does not work on earlier versions of Microsoft Windows.

  • On macOS, CodeReady Containers requires macOS 10.12 Sierra or newer. CodeReady Containers does not work on earlier versions of macOS.

  • On Linux, CodeReady Containers requires installation of the following software packages:

    • NetworkManager

Note

See Required software packages to install the required packages for your Linux distribution.

Procedure
  1. Download the latest release of CodeReady Containers for your platform and extract the contents of the archive to a location in your PATH.

  2. On Debian or Ubuntu, perform the following steps:

    1. Add your user to the libvirtd group:

      $ sudo usermod -aG libvirtd $(whoami)
    2. Update your current session to apply the group change:

      $ newgrp libvirtd
    3. Disable the libvirt group check performed by the crc start command:

      $ crc config set skip-check-user-in-libvirt-group true

1.4. Required software packages

CodeReady Containers requires the libvirt and NetworkManager packages. Consult the following table to determine the command used to install these packages for your Linux distribution.

Table 1. Package installation commands by distribution
Linux Distribution Installation command

Fedora

sudo dnf install NetworkManager

Red Hat Enterprise Linux/CentOS

su -c 'yum install NetworkManager'

Debian/Ubuntu

sudo apt install qemu-kvm libvirt-daemon libvirt-daemon-system network-manager

1.5. Setting up CodeReady Containers

The crc setup command performs operations to set up the environment of your host machine for the CodeReady Containers virtual machine.

This procedure will create the ~/.crc directory if it does not already exist.

Prerequisites
  • Your user account must have permission to use the sudo command.

Note

The crc binary should not be run as root (or Administrator). The crc binary should always be run with your user account.

Procedure
  1. Set up your host machine for CodeReady Containers:

    $ crc setup

1.6. Starting the virtual machine

The crc start command starts the CodeReady Containers virtual machine and OpenShift cluster.

Prerequisites
Procedure
  • Start the CodeReady Containers virtual machine:

    • For native hypervisors:

      $ crc start
    • For VirtualBox, a bundle file downloaded separately and the --vm-driver virtualbox and --bundle flags are required:

      $ crc start --vm-driver virtualbox --bundle path_to_system_bundle
  • When prompted, supply your user pull secret.

Note

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

1.7. Accessing the OpenShift cluster

Prerequisites
Procedure
  • To access the OpenShift web console, follow these steps:

    1. Open the OpenShift web console URL printed in the output of the crc start command:

      $ browser_command https://console-openshift-console.apps-crc.testing
    2. Log in to the OpenShift web console as the kubeadmin user with the password printed in the output of the crc start command.

      Note

      You can also view the password for the kubeadmin user in the ~/.crc/cache/crc_libvirt_v4.1.0.rc0/kubeadmin-password file.

      See Troubleshooting Red Hat CodeReady Containers if you cannot access the CodeReady Containers OpenShift cluster.

  • To access the OpenShift cluster via the oc command, follow these steps:

    1. Run the crc oc-env command to print the command needed to add the cached oc binary to your PATH:

      $ crc oc-env
    2. Run the printed command.

    3. You can now use oc to interact with your OpenShift cluster. For example, to verify that the OpenShift cluster operators are available using the oc get co command:

      $ oc get co
      NAME                                 VERSION      AVAILABLE   PROGRESSING   FAILING   SINCE
      authentication                       4.1.0-rc.0   True        False         False     6d6h
      cloud-credential                     4.1.0-rc.0   True        False         False     6d6h
      cluster-autoscaler                   4.1.0-rc.0   True        False         False     6d6h
      console                              4.1.0-rc.0   True        False         False     6d6h
      dns                                  4.1.0-rc.0   True        False         False     89m
      image-registry                       4.1.0-rc.0   True        False         False     6d6h
      ingress                              4.1.0-rc.0   True        False         False     89m
      kube-apiserver                       4.1.0-rc.0   True        False                   6d6h
      kube-controller-manager              4.1.0-rc.0   True        False                   6d6h
      kube-scheduler                       4.1.0-rc.0   True        False                   6d6h
      machine-api                          4.1.0-rc.0   True        False         False     6d6h
      machine-config                       4.1.0-rc.0   False       False         True      6d6h
      marketplace                          4.1.0-rc.0   False       False         True      6d6h
      monitoring                                        Unknown     True          Unknown   6d6h
      network                              4.1.0-rc.0   True        False                   6d6h
      node-tuning                          4.1.0-rc.0   True        False         False     89m
      openshift-apiserver                  4.1.0-rc.0   True        False                   6d6h
      openshift-controller-manager         4.1.0-rc.0   True        False                   5d11h
      openshift-samples                    4.1.0-rc.0   True        False         False     6d6h
      operator-lifecycle-manager           4.1.0-rc.0   True        False         False     6d6h
      operator-lifecycle-manager-catalog   4.1.0-rc.0   True        False         False     6d6h
      service-ca                           4.1.0-rc.0   True        False         False     6d6h
      service-catalog-apiserver            4.1.0-rc.0   True        False         False     88m
      service-catalog-controller-manager   4.1.0-rc.0   True        False         False     88m
      storage                              4.1.0-rc.0   True        False         False     6d6h
      Note

      The machine-config and marketplace cluster operators are expected to report False availability. The monitoring cluster operator is expected to report Unknown availability.

      See Troubleshooting Red Hat CodeReady Containers if you cannot access the CodeReady Containers OpenShift cluster.

1.8. Stopping the virtual machine

The crc stop command stops the running CodeReady Containers virtual machine and OpenShift cluster. The stopping process will take a few minutes while the cluster shuts down.

Procedure
  • Stop the CodeReady Containers virtual machine and OpenShift cluster:

    $ crc stop

1.9. Deleting the virtual machine

The crc delete command deletes an existing CodeReady Containers virtual machine.

Warning

All the changes which have been made to the OpenShift cluster will be lost.

Procedure
  • Delete the CodeReady Containers virtual machine:

    $ crc delete

2. Common tasks

2.1. Starting Monitoring, Alerting, and Telemetry

In order to make sure CodeReady Containers can run on a typical laptop, some resource–heavy services get disabled by default. One of these is Prometheus and all the related monitoring, alerting, and telemetry functionality, with the latter being responsible for your cluster being listed in the Red Hat OpenShift Cluster Manager.

Prerequisites
Procedure
  1. Start monitoring, alerting, and telemetry services:

    $ oc scale --replicas=1 statefulset --all -n openshift-monitoring; oc scale --replicas=1 deployment --all -n openshift-monitoring

3. Troubleshooting Red Hat CodeReady Containers

3.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
  • The host machine has been set up using the crc setup command. For more information, see Setting up CodeReady Containers.

  • The virtual machine has been started using the crc start command. For more information, see Starting the virtual machine.

  • You are using the latest CodeReady Containers release The generated certificates for the embedded system image bundle expire after 30 days. Using an older system image bundle may result in errors related to expired x509 certificates.

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.

3.2. DNS configuration details

This section describes how CodeReady Containers configures networking. This can be useful for troubleshooting, or in case you are using a non-standard DNS setup, and want to adjust it for CodeReady Containers needs. The crc ip command can be used to obtain the VM IP address as needed. This address can change each time the VM is restarted.

3.2.1. Linux

  • CodeReady Containers expects NetworkManager to be used to manage networking.

  • NetworkManager is set up to use dnsmasq through the /etc/NetworkManager/conf.d/crc-nm-dnsmasq.conf configuration file.

  • The configuration file for this dnsmasq instance is /etc/NetworkManager/dnsmasq.d/crc.conf:

server=/crc.testing/192.168.130.11
server=/apps-crc.testing/192.168.130.11
  • NetworkManager dnsmasq instance forwards requests for the crc.testing and apps-crc.testing domains to the 192.168.130.11 DNS server which is a dnsmasq instance running inside the virtual machine.

3.2.2. macOS

  • CodeReady Containers creates a /etc/resolver/testing file which instructs macOS to forward all DNS requests for the testing domain to the CodeReady Containers virtual machine.

  • CodeReady Containers also adds an api.crc.testing entry to /etc/hosts pointing at the VM IP address. This is needed by the oc binary, see OpenShift issue #23266.