Deploy a Local Openshift Cluster

Demo Use Only

The instructions in this document are for testing and learning, and not intended for use in production.

Licensing

Openshift is a licensed product following the open source model where "upstream" versions are available under community licensing, but the official release supported by Red Hat requires a subscription in order to access the software for installation. This guide assumes the user has access to such a license. Red Hat provides a free Developer account that allows a participant to obtain a 60-day license of the supported Openshift product at no charge.

Video Demonstration

A video demonstration of the process outlined on this page is available here.

Some customers are using Openshift as their platform for running Ping containerized applications. If this is the case, access to an Openshift cluster is assumed. Even in those cases, there are times where a local implementation of Openshift for development and testing is convenient.

Platform

For this guide, the Apple MacBook Pro platform is used, and the release of the Red Hat Openshift Local offering is version 2.15.0

The Openshift Local offering is used in this guide. This page was derived from the documentation provided by Red Hat along with a workaround to a bug that has not yet been addressed regarding the Openshift client on the Apple Mac platform.

Prerequisites

• Entitlement for Openshift code. If you have registered for the Red Hat developer program, you can obtain your entitlement for the free trial from the portal after logging in.
• kubectl
• Openshift client (oc)
• ports 80, 443 and 6443 available on machine. If you have Docker Desktop installed, you must either disable Kubernetes or stop Docker in order for the installation to work.
• sudo privileges on your hosting environment

Configuration and Setup

1. Install the Red Hat Openshift Local binary for your platform. When you download the installer, also download the pull secret.

2. With the crc utility installed, configure settings. Provide as much RAM and CPU as you can, depending on your system. In this example, 16 GB of RAM, 7 vCPUs, and a disk size of 80GB are set. The consent-telemetry is optional, depending on whether you consent to usage data metrics being sent to Red Hat.

   # Version information
   crc version
   
   # Output
   CRC version: 2.15.0+72256c3c
   OpenShift version: 4.12.5
   Podman version: 4.3.1
   
   # Set configuration
   crc config set memory 16384
   crc config set cpus 7
   crc config set consent-telemetry no
   crc config set disk-size 80
   
   # Confirm
   crc config view
   
   - consent-telemetry                     : no
   - cpus                                  : 7
   - disk-size                             : 80
   - memory                                : 16384
   

3. Set up your local machine for running Red Hat Openshift Local by running crc setup:

   crc setup
   
   # Output
   INFO Using bundle path https://storage.googleapis.com/crc-bundle-github-ci/4.12.5/crc_vfkit_4.12.5_amd64.crcbundle
   INFO Checking if running as non-root
   INFO Checking if crc-admin-helper executable is cached
   INFO Checking if running on a supported CPU architecture
   INFO Checking minimum RAM requirements
   INFO Checking if crc executable symlink exists
   INFO Checking if running emulated on a M1 CPU
   INFO Checking if vfkit is installed
   INFO Checking if CRC bundle is extracted in '$HOME/.crc'
   INFO Checking if https://storage.googleapis.com/crc-bundle-github-ci/4.12.5/crc_vfkit_4.12.5_amd64.crcbundle exists
   INFO Getting bundle for the CRC executable
   INFO Downloading bundle: https://storage.googleapis.com/crc-bundle-github-ci/4.12.5/crc_vfkit_4.12.5_amd64.crcbundle...
   3.07 GiB / 3.07 GiB [--------------------------------------------------------------->] 99.88% 11.39 MiB p/s
   INFO Uncompressing /Users/davidross/.crc/cache/crc_vfkit_4.12.5_amd64.crcbundle
   crc.img:  31.00 GiB / 31.00 GiB [-----------------------------------------------------------------] 100.00%
   INFO Checking if old launchd config for tray and/or daemon exists
   INFO Checking if crc daemon plist file is present and loaded
   INFO Adding crc daemon plist file and loading it
   Your system is correctly setup for using CRC. Use 'crc start' to start the instance
   

