openshift-docs/modules/installation-overview.adoc

// Module included in the following assemblies:
//
// * architecture/architecture-installation.adoc

[id="installation-overview_{context}"]
= {product-title} installation overview

The {product-title} installation program offers you flexibility. You can use the installation
program to deploy a cluster on infrastructure that the installation program
provisions and the cluster maintains or deploy a cluster on infrastructure
that you prepare and maintain.

[IMPORTANT]
====
{product-title} requires all machines, including the computer that you run the
installation process on, to have direct internet access to pull images
for platform containers and provide telemetry data to Red Hat.

You cannot specify a proxy server for {product-title}.
====

These two basic types of {product-title} clusters are frequently called
installer-provisioned infrastructure clusters and user-provisioned
infrastructure clusters.

Both types of clusters have the following characteristics:

* Highly available infrastructure with no single points of failure is available
by default
* Administrators maintain control over what updates are applied and when

You use the same installation program to deploy both types of clusters. The main
assets generated by the installation program are the Ignition config files for the
bootstrap, master, and worker machines. With these three configurations and correctly
configured infrastructure, you can start an {product-title} cluster.

The {product-title} installation program uses a set of targets and dependencies to manage
cluster installation. The installation program has a set of targets that it must achieve,
and each target has a set of dependencies. Because each target is only
concerned with its own dependencies, the installation program can act to achieve
multiple targets in parallel. The ultimate target is a running cluster. By
meeting dependencies instead of running commands, the installation program is
able to recognize and use existing components instead of running the commands to
create them again.

The following diagram shows a subset of the installation targets and dependencies:

.{product-title} installation targets and dependencies
image::targets-and-dependencies.png[{product-title} installation targets and dependencies]

After installation, each cluster machine uses {op-system-first} as the operating
system. {op-system} is the immutable container host version of
Red Hat Enterprise Linux (RHEL) and features a RHEL kernel with SELinux enabled
by default. It includes the `kubelet`, which is the Kubernetes node agent, and
the CRI-O container runtime, which is optimized for Kubernetes.

Every control plane machine in an {product-title} {product-version} cluster must
use {op-system}, which includes a critical first-boot provisioning tool called
Ignition. This tool enables the cluster to configure the machines.
Operating system updates are delivered as an Atomic OSTree repository that is
embedded in a container image that is rolled out across the cluster by an
Operator. Actual operating system changes are made in-place on each machine as
an atomic operation by using rpm-ostree. Together, these technologies enable
{product-title} to manage the operating system like it manages any other
application on the cluster, via in-place upgrades that keep the entire platform
up-to-date. These in-place updates can reduce the burden on operations teams.

If you use {op-system} as the operating system for all cluster machines, the
cluster manages all aspects of its components and machines, including the
operating system. Because of this, only the installation program and the
Machine Config Operator can change machines. The installation program uses
Ignition config files to set the exact state of each machine, and the Machine
Config Operator completes more changes to the machines, such as the application
of new certificates or keys, after installation.

[id="available-platforms_{context}"]
== Available platforms

In {product-title} {product-version}, you can install a cluster that uses
installer-provisioned infrastructure on only Amazon Web Services (AWS).

In {product-title} {product-version}, you can install a cluster that uses
user-provisioned infrastructure on the following platforms:

* AWS
* VMware vSphere
* Bare metal

The link:https://access.redhat.com/articles/4128421[OpenShift Container Platform 4.x Tested Integrations]
page contains details about integration testing for different platforms.

[id="installation-process_{context}"]
== Installation process

When you install an {product-title} cluster, you download the
installation program from the
link:https://cloud.redhat.com/openshift/install[OpenShift Infrastructure Providers]
page. This site manages:

* REST API for accounts
* Registry tokens, which are the pull secrets that you use to obtain the required
components
* Cluster registration, which associates the cluster identity to your Red Hat
account to facilitate the gathering of usage metrics

In {product-title} {product-version}, the installation program is a Go binary file that performs a
series of file transformations on a set of assets. The way you interact with the
installation program differs depending on your installation type.

* For clusters with installer-provisioned infrastructure, you delegate the
infrastructure bootstrapping and provisioning to the installation program
instead of doing it yourself. The installion program creates all of the
networking, machines, and operating systems that are required to support the
cluster.

* If you provision and manage the infrastructure for your cluster, you must
provide all of the cluster infrastructure and resources, including the
bootstrap machine, networking, load balancing, storage, and individual cluster
machines.

You use three sets of files during installation: an installation configuration
file that is named `install-config.yaml`, Kubernetes manifests, and Ignition
config files for your machine types.

