Introduction to Installing Clusters

To install clusters in production environments, OKD provides an installation method (the installer) implemented using Ansible playbooks. Familiarity with Ansible is assumed, however this installation guide will provide you with the information to help you create an inventory file that represents your environment and desired OKD cluster configuration, then run the installation using the Ansible CLI tooling.

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

Initial Planning

When installing your OKD cluster for a production environment, several factors influence installation. Consider the following questions as you read through this guide:

  • Do you install on-premises or in public/private clouds? The Installation Methods section provides more information about the cloud providers options available.

  • 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.

  • Is high availability for the cluster required? High availability is recommended for fault tolerance. In this situation, you might aim to use the Multiple Masters Using Native HA example as a basis for your environment.

  • Which installation type do you want to use: RPM or system containers? Both installations provide a working OKD environment, but you might have a preference for a particular method of installing, managing, and updating your services.

  • Which identity provider do you use for authentication? If you already use a supported identity provider, it is a best practice to configure OKD to use that identity provider during installation.

On-premises Versus Cloud Providers

OKD can be installed on-premises or hosted on public or private clouds. Ansible playbooks can help you with automating the provisioning and installation processes. For information, see Running Installation Playbooks.

Sizing Considerations

Determine how many nodes and pods you require for your OKD 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 OKD.

Environment Scenarios

This section outlines different examples of scenarios for your OKD environment. Use these scenarios as a basis for planning your own OKD cluster, based on your sizing needs.

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

For information on updating labels, see Updating Labels on Nodes.

Single Master and Node on One System

OKD can be installed on a single system for a development environment only. An all-in-one environment is not considered a production environment.

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 Name Infrastructure Component to Install

Master, etcd, and node


Single Master, Multiple etcd, and Multiple Nodes

The following table describes an example environment for a single master, three etcd hosts, and two nodes:

Host Name Infrastructure Component to Install

Master and node



Multiple Masters Using Native HA with Co-located Clustered etcd

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

Host Name Infrastructure Component to Install

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

HAProxy to load balance API master endpoints


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 Name Infrastructure Component to Install

Master (clustered using native HA) and node

HAProxy to load balance API master endpoints

Clustered etcd


Stand-alone Registry

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

Installation Types

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

Starting in OKD 3.10, if you use Red Hat Enterprise Linux (RHEL) Server as the underlying OS for a host, the RPM method is used to install OKD 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 choice lies in the operating system and therefore how you will manage services and host updates.

When using RPMs, all services are installed and updated by package management from an outside source. These modify a host’s existing configuration within the same user space. Alternatively, with system container installs, each component of OKD is shipped as a container (in a self-contained package) and leverages the host’s kernel to start and run. Any updated, newer containers replace any existing ones on your host.

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

Table 1. Differences Between Installation Types
RPM-based Installations System Container Installations

Delivery Mechanism

RPM packages using yum

System container images using docker

Service Management


docker and systemd units

Operating System

Red Hat Enterprise Linux (RHEL)

RHEL Atomic Host

Required Images for System Containers

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

  • openshift/origin

  • openshift/node (node + openshift-sdn + openvswitch RPM for client tools)

  • openshift/openvswitch (CentOS 7 + openvswitch RPM, runs ovsdb and ovsctl processes)


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:


You can also set the openshift_docker_insecure_registries variable to the IP address of the host. 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 Docker 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.

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.

The etcd package is slated to be removed from RHEL Atomic Host in the future.

File Path Locations

All OKD 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.

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 OKD. See the System Requirements section for details.