openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity
Files
d6e76567cbb2bfca377a6dfa4295efa4e2336a3f
openshift-docs/modules/installation-process.adoc
Avital Pinnick 1691ef1f6c HCIDOCS- 104: Update Assisted Installer links 
Signed-off-by: Avital Pinnick <apinnick@redhat.com>
2024-01-03 09:05:33 +00:00

126 lines
12 KiB
Plaintext
Raw Blame History

// Module included in the following assemblies:
//
// * installing/index.adoc
// * architecture/architecture-installation.adoc
:_mod-docs-content-type: CONCEPT
[id="installation-process_{context}"]
= Installation process
Except for the {ai-full}, when you install an {product-title} cluster, you must download the installation program from
ifndef::openshift-origin[]
the appropriate link:https://console.redhat.com/openshift/create[*Cluster Type*] page on the {cluster-manager} {hybrid-console-second}. This console 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.
endif::[]
ifdef::openshift-origin[]
https://github.com/openshift/okd/releases.
endif::[]
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. Consider the following installation use cases:
* To deploy a cluster with the {ai-full}, you must configure the cluster settings by using the link:https://access.redhat.com/documentation/en-us/assisted_installer_for_openshift_container_platform[{ai-full}]. There is no installation program to download and configure. After you finish setting the cluster configuration, you download a discovery ISO and then boot cluster machines with that image. You can install clusters with the {ai-full} on Nutanix, vSphere, and bare metal with full integration, and other platforms without integration. If you install on bare metal, you must provide all of the cluster infrastructure and resources, including the networking, load balancing, storage, and individual cluster machines.
* To deploy clusters with the Agent-based Installer, you can download the link:https://console.redhat.com/openshift/install/metal/agent-based[Agent-based Installer] first. You can then configure the cluster and generate a discovery image. You boot cluster machines with the discovery image, which installs an agent that communicates with the installation program and handles the provisioning for you instead of you interacting with the installation program or setting up a provisioner machine yourself. You must provide all of the cluster infrastructure and resources, including the networking, load balancing, storage, and individual cluster machines. This approach is ideal for disconnected environments.
* For clusters with installer-provisioned infrastructure, you delegate the infrastructure bootstrapping and provisioning to the installation program instead of doing it yourself. The installation program creates all of the networking, machines, and operating systems that are required to support the cluster, except if you install on bare metal. If you install on bare metal, you must provide all of the cluster infrastructure and resources, including the bootstrap machine, networking, load balancing, storage, and individual cluster machines.
* 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.
For the installation program, the program uses 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]
====
You can 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 the 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 the {ai-full}
Installation with the link:https://access.redhat.com/documentation/en-us/assisted_installer_for_openshift_container_platform[{ai-full}] involves creating a cluster configuration interactively by using the web-based user interface or the RESTful API. The {ai-full} user interface prompts you for required values and provides reasonable default values for the remaining parameters, unless you change them in the user interface or with the API. The {ai-full} generates a discovery image, which you download and use to boot the cluster machines. The image installs {op-system} and an agent, and the agent handles the provisioning for you. You can install {product-title} with the {ai-full} and full integration on Nutanix, vSphere, and bare metal. Additionally, you can install {product-title} with the {ai-full} on other platforms without integration.
{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.
If possible, use the {ai-full} feature to avoid having to download and configure the Agent-based Installer.
[discrete]
== The installation process with Agent-based infrastructure
Agent-based installation is similar to using the {ai-full}, except that you must initially download and install the link:https://console.redhat.com/openshift/install/metal/agent-based[Agent-based Installer]. An Agent-based installation is useful when you want the convenience of the {ai-full}, but you need to install a cluster in a disconnected environment.
If possible, use the Agent-based installation feature to avoid having to create a provisioner machine with a bootstrap VM, and then provision and maintain the cluster infrastructure.
[discrete]
== The installation process with installer-provisioned infrastructure
The default installation type uses installer-provisioned infrastructure. 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. The following list details some of these self-managed resources:
* The underlying infrastructure for 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 {op-system-base} compute machines to your cluster.
[discrete]
== Installation process details
When a cluster is provisioned, each machine in the cluster requires information about the cluster. {product-title} uses a temporary bootstrap machine during initial configuration to provide the required information to the permanent control plane. The temporary bootstrap machine boots by using an Ignition config file that describes how to create the cluster. The bootstrap machine creates the control plane machines that make up the control plane. The control plane machines then create the compute machines, which are also known as worker machines. The following figure illustrates this process:
ifndef::openshift-origin[]
.Creating the bootstrap, control plane, and compute machines
image::create-nodes.png[Creating bootstrap, control plane, and compute machines]
endif::openshift-origin[]
ifdef::openshift-origin[]
.Creating the bootstrap, control plane, and compute machines
image::150_OpenShift_VMware_on_AWS_1021_installer_FCOS.png[Creating bootstrap, control plane, and compute machines]
endif::openshift-origin[]
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, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information.
* Consider using Ignition config files within 12 hours after they are generated, because the 24-hour certificate rotates from 16 to 22 hours after the cluster is installed. By using the Ignition config files within 12 hours, you can avoid installation failure if the certificate update runs during installation.
====
Bootstrapping a cluster involves the following steps:
. The bootstrap machine boots and starts hosting the remote resources required for the control plane machines to boot. If you provision the infrastructure, this step requires manual intervention.
. The bootstrap machine starts a single-node etcd cluster and a temporary Kubernetes control plane.
. The control plane machines fetch the remote resources from the bootstrap machine and finish booting. If you provision the infrastructure, this step requires manual intervention.
. The temporary control plane schedules the production control plane to the production control plane machines.
. The Cluster Version Operator (CVO) comes online and installs the etcd Operator. The etcd Operator scales up etcd on all control plane nodes.
. 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. If you provision the infrastructure, this step requires manual intervention.
. The control plane sets up the compute nodes.
. The control plane installs additional services in the form of a set of Operators.
The result of this bootstrapping process is a running {product-title} cluster. The cluster then downloads and configures remaining components needed for the day-to-day operations, including the creation of compute machines in supported environments.
View Git Blame Copy Permalink