Chapter 3. Using Red Hat OpenShift Local

3.1. About presets

Red Hat OpenShift Local presets represent a managed container runtime and the lower bounds of system resources required by the instance to run it. Red Hat OpenShift Local offers presets for OpenShift Container Platform and the Podman container runtime.

On Microsoft Windows and macOS, the Red Hat OpenShift Local guided installer prompts you for your desired preset. On Linux, the OpenShift Container Platform preset is selected by default. You can change this selection using the crc config command before running the crc setup command. You can change your selected preset from the system tray on Microsoft Windows and macOS or from the command line on all supported operating systems. Only one preset can be active at a time.

Additional resources

3.2. Setting up Red Hat OpenShift Local

The crc setup command performs operations to set up the environment of your host machine for the Red Hat OpenShift Local instance.

The crc setup command creates the ~/.crc directory if it does not already exist.

Warning

If you are setting up a new version, capture any changes made to the instance before setting up a new Red Hat OpenShift Local release.

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 the root user or an administrator. Always run the crc executable with your user account.

Procedure

  1. (Optional) On Linux, the OpenShift Container Platform preset is selected by default. To select the the Podman container runtime preset: 

    $ crc config set preset podman

  2. Set up your host machine for Red Hat OpenShift Local: 

    $ crc setup

Additional resources

  • For more information about the available container runtime presets, see About presets.

3.3. Starting the instance

The crc start command starts the Red Hat OpenShift Local instance and configured container runtime.

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 using the crc setup command. For more information, see Setting up Red Hat OpenShift Local.
  • On Microsoft Windows, ensure that your user account can elevate to Administrator privileges.

  • For the OpenShift preset, ensure that you have a valid OpenShift user pull secret. Copy or download the pull secret from the Pull Secret section of the Red Hat OpenShift Local page on the Red Hat Hybrid Cloud Console.

    Note

    Accessing the user pull secret requires a Red Hat account.

Procedure

  1. Start the Red Hat OpenShift Local instance: 

    $ crc start

  2. For the OpenShift preset, supply your user pull secret when prompted.

    Note

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

Additional resources

3.4. Accessing the OpenShift cluster

Access the OpenShift Container Platform cluster running in the Red Hat OpenShift Local instance by using the OpenShift Container Platform web console or OpenShift CLI (oc).

3.4.1. Accessing the OpenShift web console

Access the OpenShift Container Platform web console by using your web browser.

Access the cluster by using either the kubeadmin or developer user. Use the developer user for creating projects or OpenShift applications and for application deployment. Use the kubeadmin user only for administrative tasks such as creating new users or setting roles.

Prerequisites

Procedure

  1. To access the OpenShift Container Platform web console with your default web browser, run the following command: 

    $ crc console

  2. Log in as the developer user with the password printed in the output of the crc start command. You can also view the password for the developer and kubeadmin users by running the following command: 

    $ crc console --credentials

See Troubleshooting Red Hat OpenShift Local if you cannot access the OpenShift Container Platform cluster managed by Red Hat OpenShift Local.

Additional resources

3.4.2. Accessing the OpenShift cluster with the OpenShift CLI

Access the OpenShift Container Platform cluster managed by Red Hat OpenShift Local by using the OpenShift CLI (oc).

Prerequisites

Procedure

  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 Container Platform cluster. For example, to verify that the OpenShift Container Platform 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

    Red Hat OpenShift Local disables the Cluster Monitoring Operator by default.

See Troubleshooting Red Hat OpenShift Local if you cannot access the OpenShift Container Platform cluster managed by Red Hat OpenShift Local.

Additional resources

3.4.3. Accessing the internal OpenShift registry

The OpenShift Container Platform cluster running in the Red Hat OpenShift Local instance 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 Container Platform 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.5. 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 Container Platform cluster running in the Red Hat OpenShift Local instance.

Prerequisites

  • You have installed odo. For more information, see Installing odo in the odo documentation.
  • Red Hat OpenShift Local is configured to use the OpenShift preset. For more information, see Changing the selected preset.
  • The Red Hat OpenShift Local instance is running. For more information, see Starting the instance.

Procedure

  1. Log in to the running OpenShift Container Platform cluster managed by Red Hat OpenShift Local 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.6. Stopping the instance

The crc stop command stops the running Red Hat OpenShift Local instance and container runtime. The stopping process takes a few minutes while the cluster shuts down.

Procedure

  • Stop the Red Hat OpenShift Local instance and container runtime: 

    $ crc stop

3.7. Deleting the instance

The crc delete command deletes an existing Red Hat OpenShift Local instance.

Procedure

  • Delete the Red Hat OpenShift Local instance: 

    $ crc delete
    Warning

    The crc delete command results in the loss of data stored in the Red Hat OpenShift Local instance. Save any desired information stored in the instance before running this command.