Chapter 3. Using CodeReady Containers

3.1. 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

  • On Linux or macOS, ensure that your user account has permission to use the sudo command. On Microsoft Windows, ensure that your user account can elevate to Administrator privileges.
Note
  • Do not run the crc executable as root (or Administrator). Always run the crc executable with your user account.
  • If you are setting up a new version, capture any changes made to the virtual machine before setting up a new CodeReady Containers release.

Procedure

  1. Set up your host machine for CodeReady Containers:

    $ crc setup

Consent for telemetry data collection

The crc setup command prompts you for optional, anonymous usage data collection to assist with development. No personally identifiable information is collected.

  • To manually enable telemetry, run the following command:

    $ crc config set consent-telemetry yes
  • To manually disable telemetry, run the following command:

    $ crc config set consent-telemetry no

For more information about collected data, see the Red Hat Telemetry data collection notice.

3.2. Starting the virtual machine

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

Prerequisites

  • To avoid networking-related issues, ensure that you are not connected to a VPN and that your network connection is reliable.
  • You set up the host machine through the crc setup command. For more information, see Setting up CodeReady Containers.
  • On Microsoft Windows, ensure that your user account can elevate to Administrator privileges.
  • You have a valid OpenShift user pull secret. Copy or download the pull secret from the Pull Secret section of the Install on Laptop: Red Hat CodeReady Containers page on cloud.redhat.com.

    Note

    Accessing the user pull secret requires a Red Hat account.

Procedure

  1. Start the CodeReady Containers virtual machine:

    $ crc start
  2. 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.
  • If you see errors during crc start, check the Troubleshooting CodeReady Containers section for potential solutions.

Additional resources

3.3. Accessing the OpenShift cluster

Access the OpenShift cluster running in the CodeReady Containers virtual machine through the OpenShift web console or client executable (oc).

3.3.1. Accessing the OpenShift web console

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 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 and kubeadmin users by running crc console --credentials.
    • You can initially access the cluster through either the kubeadmin or developer user. Use the developer user for creating projects or OpenShift applications and for application deployment. Only use the kubeadmin user for administrative tasks such as creating new users, setting roles, and so on.

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

Additional resources

3.3.2. Accessing the OpenShift cluster with oc

Prerequisites

Procedure

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

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

    $ crc oc-env
  2. Run the printed command.
  3. Log in as the developer user:

    $ oc login -u developer https://api.crc.testing:6443
    Note

    The crc start command prints the password for the developer user. 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, log in as the kubeadmin user and run the following command:

    $ oc config use-context crc-admin
    $ oc whoami
    kubeadmin
    $ oc get co
    Note
    • CodeReady Containers disables the machine-config and monitoring Operators by default.

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

Additional resources

3.3.3. Accessing the internal OpenShift registry

The OpenShift cluster running in the CodeReady Containers virtual machine includes an internal container image registry by default. This internal container image registry can be used as a publication target for locally developed container images. To access the internal OpenShift registry, follow these steps.

Prerequisites

Procedure

  1. Check which user is logged in to the cluster:

    $ oc whoami
    Note

    For demonstration purposes, the current user is assumed to be kubeadmin.

  2. Log in to the registry as that user with its token:

    $ podman login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.apps-crc.testing --tls-verify=false
  3. Create a new project:

    $ oc new-project demo
  4. Pull an example container image:

    $ podman pull quay.io/libpod/alpine
  5. Tag the image, including namespace details:

    $ podman tag alpine:latest default-route-openshift-image-registry.apps-crc.testing/demo/alpine:latest
  6. Push the container image to the internal registry:

    $ podman push default-route-openshift-image-registry.apps-crc.testing/demo/alpine:latest --tls-verify=false
  7. Get imagestreams and verify that the pushed image is listed:

    $ oc get is
  8. Enable image lookup in the imagestream:

    $ oc set image-lookup alpine

    This setting allows the imagestream to be the source of images without having to provide the full URL to the internal registry.

  9. Create a pod using the recently pushed image:

    $ oc run demo --image=alpine --command -- sleep 600s

3.4. Deploying a sample application with odo

You can use odo to create OpenShift projects and applications from the command line. This procedure deploys a sample application to the OpenShift cluster running in the CodeReady Containers virtual machine.

Prerequisites

Procedure

To deploy a sample application through odo, follow these steps:

  1. Log in to the running CodeReady Containers OpenShift cluster as the developer user:

    $ odo login -u developer -p developer
  2. Create a project for your application:

    $ odo project create sample-app
  3. Create a directory for your components:

    $ mkdir sample-app
    $ cd sample-app
  4. Create a component from a sample application on GitHub:

    $ odo create nodejs --s2i --git https://github.com/openshift/nodejs-ex
    Note

    Creating a component from a remote Git repository will rebuild the application each time you run the odo push command. To create a component from a local Git repository, see Creating a single-component application with odo in the odo documentation.

  5. Create a URL and add an entry to the local configuration file:

    $ odo url create --port 8080
  6. Push the changes:

    $ odo push

    Your component is now deployed to the cluster with an accessible URL.

  7. List the URLs and check the desired URL for the component:

    $ odo url list
  8. View the deployed application using the generated URL.

Additional resources

3.5. 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

3.6. Deleting the virtual machine

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

Procedure

  • Delete the CodeReady Containers virtual machine:

    $ crc delete
    Warning

    The crc delete command 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.