Chapter 1. Planning your installation

You install OpenShift Container Platform by running a series of Ansible playbooks. As you prepare to install your cluster, you create an inventory file that represents your environment and OpenShift Container Platform cluster configuration. While familiarity with Ansible might make this process easier, it is not required.

You can read more about Ansible and its basic usage in the official documentation.

1.1. Initial planning

Before you install your production OpenShift Container Platform cluster, you need answers to the following questions:

  • Do your on-premise servers use IBM POWER or x86_64 processors? You can install OpenShift Container Platform on servers that use either type of processor. If you use POWER servers, review the Limitations and Considerations for Installations on IBM POWER.
  • How many pods are required in your cluster? The Sizing Considerations section provides limits for nodes and pods so you can calculate how large your environment needs to be.
  • How many hosts do you require in the cluster? The Environment Scenarios section provides multiple examples of Single Master and Multiple Master configurations.
  • Does you need a high availability cluster? High availability configurations improve fault tolerance. In this situation, you might use the Multiple Masters Using Native HA example to set up your environment.
  • Is cluster monitoring required? The monitoring stack requires additional system resources. Note that the monitoring stack is installed by default. See the cluster monitoring documentation for more information.
  • Do you want to use Red Hat Enterprise Linux (RHEL) or RHEL Atomic Host as the operating system for your cluster nodes? If you install OpenShift Container Platform on RHEL, you use an RPM-based installation. On RHEL Atomic Host, you use a system container. Both installation types provide a working OpenShift Container Platform environment.
  • Which identity provider do you use for authentication? If you already use a supported identity provider, configure OpenShift Container Platform to use that identity provider during installation.
  • Is my installation supported if I integrate it with other technologies? See the OpenShift Container Platform Tested Integrations for a list of tested integrations.

1.1.1. Limitations and Considerations for Installations on IBM POWER

As of version 3.10.45, you can install OpenShift Container Platform on IBM POWER servers.

  • Your cluster must use only Power nodes. Because of the way that images are tagged, OpenShift Container Platform cannot differentiate between x86 images and Power images.
  • Image streams and templates are not installed by default or updated when you upgrade. You can manually install and update the image streams.
  • You can install only on on-premise Power servers. You cannot install OpenShift Container Platform on nodes in any cloud provider.
  • Not all storage providers are supported. You can use only the following storage providers:

    • GlusterFS
    • NFS
    • Local storage

1.2. Sizing considerations

Determine how many nodes and pods you require for your OpenShift Container Platform cluster. Cluster scalability correlates to the number of pods in a cluster environment. That number influences the other numbers in your setup. See Cluster Limits for the latest limits for objects in OpenShift Container Platform.

1.3. Environment scenarios

Use these environment scenarios to help plan your OpenShift Container Platform cluster based on your sizing needs.

Note

Moving from a single master cluster to multiple masters after installation is not supported.

In all environments, if your etcd hosts are co-located with master hosts, etcd runs as a static pod on the host. If your etcd hosts are not co-located with master hosts, they run etcd as standalone processes.

Note

If you use RHEL Atomic Host, you can configure etcd on only master hosts.

1.3.1. Single master and node on one system

You can install OpenShift Container Platform on a single system for only a development environment. You cannot use an all-in-one environment as a production environment.

1.3.2. Single master and multiple nodes

The following table describes an example environment for a single master (with etcd installed on the same host) and two nodes:

Host NameInfrastructure Component to Install

master.example.com

Master, etcd, and node

node1.example.com

Node

node2.example.com

1.3.3. Multiple masters using native HA

The following describes an example environment for three masters, one HAProxy load balancer, and two nodes using the native HA method. etcd runs as static pods on the master nodes:

Host NameInfrastructure Component to Install

master1.example.com

Master (clustered using native HA) and node and clustered etcd

master2.example.com

master3.example.com

lb.example.com

HAProxy to load balance API master endpoints

node1.example.com

Node

node2.example.com

1.3.4. Multiple Masters Using Native HA with External Clustered etcd

The following describes an example environment for three masters, one HAProxy load balancer, three external clustered etcd hosts, and two nodes using the native HA method:

Host NameInfrastructure Component to Install

master1.example.com

Master (clustered using native HA) and node

master2.example.com

master3.example.com

lb.example.com

HAProxy to load balance API master endpoints

etcd1.example.com

Clustered etcd

etcd2.example.com

etcd3.example.com

node1.example.com

Node

node2.example.com

1.3.5. Stand-alone registry

You can also install OpenShift Container Platform to act as a stand-alone registry using the OpenShift Container Platform’s integrated registry. See Installing a Stand-alone Registry for details on this scenario.

1.4. Installation types for supported operating systems

Starting in OpenShift Container Platform 3.10, if you use RHEL as the underlying OS for a host, the RPM method is used to install OpenShift Container Platform components on that host. If you use RHEL Atomic Host, the system container method is used on that host. Either installation type provides the same functionality for the cluster, but the operating system you use determines how you manage services and host updates.

An RPM installation installs all services through package management and configures services to run in the same user space, while a system container installation installs services using system container images and runs separate services in individual containers.

When using RPMs on RHEL, all services are installed and updated by package management from an outside source. These packages modify a host’s existing configuration in the same user space. With system container installations on RHEL Atomic Host, each component of OpenShift Container Platform is shipped as a container, in a self-contained package, that uses the host’s kernel to run. Updated, newer containers replace any existing ones on your host.

The following table and sections outline further differences between the installation types:

Table 1.1. Differences between installation types

 Red Hat Enterprise LinuxRHEL Atomic Host

Installation Type

RPM-based

System container

Delivery Mechanism

RPM packages using yum

System container images using docker

Service Management

systemd

docker and systemd units

1.4.1. Required images for system containers

The system container installation type makes use of the following images:

  • openshift3/ose-node

By default, all of the above images are pulled from the Red Hat Registry at registry.redhat.io.

If you need to use a private registry to pull these images during the installation, you can specify the registry information ahead of time. Set the following Ansible variables in your inventory file, as required:

oreg_url='<registry_hostname>/openshift3/ose-${component}:${version}'
openshift_docker_insecure_registries=<registry_hostname>
openshift_docker_blocked_registries=<registry_hostname>
Note

You can also set the openshift_docker_insecure_registries variable to the IP address of the host. 0.0.0.0/0 is not a valid setting.

The default component inherits the image prefix and version from the oreg_url value.

The configuration of additional, insecure, and blocked container registries occurs at the beginning of the installation process to ensure that these settings are applied before attempting to pull any of the required images.

1.4.2. systemd service names

The installation process creates relevant systemd units which can be used to start, stop, and poll services using normal systemctl commands. For system container installations, these unit names match those of an RPM installation.

1.4.3. File path locations

All OpenShift Container Platform configuration files are placed in the same locations during containerized installation as RPM based installations and will survive os-tree upgrades.

However, the default image stream and template files are installed at /etc/origin/examples/ for Atomic Host installations rather than the standard /usr/share/openshift/examples/ because that directory is read-only on RHEL Atomic Host.

1.4.4. Storage requirements

RHEL Atomic Host installations normally have a very small root file system. However, the etcd, master, and node containers persist data in the /var/lib/ directory. Ensure that you have enough space on the root file system before installing OpenShift Container Platform. See the System Requirements section for details.