Prerequisites:

  1. Access to an AWS Root Account (to create an account go here: https://portal.aws.amazon.com/billing/signup#/start)
  2. A Registered Domain within the Route53 service on AWS.
  3. Access to an AWS IAM Account with the AdministratorAccess policy attached directly to the user. (Be sure to save the AWS Secret Access Key as well as the Access Key ID when creating this user account).
  4. Download the Openshift Installer from try.openshift.com for the appropriate operating system (Currently MacOS and Linux are the only supported operating systems).
  5. 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).
  6. A saved copy of the Pull Secret that is provided on try.openshift.com

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.
  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 it configured in your cluster.
  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 AWS. 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 AWS Access Key ID first then your AWS Secret Access Key. These credentials will be stored in a .aws 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. Enter your AWS IAM user credentials.
  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 what you registered in Route53 during the prerequisites section. Enter that domain exactly as it shows up in Route53.
  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
  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. If you receive an error message that AWS was unable to authenticate the IAM user you have incorrectly entered the Access Key information. Navigate to the .aws/credentials file on your home directory and ensure that this information matches with the IAM console in AWS. If needed you can generate a new Access Key and enter the new information. Also ensure that your IAM user has the appropriate role assigned to it as outlined in the prerequisites.
  2. When running the installer for the first time on an new AWS account the installer will fail due to your account lacking the proper access. An upgrade request will be sent to AWS and you should receive an “approved” email within the next 10-20 minutes. If you do not then contact AWS support to ensure your account is given the proper access. Once the installer fails be sure to run the: openshift-install destroy cluster command after navigating to the directory that your installer was running in. This will remove the old install files and ensure you don't have any conflicts when your account has been given the appropriate access. After the destroy command completes ensure that all files have been removed from the installation directory as I have noticed that the installer doesn’t always remove the terraform file and this will cause your next install to fail. Rerun the installer and your cluster should be created.
  3. When running the installer you may receive an EIP error message. This indicates that your account does not have the appropriate access and cannot create all of the IP addresses needed for the 3 master and 3 worker node install. This should only happen the first time you run the installer but I have noticed that it occurs during random installs and may indicate an issue on AWS’ side. After running the openshift-install destroy cluster command and rerunning the installer you should be able to create the cluster without issue.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 AWS. Any opinions in this post are expressly my own and do not reflect Red Hat's opinions on this installation process.