An Introduction to Red Hat OpenShift CodeReady Containers

Introduction to the Manual

This manual is made to guide you step by step in setting up an OpenShift cloud environment on your own device. It will tell you what needs to be done when it needs to be done, what you will be doing, and why you will be doing it, all in one convenient manual that is made for Windows users. Be warned however some system requirements are necessary to run the CodeReady Containers that we will be using. These requirements are specified within the chapter Minimum system requirements.

This manual is written for everyone with an interest in the Red Hat OpenShift Container Platform and has at least a basic understanding of the command line within PowerShell on Windows. Even though it is possible to use most of the manual for Linux or macOS we will focus on how to do this within Windows.

If you follow this manual you will be able to do the following items by yourself:

• Installing the CodeReady Containers

• Updating OpenShift

• Configuring a CodeReady Container

• Configuring the DNS

• Accessing the OpenShift cluster 

• Deploying the Mediawiki application

What Is the OpenShift Container Platform?

Red Hat OpenShift is a cloud development Platform as a Service (PaaS). It enables developers to develop and deploy their applications on a cloud infrastructure. It is based on the Kubernetes platform and is widely used by developers and IT operations worldwide. The OpenShift Container Platform makes use of CodeReady Containers. CodeReady Containers are pre-configured containers that can be used for developing and testing purposes. There are also CodeReady Workspaces, these workspaces are used to provide any member of the development or IT team with a consistent, secure, and zero-configuration development environment.

The OpenShift Container Platform is widely used because it helps the programmers and developers make their application faster because of CodeReady Containers and CodeReady Workspaces and it also allows them to test their application in the same environment. One of the advantages provided by OpenShift is an efficient container orchestration. This allows for faster container provisioning, deploying, and management. It does this by streamlining and automating the automation process.

What knowledge is required or recommended to proceed with the installation?

To be able to follow this manual some knowledge is mandatory, because most of the commands are done within the Command Line interface it is necessary to know how it works and how you can browse through files/folders. If you either don’t have this basic knowledge or have trouble with the basic Command Line Interface commands from PowerShell, then a cheat sheet might offer some help. We recommend the following cheat sheet for windows:

• https://www.sans.org/security-resources/sec560/windows_command_line_sheet_v1.pdf 

Another option is to read through the operating system’s documentation or introduction guides. Though the documentation can be overwhelming by the sheer amount of commands.

• Microsoft: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands

• MacOS: https://www.makeuseof.com/tag/mac-terminal-commands-cheat-sheet/

• Linux: https://ubuntu.com/tutorials/command-line-for-beginners#2-a-brief-history-lesson
  https://www.guru99.com/linux-commands-cheat-sheet.htmlhttp://cc.iiti.ac.in/docs/linuxcommands.pdf

Aside from the required knowledge, some things can be helpful to know just to make the use of OpenShift a bit simpler. This consists of some general knowledge on PaaS like Dockers and Kubernetes.

System Requirements

Minimum System Requirements

The minimum system requirements for the Red Hat OpenShift CodeReady Containers has the following minimum hardware:

Hardware Requirements 

Code Ready Containers requires the following system resources:

• 4 virtual CPU’s

• 9 GB of free random-access memory

• 35 GB of storage space

• Physical CPU with Hyper-V (intel) or SVM mode (AMD) this has to be enabled in the bios

Software Requirements

The minimum system requirements for the Red Hat OpenShift CodeReady Containers has the following minimum operating system requirements:

Microsoft Windows

On Microsoft Windows, the Red Hat OpenShift CodeReady Containers requires the Windows 10 Pro Fall Creators Update (version 1709) or newer. CodeReady Containers does not work on earlier versions or other editions of Microsoft Windows. Microsoft Windows 10 Home Edition is not supported.

macOS

On macOS, the Red Hat OpenShift CodeReady Containers requires macOS 10.12 Sierra or newer. 

Linux

On Linux, the Red Hat OpenShift CodeReady Containers is only supported on Red Hat Enterprise Linux/CentOS 7.5 or newer and on the latest two stable Fedora releases.

When using Red Hat Enterprise Linux, the machine running CodeReady Containers must be registered with the Red Hat Customer Portal.

Ubuntu 18.04 LTS or newer and Debian 10 or newer are not officially supported and may require manual set up of the host machine.

Required Additional Software Packages for Linux

The CodeReady Containers on Linux require the libvirt and Network Manager packages to run. Consult the following table to find the command used to install these packages for your Linux distribution:

Table 1.1 Package installation commands by distribution

