OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Install OpenShift Container Platform

Overview

This guide introduces you to the basic concepts of OpenShift Container Platform, and helps you install a basic application. This guide is not suitable for deploying or installing a production environment of OpenShift Container Platform.

Prerequisites

To install OpenShift Container Platform, you will need:

  • At least two physical or virtual RHEL 7+ machines, with fully qualified domain names (either real world or within a network) and password-less SSH access to each other. This guide uses master.openshift.example.com and node.openshift.example.com. These machines must be able to ping each other using these domain names. If you use IBM POWER servers, all servers in your cluster must be IBM POWER servers.

  • A valid Red Hat subscription.

  • Wildcard DNS resolution that resolves your domain to the IP of the node. So, an entry like the following in your DNS server:

    master.openshift.example.com. 300 IN A <master_ip>
node.openshift.example.com. 300 IN A <node_ip>
*.apps.openshift.example.com. 300 IN A <node_ip>
Why the apps in your domain name for the wildcard entry?

When using OpenShift Container Platform to deploy applications, an internal router needs to proxy incoming requests to the corresponding application pod. By using apps as part of the application domains, the application traffic is accurately marked to the right pod.

You can use anything other than apps.

*.cloudapps.openshift.example.com. 300 IN A <node_ip>

Once these are configured, use the following steps to set up a two-machine OpenShift Container Platform install.

Attach OpenShift Container Platform Subscription

  1. As root on the target machines (both master and node), use subscription-manager to register the systems with Red Hat.

    # subscription-manager register

  2. Pull the latest subscription data from Red Hat Subscription Manager (RHSM):

    # subscription-manager refresh

  3. List the available subscriptions.

    # subscription-manager list --available

  4. Find the pool ID that provides OpenShift Container Platform subscription and attach it.

    # subscription-manager attach --pool=<pool_id>

  5. Replace the string <pool_id> with the pool ID of the pool that provides OpenShift Container Platform. The pool ID is a long alphanumeric string.

These RHEL systems are now authorized to install OpenShift Container Platform. Now you need to tell the systems from where to get OpenShift Container Platform.

Set Up Repositories

On both master and node, use subscription-manager to enable the repositories that are necessary in order to install OpenShift Container Platform. You may have already enabled the first two repositories in this example.

  • For cloud installations and on-premise installations on x86_64 servers, run the following command:

    # subscription-manager repos --enable="rhel-7-server-rpms" \
    --enable="rhel-7-server-extras-rpms" \
    --enable="rhel-7-server-ose-3.11-rpms" \
    --enable="rhel-7-server-ansible-2.9-rpms"

  • For on-premise installations on IBM POWER8 servers, run the following command:

    # subscription-manager repos \
    --enable="rhel-7-for-power-le-rpms" \
    --enable="rhel-7-for-power-le-extras-rpms" \
    --enable="rhel-7-for-power-le-optional-rpms" \
    --enable="rhel-7-server-ansible-2.9-for-power-le-rpms" \
    --enable="rhel-7-server-for-power-le-rhscl-rpms" \
    --enable="rhel-7-for-power-le-ose-3.11-rpms"

  • For on-premise installations on IBM POWER9 servers, run the following command:

    # subscription-manager repos \
    --enable="rhel-7-for-power-9-rpms" \
    --enable="rhel-7-for-power-9-extras-rpms" \
    --enable="rhel-7-for-power-9-optional-rpms" \
    --enable="rhel-7-server-ansible-2.9-for-power-9-rpms" \
    --enable="rhel-7-server-for-power-9-rhscl-rpms" \
    --enable="rhel-7-for-power-9-ose-3.11-rpms"

This command tells your RHEL system that the tools required to install OpenShift Container Platform will be available from these repositories. Now we need the OpenShift Container Platform installer that is based on Ansible.

Older versions of OpenShift Container Platform 3.11 supported only Ansible 2.6. The most recent versions of the playbooks now support Ansible 2.9, which is the preferred version to use.

Install the OpenShift Container Platform Package

The installer for OpenShift Container Platform is provided by the openshift-ansible package. Install it using yum on the master after running yum update.

# yum -y install wget git net-tools bind-utils iptables-services bridge-utils bash-completion kexec-tools sos psacct
# yum -y update
# reboot
# yum -y install openshift-ansible

Now install a container engine:

  • To install CRI-O:

    # yum -y install cri-o

  • To install Docker:

    # yum -y install docker

Set up Password-less SSH Access

Before running the installer on the master, set up password-less SSH access as this is required by the installer to gain access to the machines. On the master, run the following command.

$ ssh-keygen

Follow the prompts and just hit enter when asked for pass phrase.

An easy way to distribute your SSH keys is by using a bash loop:

$ for host in master.openshift.example.com \
    node.openshift.example.com; \
    do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; \
    done

Run the Installation Playbooks

  1. See Example Inventory Files and select the example that most closely matches your desired cluster configuration.

    Running Ansible playbooks with the --tags or --check options is not supported by Red Hat.

Further example host files are available as references in the /usr/share/doc/openshift-ansible-docs-3.11.<version>/docs/example-inventories/ directory (replacing <version> with your latest installed version of the openshift-ansible-docs package, which will update over time as the openshift-ansible parent package is upgraded). See Configuring Your Inventory File for full documentation on available inventory variables.

  1. Edit the example inventory to use your host names, and then save it to a file. The default location is /etc/ansible/hosts.

  2. Change to the playbook directory and run the prerequisites.yml playbook using your inventory file:

    $ cd /usr/share/ansible/openshift-ansible
    $ ansible-playbook -i <inventory_file> playbooks/prerequisites.yml

  3. Change to the playbook directory and run the deploy_cluster.yml playbook using your inventory file:

    $ cd /usr/share/ansible/openshift-ansible
    $ ansible-playbook -i <inventory_file> playbooks/deploy_cluster.yml

After a successful install, but before you add a new project, you must set up basic authentication, user access, and routes.

Interact with OpenShift Container Platform

OpenShift Container Platform provides two command line utilities to interact with it.

  • oc: for normal project and application management

  • oc adm: for administrative tasks

    When running oc adm commands, you should run them only from the first master listed in the Ansible host inventory file, by default /etc/ansible/hosts.

Use oc --help and oc adm --help to view all available options.

In addition, you can use the web console to manage projects and applications. The web console is available at https://<master_fqdn>:8443/console. In the next section, you will see how to create user accounts for accessing the console.

You can interact with your OpenShift Container Platform instance from a remote system as well, using these command line utilities. Bundled as the OpenShift CLI, you can download these utilities for Windows, Mac, or Linux environments in the CLI Reference section.

Understand Roles and Authentication

By default, when installed for the first time, there are no roles or user accounts created in OpenShift Container Platform, so you need to create them. You have the option to either create new roles or define a policy that allows anyone to log in (to start you off).

Before you do anything else, log in at least one time with the default system:admin user. On the master, run the following command:

$ oc login -u system:admin
All commands from now on should be executed on the master, unless otherwise indicated.

By logging in at least one time with this account, you will create the system:admin user’s configuration file, which will allow you to log in subsequently.

There is no password for this system account.

Run the following command to verify that OpenShift Container Platform was installed and started successfully. You will get a listing of the master and node, in the Ready status.

$ oc get nodes

To continue configuring your basic OpenShift Container Platform environment, follow the steps outlined in Configure OpenShift Container Platform.