[IMPORTANT]
====
It is possible to modify Kubernetes and the Ignition config files that control
the underlying {op-system} operating system during installation. However,
no validation is available to confirm the suitability of any modifications that
you make to these objects. If you modify these objects, you might render
your cluster non-functional. Because of this risk, modifying Kubernetes and
Ignition config files is not supported unless you are following documented procedures
or are instructed to do so by Red Hat support.
====

The installation configuration file is transformed into Kubernetes manifests, and
then the manifests are wrapped into Ignition config files. The installation program uses
these Ignition config files to create the cluster.

The installation configuration files are all pruned when you run the installation program,
so be sure to back up all configuration files that you want to use again.

[IMPORTANT]
====
You cannot modify the parameters that you set during installation, but you can
modify many cluster attributes after installation.
====

[discrete]
=== The installation process with installer-provisioned infrastructure

[IMPORTANT]
====
In version {product-version}, you can install a {product-title} cluster that
uses installer-provisioned infrastructure on only
Amazon Web Services (AWS).
====

The default installation type uses installer-provisioned infrastructure
on AWS. By default, the installation
program acts as an installation wizard, prompting you
for values that it cannot determine on its own and providing reasonable default
values for the remaining parameters. You can also customize the installation
process to support advanced infrastructure scenarios. The installation program provisions
the underlying infrastructure for the cluster.

You can install either a standard cluster or a customized cluster. With a
standard cluster, you provide minimum details that are required to install the
cluster. With a customized cluster, you can specify more details about the
platform, such as the number of machines that the control plane uses, the type
of virtual machine that the cluster deploys, or the CIDR range for the
Kubernetes service network.

If possible, use this feature to avoid
having to provision and maintain the cluster infrastructure. In all other
environments, you use the installation program to generate the assets that you require to
provision your cluster infrastructure.

With installer-provisioned infrastructure clusters, {product-title} manages all aspects of
the cluster, including the operating system itself. Each machine boots with a
configuration that references resources hosted in the cluster that it joins.
This configuration allows the cluster to manage itself as updates are applied.

[discrete]
=== The installation process with user-provisioned infrastructure

You can also install {product-title} on infrastructure that you provide. You use the
installation program to generate the assets that you require to provision the
cluster infrastructure, create the cluster infrastructure, and then deploy
the cluster to the infrastructure that you provided.

If you do not use infrastructure that the installation program provisioned, you must manage
and maintain the cluster resources yourself, including:

* The control plane and compute machines that make up the cluster
* Load balancers
* Cluster networking, including the DNS records and required subnets
* Storage for the cluster infrastructure and applications

If your cluster uses user-provisioned infrastructure, you have the option of
adding RHEL worker machines to your cluster.

[discrete]
=== Installation process details

Because each machine in the cluster requires information about the cluster when
it is provisioned, {product-title} uses a temporary _bootstrap_ machine during
initial configuration to provide the required information to the permanent
control plane. It boots by using an Ignition config file that describes how to
create the cluster. The boostrap machine creates the master machines that
make up the control plane. The control plane machines then create the compute,
or worker, machines. The following figure illustrates this process:

.Creating the bootstrap, master, and worker machines
image::create-nodes.png[Creating bootstrap, master, and worker machines]

After the cluster machines initialize, the bootstrap machine is destroyed.
All clusters use the bootstrap process to initialize the
cluster, but if you provision the infrastructure for your cluster, you must
complete many of the steps manually.

[IMPORTANT]
====
The Ignition config files that the installation program generates contain
certificates that expire after 24 hours. You must complete your cluster
installation and keep the cluster running for 24 hours in a non-degraded state
to ensure that the first certificate rotation has finished.
====

Bootstrapping a cluster involves the following steps:

. The bootstrap machine boots and starts hosting the remote resources required
for the master machines to boot. (Requires manual intervention if you provision
  the infrastructure)
. The master machines fetch the remote resources from the bootstrap machine
and finish booting. (Requires manual intervention if you provision the
  infrastructure)
. The master machines use the bootstrap machine to form an etcd cluster.
. The bootstrap machine starts a temporary Kubernetes control plane using the
new etcd cluster.
. The temporary control plane schedules the production control plane to the
master machines.
. The temporary control plane shuts down and passes control to the production
control plane.
. The bootstrap machine injects {product-title} components into the production
control plane.
. The installation program shuts down the bootstrap machine.
(Requires manual intervention if you provision the infrastructure)
. The control plane sets up the worker nodes.
. The control plane installs additional services in the form of a set
of Operators.

The result of this bootstrapping process is a fully running {product-title}
cluster. The cluster then downloads and configures remaining components
needed for the day-to-day operation, including the creation of worker machines
in supported environments.

[discrete]
=== Installation process details

[discrete]
== Installation scope

The scope of the {product-title} installation program is intentionally narrow.
It is designed for simplicity and ensured success. You can complete many
more configuration tasks after installation completes.