Prerequisites:

  1. Access to an Azure Account with the User Access Administrator role associated to it (to create an account go here:https://azure.microsoft.com/en-us/free/)
  2. Note that this account needs to be upgraded from the Free Account to the Pay-As-You-Go account.
  3. A registered domain within the Azure Domain system. If you would prefer to use a separate domain you can delegate a 3rd party domain name to your azure account.
  4. Steps to create an Azure Domain Name (this will require you to create an app service in Azure which may lead to extra costs): https://docs.microsoft.com/en-us/azure/app-service/manage-custom-dns-buy-domain
  5. Steps to delegate an existing DNS to Azure: https://docs.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns
  6. You have verified that your Azure account meets the required limits on this page: https://docs.openshift.com/container-platform/4.4/installing/installing_azure/installing-azure-account.html#installation-azure-network-config_installing-azure-account
  7. Download the Openshift Installer from try.openshift.com for the appropriate operating system (Currently MacOS and Linux are the only supported operating systems).
  8. Be sure to download the Openshift CLI tools for your operating system (when extracting this binary file be sure to place it in a location that is included in your PATH variable in order to use these in the command line).
  9. A saved copy of the Pull Secret that is provided on try.openshift.com
  10. A created service principal following the steps found here (one thing to note is that the password created for the service principal sometimes breaks the installer. Ensure the password doesn’t have any special characters. To change this login to your Azure account and create a new secret for the application): https://docs.openshift.com/container-platform/4.4/installing/installing_azure/installing-azure-account.html#installation-azure-network-config_installing-azure-account
  11. It is also important to have an SSH key generated for the bootstrap node in case of failure during the installation.

Installation Procedure:

  1. Navigate to a directory on your local machine where you would like the installer to save log information as well as install files. Or you can run the installer with the --dir= command and that will set the install directory.
  2. Open up a terminal instance and run the following command in the above directory:
  3. openshift-install create cluster
  4. If the Openshift Installer file was not added to your Path variable then run the command: /<directory>/openshift-install create cluster where <directory> is the directory that the Openshift Installer file was extracted to.
  5. The installer will ask you if you would like to use a public SSH key or if you would like to skip this step. Select an SSH key if you would like to have that configured in your cluster. (Again it is helpful to have this as your bootstrap node may crash and the ssh key is helpful for recovering logs)
  6. The next step is to select the platform you would like the cluster installed to. The options are:
  7. AWS
  8. Azure
  9. GCP
  10. OpenStack

Select Azure. That is not to say these are the only options that OCP can be run on. These are the options currently supporting the IPI installer method

  1. If this is not your first time running the installer then skip this step and proceed to the next one. The installer will ask you for your Azure Subscription ID (id)  first then your Azure Tenant ID (tenantID). Then your Azure Service Principal Client ID (appId). And finally your Azure Service Principal Client Secret (password). These credentials will be stored in a .azure directory on your home directory. The directory is hidden but you can navigate to it and modify it in the terminal if there is an issue with your credentials or your need to change them. The file is called osServicePrincipal.json.
  2. The next step is to select the region that you would like your cluster hosted on. If there are no known limitations to the closest Region then select this one. If you would prefer the cluster to be located in a different region then select that region.
  3. The installer will then ask you for your registered base domain. This is your Azure DNS zone that you should have configured during the prerequisites section. Enter that domain exactly as it shows up in Azure DNS Zones.
  4. Next, you will be asked to name your cluster. This will be used when generating hostnames for your 3 masters and 3 worker nodes. If you would like more information then type ? on the command line and helpful information will be provided to you regarding naming.
  5. The final step will be to enter the Pull Secret that you copied from try.openshift.com. Once you have entered the Pull Secret you can hit enter and the installer will begin creating the cluster.
  6. Once the installer completes there will be some credential information displayed in the terminal. This information will include:
  7. The API URL for accessing your cluster via CLI
  8. The console URL for accessing your cluster via a browser
  9. A command to export the KUBEADMIN variable to your local system which will display the location of the kubeadmin account information and allow you to login in as system:admin
  10. The kubeadmin account information for first login either via the CLI or Console.

Troubleshooting:

These are some common issues that I have encountered and how to avoid them:

  1. The first issue I received was a networking issue. This is usually caused by DNS Zone misconfiguration. If Azure cannot connect to the appropriate DNS then you need to verify that the 3rd party DNS or the Azure Domain is configured correctly.
  2. I received some initial login errors due to my Azure Service Principal Client Secret containing some characters that broke the installer. To avoid this generate a secret that doesn’t have those characters. If you would like to change any of the azure information you entered during the installer you can go and edit the osServicePrincipal.json file. You can also check your Azure login by running az login with the appID and password for your service principal.
  3. The final error I received was due to my 3rd party Domain being locked. The installer completed successfully but I was unable to access the cluster url via CLI and console. This was solved by me going to my Domain Registrar and removing extra security measures.
  4. It is also important to note that once created, the cluster should not be shut down for at least 24 hours. This post explains the reasoning: https://access.redhat.com/solutions/4218311

Please note this is my experience when installing OpenShift on Azure. Any opinions in this post are expressly my own and do not reflect Red Hat's opinions on this installation process.