TELCODOCS-1779/TELCODOCS-1782: Adding image-based installation and deployment workflow

_topic_maps/_topic_map.yml

@@ -3113,6 +3113,17 @@ Topics:
     File: cnf-image-based-upgrade-base
   - Name: Performing an image-based upgrade for single-node OpenShift clusters using GitOps ZTP
     File: ztp-image-based-upgrade
+- Name: Image-based installation for single-node OpenShift clusters
+  Dir: image-base-install
+  Topics:
+  - Name: Understanding an image-based installation for single-node OpenShift clusters
+    File: ibi-understanding-image-based-install
+  - Name: Preparing for an image-based installation for single-node OpenShift clusters
+    File: ibi-preparing-for-image-based-install
+  - Name: Performing an image-based installation for single-node OpenShift clusters
+    File: ibi-factory-image-based-install
+  - Name: Performing an image-based deployment for single-node OpenShift clusters
+    File: ibi-edge-image-based-install
 ---
 Name: Reference design specifications
 Dir: telco_ref_design_specs

edge_computing/image-base-install/_attributes

@@ -0,0 +1 @@
+../_attributes/

edge_computing/image-base-install/ibi-edge-image-based-install.adoc

@@ -0,0 +1,76 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ibi-image-based-install_{context}"]
+= About image-based deployments for {sno} clusters
+include::_attributes/common-attributes.adoc[]
+:context: ibi-edge-image-based-install
+
+toc::[]
+
+When a host preinstalled with {sno} using an image-based installation arrives at a remote site, a technician can easily reconfigure and deploy the host in a matter of minutes.
+
+To complete the deployment of a preinstalled host, you must first define site-specific configuration resources on the hub cluster for each host. These resources contain configuration information such as the properties of the bare-metal host, authentication details, and other deployment and networking information. 
+
+The Image Based Install (IBI) Operator creates a configuration ISO from these resources, and then boots the host with the configuration ISO attached. The host mounts the configuration ISO and runs the reconfiguration process. When the reconfiguration completes, the {sno} cluster is ready.
+
+[NOTE]
+====
+You must create distinct configuration resources for each bare-metal host. 
+====
+
+See the following high-level steps to deploy a preinstalled host:
+
+* Install the IBI Operator on the hub cluster.
+* Create site-specific configuration resources in the hub cluster for each host.
+* Apply these resources in the hub cluster. 
+* The IBI Operator creates a configuration ISO from these resources and boots the target host with the configuration ISO attached.
+* The host mounts the configuration ISO and runs the reconfiguration process. When the reconfiguration completes, the {sno} cluster is ready. 
+
+include::modules/ibi-install-ibi-operator.adoc[leveloffset=+1]
+
+== Cluster configuration resources for deploying a preinstalled host
+To complete a deployment for a preinstalled host at a remote site, you must configure the following site-specifc cluster configuration resources in the hub cluster for each bare-metal host.
+
+.Cluster configuration resources reference
+[cols="1,3", options="header"]
+|===
+
+| Resource | Description
+
+|`Namespace`
+|Namespace for the managed {sno} cluster.
+
+|`BareMetalHost`
+|Describes the physical host and its properties, such as the provisioning and hardware configuration.
+
+|`Secret` for the bare-metal host
+|Credentials for the host BMC.
+
+|`Secret` for the image registry
+|Credentials for the image registry. The secret for the image registry must be of type `kubernetes.io/dockerconfigjson`.
+
+|`ImageClusterInstall`
+|References the bare-metal host, deployment, and image set resources.
+
+|`ClusterImageSet`
+|Describes the release images to use for the cluster.
+
+|`ClusterDeployment`
+|Describes networking, authentication, and platform-specific settings.
+
+|`ManagedCluster`
+|Describes cluster details to enable {rh-rhacm-first} to register and manage.
+
+|`ConfigMap`
+|Describes networking setting, such as static networking and routing information. This is resource is optional.
+
+|===
+
+include::modules/ibi-create-config-iso.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* link:https://docs.openshift.com/container-platform/4.15/post_installation_configuration/bare-metal-configuration.html#about-the-baremetalhost-resource_post-install-bare-metal-configuration[About the BareMetalHost resource]
+
+* link:https://docs.openshift.com/container-platform/4.15/openshift_images/managing_images/using-image-pull-secrets.html[Using image pull secrets]
+

edge_computing/image-base-install/ibi-factory-image-based-install.adoc

@@ -0,0 +1,21 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ibi-image-based-install_{context}"]
+= Performing an image-based installation for {sno} clusters
+include::_attributes/common-attributes.adoc[]
+:context: ibi-factory-image-based-install
+
+toc::[]
+
+Use the `ib-cli` CLI tool to create a live installation ISO for preinstalling {sno} on bare-metal hosts. You can extract the `ib-cli` CLI tool from the {lcao}.
+
+The `ib-cli` CLI tool takes a seed image URL, and other inputs such as a URL for an instance of {op-system-first}, and creates a live installation ISO that references these installation artifacts. You can then restart the host using the live installation ISO to begin the preinstallation of the host. When the preinstallation is complete, the host is ready to ship to a remote site for the final site-specific configuration and deployment.
+
+The following are the high-level steps to preinstall a {sno} cluster to a host using an image-based installation:
+
+* Generate a seed image.
+* Create a live installation ISO using the `ib-cli` CLI tool.
+* Restart the host using the live installation ISO to preinstall the host.
+
+include::modules/ibi-ib-cli-reference.adoc[leveloffset=+1]
+
+include::modules/ibi-create-iso-for-seed-image.adoc[leveloffset=+1]

edge_computing/image-base-install/ibi-preparing-for-image-based-install.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ibi-preparing-for-image-based-install_{context}"]
+= Preparing for an image-based installation for {sno} clusters
+include::_attributes/common-attributes.adoc[]
+:context: ibi-understanding-image-based-install
+
+toc::[]
+To prepare for an image-based installation for {sno} clusters, you must complete the following tasks:
+
+* Create a seed image by using the {lcao}.
+* Verify that all software components meet the required versions. 
+
+== Installing the {lcao}
+
+Use the {lcao} to generate a seed image from a seed cluster. You can install the {lcao} using the {product-title} CLI or the web console.
+
+include::modules/ibi-install-lcao-console.adoc[leveloffset=+2]
+
+include::modules/ibi-install-lcao-cli.adoc[leveloffset=+2]
+
+include::modules/ibi-install-shared-partition.adoc[leveloffset=+1]
+
+include::modules/ibi-generate-seed-image.adoc[leveloffset=+1]

edge_computing/image-base-install/ibi-understanding-image-based-install.adoc

@@ -0,0 +1,114 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ibi-image-based-install_{context}"]
+= Understanding an image-based installation for {sno} clusters
+include::_attributes/common-attributes.adoc[]
+:context: ibi-understanding-image-based-install
+
+toc::[]
+
+Image-based installations streamline the deployment process for {sno} clusters, reducing both installation and deployment times. By leveraging an image-based approach, you can preinstall configured and validated instances of {sno} on target hosts. These prepared hosts can be rapidly reconfigured and deployed at the far edge of the network with minimal intervention.
+
+== Understanding an image-based installation and deployment for {sno} clusters
+
+Service providers continue to deploy their infrastructure at the far edge of the network. However, this presents challenges in terms of the cost, time, and expertise needed for installing and deploying {sno} clusters at remote sites on an enterprise scale.
+
+At the far edge of the network, challenges such as low bandwidth and high latency can increase installation times and complicate {sno} cluster deployments. These circumstances require experienced technicans to spend considerable time at remote sites, overseeing the installation and deployment of a {sno} cluster.
+
+An image-based installation and deployment overcomes the deficiencies of this workflow by separating the installation and deployment stages for {sno} clusters. Using an image-based installation, you can preinstall multiple hosts with {sno} at a central site, such as a service depot or a factory.
+You can also validate the base configuration for these hosts and leverage the image-based approach to perform reproducible factory installs at scale using a single container image.
+The preinstalled and validated hosts are shipped to a remote site where they can be rapidly reconfigured and deployed in a matter of minutes.
+
+.Overview of an image-based installation and deployment for {sno} clusters
+image::../images/711_OpenShift_IBI_Installation_high-level_0624.png[][Overview of an image-based installation and deployment]
+
+=== Image-based installation for {sno} clusters
+Using the {lcao}, you can generate an OCI container image that encapsulates an instance of a {sno} cluster. This image is derived from a dedicated cluster that you can configure with the target {product-title} version.  
+
+You can reference this image in a live installation ISO to consistently preinstall configured and validated instances of {sno} to multiple hosts. This approach enables the preparation of hosts at a central location, for example in a factory or service depot, before shipping the preinstalled hosts to a remote site for rapid reconfiguration and deployment. 
+
+The following is a high-level overview of the image-based installation process:
+
+* Generate an image from a {sno} cluster.
+* Use the {lcao} to embed the seed image URL, and other installation artifacts, in a live installation ISO.
+* Restart the host using the live installation ISO to preinstall the host. 
++
+During this process, the installation program installs {op-system-first} to the disk, pulls the image you generated, and precaches release container images to the disk.
+
+* When the installation completes, the host is ready to ship to the remote site for rapid reconfiguration and deployment.
+
+=== Imaged-based deployment for {sno} clusters
+{rh-rhacm-first} and the multicluster engine for Kubernetes operator (MCE) use a hub-and-spoke approach to manage and deploy {sno} clusters across multiple sites. Using this approach, the hub cluster serves as a central control plane that manages the spoke clusters, which are often remote {sno} clusters deployed at the far edge of the network.
+
+The hub cluster is responsible for defining and distributing configuration resources, policies, and updates to the spoke clusters. The configuration resources defined in the hub cluster ensure consistency and compliance across all spoke clusters from a single point of administration.
+
+An image-based installation and deployment combines the benefits of the hub-and-spoke approach with an image-based approach. Preinstalled hosts from an image-based installation require minimal configuration details to deploy a managed {sno} cluster at a remote site. This approach is especially beneficial for telecommunications providers and other service providers with extensive, distributed infrastructures, where manual installation would be time-consuming and costly.
+
+The following is a high-level overview of the image-based deployment process for hosts preinstalled with an imaged-based installation:
+
+* Define the site-specific configuration resources for the preinstalled host in the hub cluster.
+* Apply these resources in the hub cluster. This initiates the deployment process.
+* The IBI Operator creates a configuration ISO.
+* The IBI Operator boots the target preinstalled host with the configuration ISO attached.
+* The host mounts the configuration ISO and begins the reconfiguration process.
+* When the reconfiguration completes, the {sno} cluster is ready.
+
+As the host is already preinstalled using an image-based installation, a technician can reconfigure and deploy the host in a matter of minutes.
+
+== Image-based installation and deployment key components
+
+The following content describes key components in image-based installation and deployments.
+
+Seed image:: A seed image is an OCI container image generated from a dedicated cluster with the target {product-title} version. 
+
+Seed cluster:: A seed cluster is a dedicated {sno} cluster that you use to create a seed image and is deployed with the target {product-title} version.
+
+{lcao}:: In image-based installations, you can use the {lcao} to generate a seed image, embed the seed image URL in a live installation ISO, and reconfigure the host during a deployment at a remote site.
+
+`ib-cli` CLI tool:: Extract the binary for the `ib-cli` CLI tool from the {lcao}. Use the `ib-cli` CLI tool to create a live installation ISO for preinstalling {sno} on bare-metal hosts.
+
+Image Based Install (IBI) Operator:: The IBI Operator creates a configuration ISO from the site-specific resources you define in the hub cluster, attaches the configuration ISO to the remote host using a bare-metal provisioning service.
+
+include::modules/ibi-image-based-install-cluster-guide.adoc[leveloffset=+1]
+
+
+include::modules/ibi-validated-software-versions.adoc[leveloffset=+1]
+
+////
+Possibly repeating myself with the below content, so I've commented it out for now. Perhaps I could add more detail to the above sections instead.
+
+== Image-based installation with zero touch configuration end-to-end workflow
+
+The following steps details the high-level workflow from installation at a core location to final configuration at a remote site. 
+
+.Generate a seed image
+Image-based installations require a seed image generated from a seed cluster with the target {product-title} version.
+
+The seed image provides a reproducible version of a {sno} cluster that you can use to preinstall {sno} to hosts. You can adjust the seed image by adjusting the seed cluster. You can use this approach to validate the instance of {sno} based on a desired cluster configuration before creating the seed image.
+
+.Embed the seed image URL in an installation ISO 
+To boot the host with the seed image, you must create a live installation ISO. The {lcao} features the `ib-cli` CLI tool binary, which you can use to create the live installation ISO. `ib-cli` takes the seed image URL and other inputs and creates a live ISO featuring {op-system} that you can attach to a specific disk on the host.
+
+.Boot the ISO to target hosts
+Using you're preferred method, you can attach the ISO to the target hosts. When you boot the host from the installation ISO, the {lcao} completes the following tasks:
+
+* Installs {op-system} to disk
+* An extra partition is created to store precached release images
+* Grows the specified partition to occupy all available space on the disk
+* Mounts the filesystem to the partition to enable access to {op-system}
+* Pulls the seed image and creates a state root with its content
+* Optional: precaches the release images on the disk
+
+The host is then ready for deployment at the remote site.
+
+.Deploy the cluster at a remote site with zero touch configuration
+Create configuration resources on the hub cluster containing the site-specific cluster configuration details for the host. These include the `BareMetalHost`, `ImageClusterInstall`, and `ClusterDeployment` resources. 
+
+The IBI Operator creates a configuration ISO from these configuration resources. The Operator then boots the host with the configuration ISO attached. The node mounts the configuration ISO and runs the reconfiguration process. When the reconfiguration completes, the {sno} cluster is ready. As the host is already preinstalled using an image-based installation, a technician can deploy the host using ZTC in a matter of minutes.
+////
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.7/html/about/welcome-to-red-hat-advanced-cluster-management-for-kubernetes#multicluster-architecture[Multicluster architecture]
+
+* link:https://docs.openshift.com/container-platform/4.16/edge_computing/image_based_upgrade/cnf-understanding-image-based-upgrade.html[Understanding the image-based upgrade for single-node OpenShift clusters]

edge_computing/image-base-install/images

@@ -0,0 +1 @@
+../images/

edge_computing/image-base-install/modules

@@ -0,0 +1 @@
+../modules/

edge_computing/image-base-install/snippets

@@ -0,0 +1 @@
+../snippets/