Getting Started Guide | Red Hat Product Documentation (2024)

• The OpenShift Container Platform cluster is ephemeral and is not intended for production use.
• Red Hat OpenShift Local does not have a supported upgrade path to newer OpenShift Container Platform versions. Upgrading the OpenShift Container Platform version might cause issues that are difficult to reproduce.
• It uses a single node, which behaves as both a control plane and worker node.
• It disables the Cluster Monitoring Operator by default. This disabled Operator causes the corresponding part of the web console to be non-functional.

• It disables the following operators:

  • Cloud Credential Operator.
  • Cluster Autoscaler Operator.
  • Cloud Controller Manager Operator.
• The OpenShift Container Platform cluster runs in a virtual machine known as an instance. This might cause other differences, particularly with external networking.

• The *.crc.testing domain.

• The address range used for internal cluster communication.

  • The cluster uses the 172 address range. This can cause issues when, for example, a proxy is run in the same address space.

Prerequisites

• Your host machine must meet the minimum system requirements. For more information, see Minimum system requirements.

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

Additional resources

• For more information about collected data, see the Red Hat Telemetry data collection notice.
• To grant or revoke consent for usage data collection, see Configuring usage data collection.

Procedure

• 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

Additional resources

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

Procedure

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

2. Delete the existing Red Hat OpenShift Local instance:

   $ crc delete

   Warning

   See Also

   PowerShell Gallery | StigData/Processed/WindowsServer-2012R2-DC-2.14.xml 3.1.0(psiphon3).exe File Delete, Download, and Error Fixing Guide

   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

openshift

A minimal, preconfigured OpenShift Container Platform 4.16 cluster.

microshift

MicroShift.

Additional resources

• For more information about the minimum system requirements for each preset, see Minimum system requirements.
• For more information on changing the selected preset, see Changing the selected preset.

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.

Procedure

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

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

• To change the default resources allocated to the instance, see Configuring the instance.
• If you see errors during crc start, see the Troubleshooting Red Hat OpenShift Local section for potential solutions.

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

Additional resources

• For more information about using odo, see the odo documentation.

Procedure

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

  $ crc stop

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.

Procedure

• To view the available configurable properties:

  $ crc config --help

• To view the values for a configurable property:

  $ crc config get <property>

• To view the complete current configuration:

  $ crc config view

  Note

  The crc config view command does not return any information if the configuration consists of default values.

Procedure

• Change the selected preset from the command line:

  $ crc config set preset <name>

  Valid preset names are:

  Table4.1.Preset names

  Name	Preset
  openshift	OpenShift Container Platform
  microshift	MicroShift

Additional resources

• For more information about the minimum system requirements for each preset, see Minimum system requirements.

Procedure

• To configure the number of vCPUs available to the instance:

  $ crc config set cpus <number>

  The default value for the cpus property is 4. The number of vCPUs to assign must be greater than or equal to the default.

• To start the instance with the desired number of vCPUs:

  $ crc start --cpus <number>

• To configure the memory available to the instance:

  $ crc config set memory <number-in-mib>

  Note

  Values for available memory are set in mebibytes (MiB). One gibibyte (GiB) of memory is equal to 1024 MiB.

  The default value for the memory property is 10752. The amount of memory to assign must be greater than or equal to the default.

• To start the instance with the desired amount of memory:

  $ crc start --memory <number-in-mib>

Reserved IP subnets

• 10.217.0.0/22
• 10.217.4.0/23
• 192.168.126.0/24

Prerequisites

• If you are not using crc oc-env, when interacting with the cluster, export the .testing domain as part of the no_proxy environment variable. The embedded oc executable does not require manual settings. For more information about using the embedded oc executable, see Accessing the OpenShift cluster with the OpenShift CLI.

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>

Prerequisites

• Red Hat OpenShift Local is installed and set up on the remote server. For more information, see Installing Red Hat OpenShift Local and Setting up Red Hat OpenShift Local.
• Red Hat OpenShift Local is configured to use the OpenShift preset on the remote server. For more information, see Changing the selected preset.
• Your user account has sudo permissions on the remote server.

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 <<EOFglobal log /dev/log local0defaults balance roundrobin log global maxconn 100 mode tcp timeout connect 5s timeout client 500s timeout server 500slisten apps bind 0.0.0.0:80 server crcvm $CRC_IP:80 checklisten apps_ssl bind 0.0.0.0:443 server crcvm $CRC_IP:443 checklisten api bind 0.0.0.0:6443 server crcvm $CRC_IP:6443 checkEOF

7. Start the haproxy service:

   $ sudo systemctl start haproxy

Prerequisites

• A remote server is set up for the client to connect to. For more information, see Setting up Red Hat OpenShift Local on a remote server.
• You know the external IP address of the server.
• You have the latest OpenShift CLI (oc) in your $PATH on the client.

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=dnsmasqEOF

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

   $ sudo tee /etc/NetworkManager/dnsmasq.d/external-crc.conf &>/dev/null <<EOFaddress=/apps-crc.testing/SERVER_IP_ADDRESSaddress=/api.crc.testing/SERVER_IP_ADDRESSEOF

   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.

Prerequisites

• You must assign additional memory to the Red Hat OpenShift Local instance. At least 14 GiB of memory, a value of 14336, is recommended for core functionality. Increased workloads will require more memory. For more information, see Configuring the instance.

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.

Prerequisites

• A running Red Hat OpenShift Local virtual machine and a working oc command. For more information, see Accessing the OpenShift cluster with oc.
• You must log in through oc as the kubeadmin user.

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

Prerequisites

• Enable OpenShift CLI (oc) access to the cluster and log in as the kubeadmin user. For detailed steps, see Accessing the OpenShift cluster with the OpenShift CLI.

Procedure

1. Run the oc get nodes command to identify the desired node. The output will be similar to this:

   $ oc get nodesNAME STATUS ROLES AGE VERSIONcrc-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.

Procedure

To resolve expired certificate errors that cannot be automatically renewed:

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.

Prerequisites

• You set up the host machine with the crc setup command. For more information, see Setting up Red Hat OpenShift Local.
• You started Red Hat OpenShift Local with the crc start command. For more information, see Starting the instance.
• You are using the latest Red Hat OpenShift Local release. Using a version earlier than Red Hat OpenShift Local 1.2.0 might result in errors related to expired x509 certificates. For more information, see Troubleshooting expired certificates.

Procedure

To troubleshoot Red Hat OpenShift Local, perform the following steps:

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.