Chapter 1. Getting started with Red Hat CodeReady Containers

1.1. Understanding CodeReady Containers

Red Hat CodeReady Containers brings a minimal OpenShift 4 cluster to your local computer. This cluster provides a minimal environment for development and testing purposes. It’s mainly targetted at running on developers' desktops. For other use cases, such as headless, multi-developer/team-based setups, …​, use of the full-fledged OpenShift installer is recommended.

You can refer to the OpenShift documentation for a more in-depth introduction to OpenShift.

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 and monitoring Operators are disabled by default.
  • These disabled Operators will cause the corresponding parts of the web console to be non functional.
  • For the same reason, there is currently no upgrade path to newer OpenShift versions.
  • Due to technical limitations, the CodeReady Containers cluster is ephemeral and will need to be recreated from scratch once a month using a newer release.
  • The OpenShift instance is running in a virtual machine, which could cause some other differences, in particular in relation with external networking.

1.3. Minimum system requirements

CodeReady Containers requires the following minimum hardware and operating system requirements.

1.3.1. Hardware requirements

CodeReady Containers requires the following system resources:

  • 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. Depending on the workload, more resources need to be assigned.

1.3.2. Operating system requirements

CodeReady Containers requires the following minimum version of a supported operating system:

1.3.2.1. Microsoft Windows

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

1.3.2.2. macOS

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

1.3.2.3. Linux

  • On Linux, CodeReady Containers is only supported on Red Hat Enterprise Linux/CentOS 7.5 or newer (including 8.x versions) and on the latest two stable Fedora releases.
  • When using Red Hat Enterprise Linux, the machine running CodeReady Containers must be registered with Red Hat Customer Portal.
  • Ubuntu 18.04 LTS or newer and Debian 10 or newer are not officially supported and may require manual set up of the host machine.
  • See Section 1.4, “Required software packages” to install the required packages for your Linux distribution.

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.1. Package installation commands by distribution

Linux DistributionInstallation 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. Installing CodeReady Containers

Prerequisites

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.

1.6. 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.7. 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
  • 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.8. Accessing the OpenShift cluster

Prerequisites

Procedure

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

    1. Run crc console. This will open your web browser and direct it to the web console.

    2. Log in to the OpenShift web console as the developer user with the password printed in the output of the crc start command.

      Note

      You can also view the password for the developer user by running crc console --credentials.

      Note

      The cluster can initially be accessed through either the kubeadmin or developer user. For creating projects or OpenShift applications, and for application deployment, the developer user should be used. The kubeadmin user should only be used for administrative tasks such as creating new users, setting roles, and so on.

    3. The OpenShift documentation covers the creation of projects and applications.

      See Chapter 3, 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. Log in by running the oc login -u developer https://api.crc.testing:6443 command.

      Note

      The password for the developer user was printed in the output of the crc start command. You can also view it by running the crc console --credentials command.

    4. 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   True        False         False     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 cluster operator is expected to report False availability. The monitoring cluster operator is expected to report Unknown availability.

    5. The OpenShift documentation covers the creation of projects and applications. OpenShift Do (odo) can also be used to create OpenShift projects and applications from the command line.

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

1.9. 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.10. 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