Getting Started Guide

Procedure

1. Download the latest release of Red Hat OpenShift Local for your platform.
2. On Microsoft Windows, extract the contents of the archive.

3. On macOS or Microsoft Windows, run the guided installer and follow the instructions.

   Note

   On Microsoft Windows, you must install Red Hat OpenShift Local to your local C:\ drive. You cannot run Red Hat OpenShift Local from a network drive.

   On Red Hat Enterprise Linux, assuming the archive is in the ~/Downloads directory, follow these steps:

   1. Extract the contents of the archive:

      $ cd ~/Downloads
      $ tar xvf crc-linux-amd64.tar.xz

   2. Create the ~/bin directory if it does not exist and copy the crc executable to it:

      $ mkdir -p ~/bin
      $ cp ~/Downloads/crc-linux-*-amd64/crc ~/bin

   3. Add the ~/bin directory to your $PATH:

      $ export PATH=$PATH:$HOME/bin
      $ echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc

Procedure

1. Download the latest release of Red Hat OpenShift Local.

2. Delete the existing 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.

3. Replace the earlier crc executable with the executable of the latest release. Verify that the new crc executable is in use by checking its version:

   $ crc version

4. Set up the new Red Hat OpenShift Local release:

   $ crc setup

5. Start the new Red Hat OpenShift Local instance:

   $ crc start

Procedure

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

   $ crc setup

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.

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. Clone an example Node.js application:

   $ git clone https://github.com/openshift/nodejs-ex
   $ cd nodejs-ex

5. Add a nodejs component to the application:

   $ odo create nodejs

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

   $ odo url create --port 8080

7. Push the changes:

   $ odo push

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

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

   $ odo url list

9. View the deployed application using the generated URL.

Procedure

1. Define a proxy using the http_proxy and https_proxy environment variables or using the crc config set command as follows:

   $ crc config set http-proxy http://proxy.example.com:<port>
   $ crc config set https-proxy http://proxy.example.com:<port>
   $ crc config set no-proxy <comma-separated-no-proxy-entries>

2. If the proxy uses a custom CA certificate file, set it as follows:

   $ crc config set proxy-ca-file <path-to-custom-ca-file>

Procedure

1. Start the cluster:

   $ crc start

   Ensure that the cluster remains running during this procedure.

2. Install the haproxy package and other utilities:

   $ sudo dnf install haproxy /usr/sbin/semanage

3. Modify the firewall to allow communication with the cluster:

   $ sudo systemctl enable --now firewalld
   $ sudo firewall-cmd --add-service=http --permanent
   $ sudo firewall-cmd --add-service=https --permanent
   $ sudo firewall-cmd --add-service=kube-apiserver --permanent
   $ sudo firewall-cmd --reload

4. For SELinux, allow HAProxy to listen on TCP port 6443 to serve kube-apiserver on this port:

   $ sudo semanage port -a -t http_port_t -p tcp 6443

5. Create a backup of the default haproxy configuration:

   $ sudo cp /etc/haproxy/haproxy.cfg{,.bak}

6. Configure haproxy for use with the cluster:

   $ export CRC_IP=$(crc ip)
   $ sudo tee /etc/haproxy/haproxy.cfg &>/dev/null <<EOF
   global
       log /dev/log local0
   
   defaults
       balance roundrobin
       log global
       maxconn 100
       mode tcp
       timeout connect 5s
       timeout client 500s
       timeout server 500s
   
   listen apps
       bind 0.0.0.0:80
       server crcvm $CRC_IP:80 check
   
   listen apps_ssl
       bind 0.0.0.0:443
       server crcvm $CRC_IP:443 check
   
   listen api
       bind 0.0.0.0:6443
       server crcvm $CRC_IP:6443 check
   EOF

7. Start the haproxy service:

   $ sudo systemctl start haproxy

Procedure

1. Install the dnsmasq package:

   $ sudo dnf install dnsmasq

2. Enable the use of dnsmasq for DNS resolution in NetworkManager:

   $ sudo tee /etc/NetworkManager/conf.d/use-dnsmasq.conf &>/dev/null <<EOF
   [main]
   dns=dnsmasq
   EOF

3. Add DNS entries for Red Hat OpenShift Local to the dnsmasq configuration:

   $ sudo tee /etc/NetworkManager/dnsmasq.d/external-crc.conf &>/dev/null <<EOF
   address=/apps-crc.testing/SERVER_IP_ADDRESS
   address=/api.crc.testing/SERVER_IP_ADDRESS
   EOF

   Note

   Comment out any existing entries in /etc/NetworkManager/dnsmasq.d/crc.conf. These entries are created by running a local instance of Red Hat OpenShift Local and will conflict with the entries for the remote cluster.

4. Reload the NetworkManager service:

   $ sudo systemctl reload NetworkManager

5. Log in to the remote cluster as the developer user with oc:

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

   The remote OpenShift Container Platform web console is available at https://console-openshift-console.apps-crc.testing.

Procedure

1. Set the enable-cluster-monitoring configurable property to true:

   $ crc config set enable-cluster-monitoring true

2. Start the instance:

   $ crc start

   Warning

   Cluster monitoring cannot be disabled. To remove monitoring, set the enable-cluster-monitoring configurable property to false and delete the existing Red Hat OpenShift Local instance.

Procedure

1. List unmanaged Operators and note the numeric index for the desired Operator:

   • On Linux or macOS:

     $ oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | nl -v 0

   • On Microsoft Windows using PowerShell:

     PS> oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | % {$nl++;"`t$($nl-1) `t $_"};$nl=0

2. Start the desired Operator using the identified numeric index:

   $ oc patch clusterversion/version --type='json' -p '[{"op":"remove", "path":"/spec/overrides/<unmanaged-operator-index>"}]'
   clusterversion.config.openshift.io/version patched

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.

1. Download the latest Red Hat OpenShift Local 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 Red Hat OpenShift Local 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

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 Red Hat OpenShift Local instance. Save any desired information stored in the instance before running this command.

1. Stop the Red Hat OpenShift Local instance:

   $ crc stop

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

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

   $ crc cleanup

   Note

   The crc cleanup command removes an existing Red Hat OpenShift Local instance and reverts changes to DNS entries created by the crc setup command.

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

   $ crc setup

5. Start the Red Hat OpenShift Local instance:

   $ crc start

   Note

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

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.