Installation

Getting Started With the Installation

To install CodeReady Containers a few steps must be undertaken. Because an OpenShift account is necessary to use the application this will be the first step. An account can be made on “https://www.openshift.com/”, where you need to press login and after that select, the option “Create one now”.

After making an account the next step is to download the latest release of CodeReady Containers and the pulled secret on “https://cloud.redhat.com/openshift/install/crc/installer-provisioned”. Make sure to download the version corresponding to your platform and/or operating system. After downloading the right version, the contents have to be extracted from the archive to a location in your $PATH. The pulled secret should be saved because it is needed later. 

The command-line interface has to be opened before we can continue with the installation. For windows, we will use PowerShell. All the commands we use during the installation procedure of this guide are going to be done in this command-line interface unless stated otherwise. To be able to run the commands within the command-line interface, use the command-line interface to go to the location in your $PATH where you extracted the CodeReady zip.

If you have installed an outdated version and you wish to update, then you can delete the existing CodeReady Containers virtual machine with the $crc delete command. After deleting the container, you must replace the old CRC binary with a newly downloaded binary of the latest release. 

When you have done the previous steps please confirm that the correct and up-to-date CRC binary is in use by checking it with the $crc version command, this should provide you with the version that is currently installed.

To set up the host operating system for the CodeReady Containers virtual machine you have to run the $crc setup command. After running the CRC setup, CRC start will create a minimal OpenShift 4 cluster in the folder where the executable is located.

Setting Up CodeReady Containers

Now we need to set up the new CodeReady Containers release with the $crc setup command. This command will perform the operations necessary to run the CodeReady Containers and create the ~/.crc directory if it did not previously exist. In the process you have to supply your pulled secret, once this process is completed you have to reboot your system. When the system has restarted you can start the new CodeReady Containers virtual machine with the $crc start command. The $crc start command starts the CodeReady virtual machine and OpenShift cluster. 

You cannot change the configuration of an existing CodeReady Container virtual machine. So if you have a CodeReady Containers virtual machine and you want to make configuration changes you need to delete the virtual machine with the $crc delete command and create a new virtual machine and start that one with the configuration changes. Take note that deleting the virtual machine will also delete the data stored in the CodeReady Containers. So, to prevent data loss we recommend you save the data you wish to keep. Also, keep in mind that it is not necessary to change the default configuration to start OpenShift.

Before starting the machine, you need to keep in mind that it is not possible to make any changes to the virtual machine. For this tutorial however it is not necessary to change the configuration, if you don’t want to make any changes please continue by starting the machine with the CRC start command.

* you may get a Nameserver error later on, if this is the case please start it with CRC start -n 1.1.1.1

Configuration

It is not necessary to change the default configuration and continue with this tutorial, this chapter is here for those that wish to do so and know what they are doing. However, for macOS and Linux it is necessary to change the DNS settings.

Configuring the CodeReady Containers

To start the configuration of the CodeReady Containers uses the command crc config. This command allows you to configure the CRC binary and the CodeReady virtual machine. The command has some requirements before it’s able to configure. This requirement is a subcommand, the available subcommands for this binary and virtual machine are:

• Get, this command allows you to see the values of a configurable property

• Set/unset, this command can be used for 2 things. To display the names of, or to set and/or unset values of several options and parameters. These parameters being:

  • Shell options

  • Shell attributes

  • Positional parameters

• View, this command starts the configuration in read-only mode.

These commands need to operate on named configurable properties. To list all the available properties, you can run the command $crc config --help.

Throughout this manual, we will use the $crc config command a few times to change some properties needed for the configuration. 

There is also the possibility to use the CRC config command to configure the behavior of the checks that are done by the $crc start to end $crc setup commands. By default, the startup checks will stop with the process if their conditions are not met. To bypass this potential issue, you can set the value of a property that starts with skip-check or warn-check to true to skip the check or warning instead of ending up with an error.

Configuring the Virtual Machine

You can use the CPUs and memory properties to configure the default number of vCPU’s and the amount of memory available for the virtual machine. 

To increase the number of vCPU’s available to the virtual machine use the $crc config set CPUs <number of CPU’s>. Keep in mind that the default number for the CPU’s is 4 and the number of vCPU’s you wish to assign must be equal or greater than the default value.

To increase the memory available to the virtual machine, use the $crc config set memory <number in mebibytes>. Keep in mind that the default number for the memory is 9216 Mebibytes and the amount of memory you wish to assign must be equal to or greater than the default value.

Configuring the DNS

Window/General DNS Setup

There are two domain names used by the OpenShift cluster that is managed by the CodeReady Containers, these are:

• Crc.testing, this is the domain for the core OpenShift services.

• Apps-crc.testing, this is the domain used for accessing OpenShift applications that are deployed on the cluster.

Configuring the DNS settings in Windows is done by executing the CRC setup. This command automatically adjusts the DNS configuration on the system. When executing crc start additional checks to verify the configuration will be executed. 

MacOS DNS Setup

MacOS expects the following DNS configuration for the CodeReady Containers

• The CodeReady Containers creates a file that instructs the macOS to forward all DNS requests for the testing domain to the CodeReady Containers virtual machine. This file is created at /etc/resolver/testing.

• The oc binary requires the following CodeReady Containers entry to function properly, api.crc.testing adds an entry to /etc/hosts pointing at the VM IP address.

Linux DNS setup

CodeReady containers expect a slightly different DNS configuration. CodeReady Container expects the NetworkManager to manage networking. On Linux the NetworkManager uses dnsmasq through a configuration file, namely /etc/NetworkManager/conf.d/CRC-nm-dnsmasq.conf. 

To set it up properly the dnsmasq instance has to forward the requests for crc.testing and apps-CRC. testing domains to “192.168.130.11”. In the /etc/NetworkManager/conf.d/CRC-nm-dnsmasq.conf this will look like the following:

• Server=/crc. Testing/192.168.130.11

• Server=/apps-crc. Testing/192.168.130.11

Accessing the Openshift Cluster

Accessing the Openshift Web Console

To gain access to the OpenShift cluster running in the CodeReady virtual machine you need to make sure that the virtual machine is running before continuing with this chapter. The OpenShift clusters can be accessed through the OpenShift web console or the client binary(oc).

First, you need to execute the $crc console command, this command will open your web browser and direct a tab to the web console. After that, you need to select the  htpasswd_provider option in the OpenShift web console and log in as a developer user with the output provided by the CRC start command.

It is also possible to view the password for kubeadmin and developer users by running the $crc console --credentials command. While you can access the cluster through the kubeadmin and developer users, it should be noted that the kubeadmin user should only be used for administrative tasks such as user management and the developer user for creating projects or OpenShift applications and the deployment of these applications. 

Accessing the OpenShift Cluster With OC

To gain access to the OpenShift cluster with the use of the oc command you need to complete several steps.

Step 1.

Execute the $crc oc-env command to print the command needed to add the cached oc binary to your PATH:

Step 2.

Execute the printed command.

This means we have to execute* the command that the output gives us, in this case, that is:

*this has to be executed every time you start; a solution is to move the OC binary to the same path as the CRC binary

To test if this step went correctly execute the following command, if it returns without errors oc is set up properly

Step 3.

Now you need to log in as a developer user, this can be done using the following command:

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

Keep in mind that the $crc start will provide you with the password that is needed to login with the developer user.

Step 4.

The OC can now be used to interact with your OpenShift cluster. If you for instance want to verify if the OpenShift cluster Operators are available, you can execute the command 

$oc get co.

Keep in mind that by default the CodeReady Containers disables the functions provided by the commands $machine-config and $monitoringOperators.

Demonstration

Now that you can access the cluster, we will take you on a tour through some of the possibilities within the OpenShift Container Platform.

We will start by creating a project. Within this project, we will import an image, and with this image, we are going to build an application. After building the application we will explain how upscaling and downscaling can be used within the created application. 

As the next step, we will show the user how to make changes in the network route. We also show how monitoring can be used within the platform; however, within the current version of CodeReady Containers, this has been disabled. 

Lastly, we will show the user how to use user management within the platform. 

Creating a Project

To be able to create a project within the console you have to log in on the cluster. If you have not yet done this, this can be done by running the command CRC console in the command line and logging in with the login data from before.

When you are logged in as admin, switch to Developer. If you're logged in as a developer, you don't have to switch. Switching between users can be done with the dropdown menu top left.

Now that you are properly logged in press the dropdown menu shown in the image below, from there click on create a project.

When you press the correct button, the following image will pop up. Here you can give your project a name and description. We chose to name it CodeReady with a display name CodeReady Container.

Importing Image

The Containers in OpenShift Container Platform are based on OCI or Docker formatted images. An image is a binary that contains everything needed to run a container as well as the metadata of the requirements needed for the container.

Within the OpenShift Container Platform, it’s possible to obtain images in several ways. There is an integrated Docker registry that offers the possibility to download new images “on the fly”. Also, OpenShift Container Platform can use third party registries such as:

• Https://hub.docker.com/ 

• Https://catalog.redhat.com/software/containers/search 

Within this manual, we are going to import an image from the Red Hat container catalog. In this example, we’ll be using MediaWiki.

Search for the application in https://catalog.redhat.com/software/containers/search

Navigate to “Get this image”

Follow the steps to “create a registry service account”, that you can copy the YAML.

After the YAML has been copied we will go to the topology view and click on the YAML button.

Then we have to paste in the YAML, put in the name, namespace, and your pull secret name (which you created through your registry account), and click on create.

Run import command

Creating and Managing an Application

There are a few ways to create and manage applications. Within this demonstration, we’ll show how to create an application from the previously imported image. 

Creating the Application

To create an image with the previously imported image go back to the console and topology. From here on select container image.

For the option image, you'll want to select the “image stream tag from the internal registry” option. Give the application a name and then create the deployment.

If everything went right during the creating process you should see the following, this means that the application is successfully running.

Scaling the Application

In OpenShift there is a feature called autoscaling. There are two types of application scaling, namely vertical scaling, and horizontal scaling. Vertical scaling is adding only more CPU and hard disk and is no longer supported by OpenShift. Horizontal scaling is increasing the number of machines.

One of the ways to scale an application is by increasing the number of pods. This can be done by going to a pod within the view as seen in the previous step. By either pressing the up or down arrow more pods of the same application can be added. This is similar to horizontal scaling and can result in better performance when there are a lot of active users at the same time. 

In the picture above we see the number of nodes and pods and how many resources those nodes and pods are using. This is something to keep in mind if you want to scale up your application, the more you scale it up, the more resources it will take up.

Network

Since the OpenShift Container Platform is built on Kubernetes it might be interesting to know some theory about its networking. Kubernetes, on which the OpenShift Container Platform is built, ensures that the Pods within OpenShift can communicate with each other via the network and assigns them their own IP address. This makes all containers within the Pod behave as if they were on the same host. By giving each pod its own IP address, pods can be treated like physical hosts or virtual machines in terms of port mapping, networking, naming, service discovery, load balancing, application configuration, and migration. To run multiple services such as front-end and back-end services, OpenShift Container Platform has a built-in DNS.

One of the changes that can be made to the networking of a Pod is the Route. We’ll show you how this can be done in this demonstration. 

The route is not the only thing that can be changed and or configured. Two other options that might be interesting but will not be demonstrated in this manual are:

• Ingress controller, within OpenShift it is possible to set your own certificate. A user must have a certificate/key pair in PEM-encoded files, with the certificate signed by a trusted authority.

• Network policies, by default all pods in a project, are accessible from other pods and network locations. To isolate one or more pods in a project, it is possible to create Network Policy objects in that project to indicate the allowed incoming connections. Project administrators can create and delete Network Policy objects within their own projects.

There is a search function within the Container Platform. We’ll use this to search for the network routes and show how to add a new route.

You can add items that you use a lot to the navigation.

For this example, we will add Routes to navigation.

Now that we’ve added Routes to the navigation, we can start the creation of the Route by clicking on “Create a route”.

Fill in the name, select the service, and the target port from the drop-down menu and click on Create.

As you can see, we’ve successfully added the new route to our application.

Storage 

OpenShift makes use of Persistent Storage, this type of storage uses persistent volume claims (PVC). PVC’s allow the developer to make persistent volumes without needing any knowledge about the underlying infrastructure.

Within this storage there are a few configuration options:

• Reclaim
• Recycle
• Delete

It is, however, important to know how to manually reclaim the persistent volumes, since if you delete PV the associated data will not be automatically deleted with it and therefore you cannot reassign the storage to another PV yet. 

To manually reclaim the PV, you need to follow the following steps:

1. Delete the PV, this can be done by executing the following command

2. Now you need to clean up the data on the associated storage asset

3. Now you can delete the associated storage asset or if you wish to reuse the same storage asset you can now create a PV with the storage asset definition.

It is also possible to directly change the reclaim policy within OpenShift, to do this you would need to follow the following steps: 

1. Get a list of the PVs in your cluster

This will give you a list of all the PV’s in your cluster and will display their following attributes: Name, Capacity, Accesmodes, Reclaimpolicy, Statusclaim, Storageclass, Reason, and Age.

2. Now choose the PV you wish to change and execute one of the following command’s, depending on your preferred policy:

In this example the reclaim policy will be changed to Retain.

In this example the reclaim policy will be changed to Recycle.

In this example the reclaim policy will be changed to Delete.

3. After this you can check the PV to verify the change by executing this command again:

Monitoring

Within Red Hat OpenShift there is the possibility to monitor the data that has been created by your containers, applications, and pods. To do so, click on the menu option in the top left corner. Check if you are logged in as Developer and click on “Monitoring”. Normally this function is not activated within the CodeReady containers, because it uses a lot of resources (Ram and CPU) to run. 

Once you have activated “Monitoring” you can change the “Time Range” and “Refresh Interval” in the top right corner of your screen. This will change the monitoring data on your screen. 

Within this function, you can also monitor “Events”. These events are records of important information and are useful for monitoring and troubleshooting within the OpenShift Container Platform. 

User Management

According to the documentation of OpenShift is a user, an entity that interacts with the OpenShift Container Platform API. These can be a developer for developing applications or an administrator for managing the cluster. Users can be assigned to groups, which set the permissions applied to all the group’s members. For example, you can give API access to a group, which gives all members of the group API access. 

There are multiple ways to create a user depending on the configured identity provider. The DenyAll identity provider is the default within the OpenShift Container Platform. This default denies access to all the usernames and passwords. 

First, we’re going to create a new user, the way this is done depends on the identity provider, this depends on the mapping method used as part of the identity provider configuration.

for more information on what mapping methods are and how they function: 

https://docs.openshift.com/enterprise/3.1/install_config/configuring_authentication.html

With the default mapping method, the steps will be as following

Next up, we’ll create an OpenShift Container Platform Identity. Use the name of the identity provider and the name that uniquely represents this identity in the scope of the identity provider:

The <identity-provider> is the name of the identity provider in the master configuration. For example, the following commands create an Identity with identity provider ldap_provider and the identity provider username mediawiki_s.

Create a user/identity mapping for the created user and identity:

For example, the following command maps the identity to the user:

Now we're going to assign a role to this new user, this can be done by executing the following command:

There is a --clusterrole option that can be used to give the user a specific role, like a cluster user with admin privileges. The cluster-admin has access to all files and can manage the access level of other users. 

Below is an example of the admin cluster role command:

What Did You Achieve?

If you followed all the steps within this manual you now should have a functioning Mediawiki Application running on your own CodeReady Containers. During the installation of this application on CodeReady Containers you have learned how to do the following things:

• Installing the CodeReady Containers

• Updating OpenShift

• Configuring a CodeReady Container

• Configuring the DNS

• Accessing the OpenShift cluster 

• Deploying an application

• Creating new users

With these skills, you’ll be able to set up your own Container Platform environment and host applications of your choosing.

Troubleshooting

Nameserver

There is the possibility that your CodeReady container can't connect to the internet due to a Nameserver error. When this is encountered a working fix for us was to stop the machine and then start the CRC machine with the following command:

Hyper-V Admin

Should you run into a problem with Hyper-V it might be because your user is not an admin and therefore can’t access the Hyper-V admin user group. 

1. Click Start, search for "Computer Management". The Computer Management window opens.

2. Click System Tools > Local Users and Groups > Groups. The list of groups opens.

3. Double-click the Hyper-V Administrators group. The Hyper-V Administrators Properties window opens.

4. Click Add. The Select Users or Groups window opens.

5. In the Enter the object names to select field, enter the user account name to whom you want to assign permissions, and then click OK.

6. Click Apply, and then click OK.

Terms and Definitions

These terms and definitions will be expanded upon, below you can see an example of how this is going to look like together with a few terms that will require definitions.

• Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. Openshift is based on Kubernetes.

• Clusters are a collection of multiple nodes that communicate with each other to perform a set of operations.

• Containers are the basic units of OpenShift applications. These container technologies are lightweight mechanisms for isolating running processes so that they are limited to interacting with only their designated resources.

• CodeReady Container is a minimal, preconfigured cluster that is used for development and testing purposes.

• CodeReady Workspaces uses Kubernetes and containers to provide any member of the development or IT team with a consistent, secure, and zero-configuration development environment. 

Sources

https://www.ibm.com/support/knowledgecenter/en/SSMKFH/com.ibm.apmaas.doc/install/hyperv_config_add_nonadmin_user_hyperv_usergroup.html

https://access.redhat.com/documentation/en-us/openshift_container_platform/4.5/

https://docs.openshift.com/container-platform/3.11/admin_guide/manage_users.html