4. Start the Red Hat Openshift Local instance:

   crc start
   
   # Output
   
   INFO Checking if running as non-root
   INFO Checking if crc-admin-helper executable is cached
   INFO Checking if running on a supported CPU architecture
   INFO Checking minimum RAM requirements
   INFO Checking if crc executable symlink exists
   INFO Checking if running emulated on a M1 CPU
   INFO Checking if vfkit is installed
   INFO Checking if old launchd config for tray and/or daemon exists
   INFO Checking if crc daemon plist file is present and loaded
   INFO Loading bundle: crc_vfkit_4.12.5_amd64...
   INFO Creating CRC VM for openshift 4.12.5...
   INFO Generating new SSH key pair...
   INFO Generating new password for the kubeadmin user
   INFO Starting CRC VM for openshift 4.12.5...
   INFO CRC instance is running with IP 127.0.0.1
   INFO CRC VM is running
   INFO Updating authorized keys...
   INFO Resizing /dev/vda4 filesystem
   INFO Configuring shared directories
   INFO Check internal and public DNS query...
   INFO Check DNS query from host...
   INFO Verifying validity of the kubelet certificates...
   INFO Starting kubelet service
   INFO Waiting for kube-apiserver availability... [takes around 2min]
   INFO Adding user's pull secret to the cluster...
   INFO Updating SSH key to machine config resource...
   INFO Waiting for user's pull secret part of instance disk...
   INFO Changing the password for the kubeadmin user
   INFO Updating cluster ID...
   INFO Updating root CA cert to admin-kubeconfig-client-ca configmap...
   INFO Starting openshift instance... [waiting for the cluster to stabilize]
   INFO 4 operators are progressing: image-registry, network, openshift-controller-manager, service-ca
   INFO 4 operators are progressing: image-registry, network, openshift-controller-manager, service-ca
   INFO 4 operators are progressing: image-registry, network, openshift-controller-manager, service-ca
   INFO 4 operators are progressing: image-registry, network, openshift-controller-manager, service-ca
   INFO 4 operators are progressing: image-registry, network, openshift-controller-manager, service-ca
   INFO 3 operators are progressing: image-registry, network, openshift-controller-manager
   INFO Operator image-registry is progressing
   INFO All operators are available. Ensuring stability...
   INFO Operators are stable (2/3)...
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   INFO Operator authentication is progressing
   ERRO Cluster is not ready: cluster operators are still not stable after 10m0.746213711s
   INFO Adding crc-admin and crc-developer contexts to kubeconfig...
   Started the OpenShift cluster.
   
   The server is accessible via web console at:
     https://console-openshift-console.apps-crc.testing
   
   Log in as administrator:
     Username: kubeadmin
     Password: 3hT2A-JJv5U-VAJia-RNpSs
   
   Log in as user:
     Username: developer
     Password: developer
   
   Use the 'oc' command line interface:
     $ eval $(crc oc-env)
     $ oc login -u developer https://api.crc.testing:6443
   

   Depending on the speed of your system, this will take 8 to 15 minutes. There is a 10 minute timeout on checking the stability of operators deployed by Openshift. It might be the case that the tool reports these have not reached full stability in that window. In the writing of this guide, no issues were found using Openshift deployed in this manner, even if the error occurs. Each time these steps were tested, everything eventually reached a healthy status, but just not in the window expected on some occasions. You can see this error at the end of the output displayed above (Cluster is not ready).

Mac bug workaround

1. On the Mac platform only, you might have to work around a certificate issue. This situation is not a problem on other platforms. You can follow this ticket to see when it is addressed; it was still open at the time of this writing.

   The issue appears when you attempt to login at the command line, resulting in an x509 certificate error as shown here:

   oc login -u developer https://api.crc.testing:6443
   error: x509: “ingress-operator@1655391148” certificate is not trusted
   

   The workaround to this error is to trust two certificates in the Apple Keychain Access utility.

2. Login to the web console as kubeadmin, using the credentials displayed when starting the instance. If necessary, you can run crc console --credentials to display them again. The console url is https://console-openshift-console.apps-crc.testing.

   • In the web console, select the Administrator role from the top of the left navigation bar.
   • Navigate to Workloads > Secrets and filter for external-loadbalancer-serving-certkey. It will be in the openshift-kube-api server project (namespace).
   • Select the secret.
   • Copy the contents of tls.crt to a local file on your Mac
   • Open the file with the keychain application and add the certificate to the system keychain.
   • Mark the certificate (called kube-apiserver-lb-signer in the Keychain UI) as always trusted. Double click to open it, then expand the trust section and make the selection:
   • Repeat this process for tls.crt, found in the router-ca secret in the openshift-ingress-operator project. This certificate will be named ingress-operator@NNN in the Keychain UI.

   At this point, the command line login will work:

   oc login -u developer -p developer https://api.crc.testing:6443
   
   # Output
   Login successful.
   
   You don't have any projects. You can try to create a new project, by running
   
       oc new-project <projectname>
   

Setup is complete. This local environment should be ready to deploy our Helm examples

Stop the Red Hat Openshift Local instance

When not working with the environment, you can stop the instance by running the following command. All settings, projects and objects created will be retained and available when it is started again.

crc stop

Run crc start again to launch the instance.

Delete the Red Hat Openshift Local instance

You can also remove the instance by running the following command. If you do this, the embedded VM instance, all objects and projects created will be lost. A new instance will be deployed the next time you run crc start.

crc delete

Remove all configuration

Deleting the instance does not delete the configuration settings for Red Hat Openshift Local (RAM, CPU, disk, and so on, created or modified when running the crc config set command). If you want to completely remove all configuration, you can delete the $HOME/.crc folder and its contents. Also, you will need to edit /etc/hosts and remove the following aliases to the 127.0.0.1 IP: api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing