Posted in: Technical Blogs

OpenShift Installation in Fifteen Minutes*

* Well, fifteen minutes work, plus around three quarters of an hour drinking coffee and watching log messages.

Note that some of the AWS prerequisites can take some time to propagate (particularly the DNS entries), so you might want to do those up front. Also, the OpenShift installer is only available for Linux or macOS. However, once you’ve installed OpenShift you can then manage the cluster with the command-line interface on Linux, macOS, or Windows. This post assumes the use of a Linux machine – the commands and output may differ slightly for macOS.

 

The Preamble

If you’re new to OpenShift, it is “an enterprise-ready Kubernetes container platform with full-stack automated operations to manage hybrid cloud and multi-cloud deployments. Red Hat OpenShift is optimized to improve developer productivity and promote innovation”. I’ve put that in quotes because it’s copied straight off our web page: OpenShift. In practical terms that means you can run containerised workloads on OpenShift more easily and securely than if you were to try and create your own cluster from the open-source Kubernetes and associated projects.

In this series of articles we will help you install and configure an OpenShift cluster on Amazon Web Services (AWS). We will take you through a number of useful steps that you are likely to want to carry out on an OpenShift cluster, to make it more efficient, more secure, easier to manage, etc. Obviously the first thing to do will be to get OpenShift installed, which is what this post is all about.

Although these articles will focus on using AWS as the underlying infrastructure for OpenShift (mainly because it’s fairly cheap and easy to use!), there are many other options available to you. These include Google Cloud Services (GCS), Microsoft Azure, Red Hat OpenStack Platform (RHOSP), Red Hat Virtualisation (RHV), IBM Z, IBM LinuxONE, IBM Power Systems, VMware vSphere, bare metal, or combinations of the above! We’ll try to point out any major differences that you might encounter when using other kinds of infrastructure.

If you would prefer a guided video of the installation process then please watch this webinar presented by one of my colleagues: Easy Installation with Red Hat OpenShift 4.

 

The Prerequisites

There are a few requirements that we need in advance of the actual OpenShift installation. As mentioned above, some of these can take a little time to happen (in particular the domain name registration), so it’s probably best to get them sorted in advance.

Accounts

The first things you will need are an AWS account and a Red Hat account. If you don’t already have both accounts they are free to create, but you need to be aware that:

  • The OpenShift cluster uses bigger compute nodes than are available in the AWS “Free Tier”, so you will definitely end up with charges on your account! Also, the account could theoretically take up to 24 hours to activate, although in practice it’s usually a few minutes. Read more about creating an account on the Amazon web site: How do I create and activate a new AWS account?.
  • A trial Red Hat account lasts for 60 days and will be “self-supported” – you won’t have access to Red Hat’s support teams, but you will be able to use their support documentation. You can read about OpenShift and register for a trial account on the Red Hat web site: Red Hat OpenShift.

AWS Network

So that requests can be routed from the internet to your applications in OpenShift you will need to set up a couple of things:

  • Register a domain name, such as “yourcompany.com”, in Amazon’s Route 53 Domain Name System (DNS). You can register a new domain, transfer an existing domain, register subdomains of an existing parent domain such as “test.yourcompany.com” and transfer subdomains. The prices vary from a few dollars annually to a few hundred, so be careful what type of domain you register! Details of how to register a new domain can be found in the AWS documentation: Registering and managing domains using Amazon Route 53.
  • A public hosted zone, which is responsible for routing traffic to a domain or subdomain. A public hosted zone is created automatically if you register a new domain as above, but you may need to create it manually if you migrate an existing domain. There is also a small monthly charge for this hosted zone. There’s lots of information about hosted zones in the AWS documentation: Working with public hosted zones.

The rest of the network configuration that is required for the OpenShift cluster itself is created by the OpenShift installer.

AWS User

The OpenShift installer application uses the AWS API to create all the underlying infrastructure components for the cluster, such as machines, networking, etc. In order to do this you will need a user with “Programmatic access” and the “AdministratorAccess” policy. You can create a user in AWS here. The steps are:

  • Enter a sensible user name, such as “openshift-cluster-installer”.
  • Tick the “Programmatic access” checkbox, as this will allow access via the API.
  • Click “Next” to take you to the permissions page.
  • Click “Attach existing policies directly” and select the “AdministratorAccess” policy. This will give the user sufficient rights to create all the required objects. Alternatively create a group with this policy and add the user to the group.
  • Nothing else is required, so click “Next” a couple of times then “Create User”.
  • On the next page you will see the Access key ID and Secret access key. Either copy these somewhere, or download the CSV file, as you will need them during the install. Note that for added security you cannot retrieve the Secret access key after you navigate away from this page.

 

The Actual Installation

Now we get on to the installation itself. OpenShift can be installed in two ways: User-Provisioned Infrastructure (UPI) or Installer-Provisioned Infrastructure (IPI). UPI is very flexible, but requires the user (you!) to set up a lot of the infrastructure manually. Also UPI is not available for some hardware, such as when installing on bare metal. IPI does most of the hard work for you, but is much more limited in how it can be customised. For the purpose of this post we will use IPI, as it’s far simpler to get a cluster up and running quickly.

  1. Create a new directory to contain the installation files, and switch to that directory. 
    mkdir openshift-install
cd openshift-install/
  2. Download the OpenShift installer. Here I’m downloading version 4.7.2 using wget, alternatively you can download a differently numbered version or the latest version. 
    wget https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.7.2/openshift-install-linux.tar.gz

    The output should look something like this:

    --2021-03-18 18:32:52-- https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.7.2/openshift-install-linux.tar.gz
Resolving mirror.openshift.com (mirror.openshift.com)... 54.173.18.88, 54.172.163.83
Connecting to mirror.openshift.com (mirror.openshift.com)|54.173.18.88|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 89452306 (85M) [application/x-gzip]
Saving to: ‘openshift-install-linux.tar.gz’

openshift-install-linux.tar.gz 100%[================================================================================================================>] 85.31M 76.9MB/s in 1.1s

2021-03-18 18:32:53 (76.9 MB/s) - ‘openshift-install-linux.tar.gz’ saved [89452306/89452306]
  3. Extract the installer application. 
    tar xvf openshift-install-linux.tar.gz

    Output:

    README.md
openshift-install
  4. Check that the installer runs correctly. 
    ./openshift-install version

    Output:

    ./openshift-install 4.7.2
built from commit 98e11541c24e95c864328b9b35c64b77836212ed
release image quay.io/openshift-release-dev/ocp-release@sha256:83fca12e93240b503f88ec192be5ff0d6dfe750f81e8b5ef71af991337d7c584
  5. Optional step. Create a public / private key pair to enable SSH access to the machines. This is recommended for production environments to allow troubleshooting if problems arise. See the Red Hat documentation for more details: Generating an SSH private key and adding it to the agent.
    1. Create the key pair in the SSH store off your home directory. 
      ssh-keygen -t ed25519 -N '' -f ~/.ssh/openshift_rsa

      Output:

      Generating public/private ed25519 key pair.
Your identification has been saved in /home/ian/.ssh/openshift_rsa.
Your public key has been saved in /home/ian/.ssh/openshift_rsa.pub.
The key fingerprint is:
SHA256:/q6+KiOVwa9CaCYIbWPKqnMf1UE6c8Ps02FWZOWoihk ian@Ians-Mac.tier2consulting.com
The key's randomart image is:
+--[ED25519 256]--+
|        .  .+..  |
|       =   o o   |
| . .  + * + . .  |
|. = o * * o      |
|+= . +E S o      |
|=+. o..= o       |
|=. ...o o        |
|o + +.   .       |
|oo +.o.o++o      |
+----[SHA256]-----+
    2. Start the ssh-agent process as a background task. 
      eval "$(ssh-agent -s)"

      Output:

      Agent pid 1605
    3. Add the private key to the agent. 
      ssh-add ~/.ssh/openshift_rsa

      Output:

      Identity added: /home/ian/.ssh/openshift_rsa (ian@Ians-Mac.tier2consulting.com)
  6. Copy or download the OpenShift pull secret for your Red Hat account from the pull secret page
  7. Run the interactive installer. The output of the install will be placed in the given directory (in this case aws-install) which will be created automatically. There’s a slight alternative to this which allows for some further customisation – see the imaginatively named section “The Alternative Step 7” below. 
    ./openshift-install create cluster --dir=aws-install/

    The installer will collect some essential data to configure the cluster and allow the install to connect to AWS. Note that the questions the installer asks will depend on the platform you select. The questions below are obviously AWS related.

    1. Select the public key created in step 5, or <none> if you skipped that step. 
      ? SSH Public Key /home/ian/.ssh/openshift_rsa.pub
    2. Select AWS as the platform. The installer offers a few options, however IPI is not available for all the OpenShift supported platforms so it’s just a subset. The options have gradually increased since the installer was introduced, so hopefully we’ll see some more soon. 
      ? Platform aws
    3. Enter the secret key ID obtained when you created the AWS user. 
      ? AWS Access Key ID AKIAV72XFGYFFUXWAE5Y
    4. Enter the secret access key obtained when you created the AWS user. Once you do this, your credentials will be saved for future use in a file in your home directory. 
      ? AWS Secret Access Key [? for help] ****************************************

INFO Writing AWS credentials to "/home/ian/.aws/credentials" (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
    5. Select the AWS region where you would like the cluster installed. Keep scrolling down if you don’t see the region you want at first. 
      ? Region eu-west-2
    6. Select the base domain to use. This is the domain name you registered with (or transferred to) Route 53. 
      ? Base Domain tier2openshift.co.uk
    7. Enter a name for the cluster. Use something short but descriptive, as it will appear in the URLs of the management web console and the applications you deploy to OpenShift. 
      ? Cluster Name demo
    8. Finally, paste in the pull secret that you obtained in step 6. There will be a lot more asterisks in the real value! 
      ? Pull Secret [? for help] **************************************************

    The installer will now run and give you periodic updates about its progress. This is when you go and make that coffee – as you can see from the output below it can take a while…

    INFO Creating infrastructure resources...
INFO Waiting up to 20m0s for the Kubernetes API at https://api.demo.tier2openshift.co.uk:6443...
INFO API v1.20.0+5fbfd19 up
INFO Waiting up to 30m0s for bootstrapping to complete...
INFO Destroying the bootstrap resources...
INFO Waiting up to 40m0s for the cluster at https://api.demo.tier2openshift.co.uk:6443 to initialize...
INFO Waiting up to 10m0s for the openshift-console route to be created...
INFO Install complete
INFO To access the cluster as the system:admin user when using 'oc', run 'export KUBECONFIG=/home/ian/openshift-install/aws-install/auth/kubeconfig'
INFO Access the OpenShift web-console here: https://console-openshift-console.apps.demo.tier2openshift.co.uk
INFO Login to the console with user: "kubeadmin", and password: "MSEFC-vTSGI-GqmTJ-qBjef"
INFO Time elapsed: 49m42s

That’s it! You now have a working OpenShift cluster, that you can access via the web console on the URL shown using the given credentials. These are the only credentials that you can log in with at the moment, so keep them safe!

 

The Alternative Step 7

You should read this section in conjunction with step 7 above.

One thing you’ll notice from the steps above is that there is no way to customise the cluster. You will get a control plane with three master nodes which take care of the cluster management, and three worker nodes where your applications can run. If you want to change this there is a slightly different install command, which just generates the installation configuration file rather than the actual cluster. This will ask you the same interactive questions (although you won’t be asked again for your AWS credentials if you’ve entered them before), but this time it will generate an install-config.yaml file in the given output directory.

./openshift-install create install-config --dir=aws-install

Output:

INFO Install-Config created in: aws-install

The contents of the file will look similar to the one shown below. Here though I’ve changed the replicas for the compute (worker) nodes from 3 to 2 in line 8, so that I’ll have fewer workers to run my applications on. There are other changes that you can make to this file, but they’re outside the scope of this article.

apiVersion: v1
  baseDomain: sandbox1250.opentlc.com
  compute:
  - architecture: amd64
    hyperthreading: Enabled
    name: worker
    platform: {}
    replicas: 2
  controlPlane:
    architecture: amd64
    hyperthreading: Enabled
    name: master
    platform: {}
    replicas: 3
  metadata:
    creationTimestamp: null
    name: demo
  networking:
    clusterNetwork:
    - cidr: 10.128.0.0/14
      hostPrefix: 23
    machineNetwork:
    - cidr: 10.0.0.0/16
    networkType: OpenShiftSDN
    serviceNetwork:
    - 172.30.0.0/16
  platform:
    aws:
      region: eu-west-2
  publish: External
  pullSecret: '{"auths":{"cloud.openshift.com":{"auth":"********","email":"ipage@tier2consulting.com"}}}'
  sshKey: |
    ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIOIX1Grh2jabz2QX+DiZISc+Cm7m8ZmrBPkhVJnyKIf ian@Ians-Mac.tier2consulting.com

Run the installer again to create the actual cluster

./openshift-install create cluster --dir=aws-install/

When you do this it will take the install-config.yaml file and start the build straight away without prompting for any information.

As part of the installation the configuration file is deleted, so it might be wise to take a copy of it before you start. Alternatively, if you re-run the command to generate the installation configuration file after your cluster is built, it will re-create it for you based on the existing installation, again without prompting for information.

./openshift-install create install-config --dir=aws-install

Output:

INFO Install-Config created in: aws-install

 

Help! I Installed an OpenShift Cluster Accidentally

You can use the installer to destroy the cluster too. This just takes a few minutes, and is far easier than trying to remove components manually from AWS. It uses the output from the install command to retrieve the required cluster information, so does not require anything else. Note that there’s no “Are you sure?” type confirmation, so be certain that you really want to do this!

./openshift-install destroy cluster --dir=aws-install

This produces a fair bit of output – not surprisingly it’s mostly about things being deleted. When it has finished, the last line will give the elapsed time of the process.

INFO Time elapsed: 4m11s

 

The End

In this article you’ve seen how to prepare for and install an OpenShift cluster on AWS, how to customise the installation slightly by changing the number of nodes created, and how to destroy the cluster.

In the next article you’ll learn how to install and use the OpenShift Command-Line Client (“oc”), and then add some users to the cluster.

Recommended Articles