Merge pull request #53537 from stevsmit/install-microshift

Add microshift-install

_attributes/attributes-microshift.adoc

@@ -4,7 +4,12 @@
 :experimental:
 :imagesdir: images
 :OCP: OpenShift Container Platform
-:op-system-first: Red Hat Enterprise Linux for Edge (RHEL for Edge)
-:op-system: RHEL for Edge
+:ocp-version: 4.12
+:rhel-major: rhel-8
+:op-system-first: Red Hat Enterprise Linux (RHEL)
+:op-system: RHEL
+:op-system-ostree-first: Red Hat Enterprise Linux (RHEL) for Edge
+:op-system-ostree: RHEL for Edge
+:op-system-version: 8.7
 :op-system-ram: 2GB RAM
 :op-system-chip: two-core AMD64 1.5GHz processor

microshift_install/microshift-install-rhel-for-edge.adoc

@@ -1,8 +1,23 @@
 :_content-type: ASSEMBLY
 [id="microshift-install-rhel-for-edge"]
-= Installing MicroShift in a RHEL for Edge Image
+= Embedding MicroShift into a {op-system-ostree} image
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-install-rhel-for-edge
 toc::[]
 
-// The content of this file should be based on https://github.com/openshift/microshift/blob/main/docs/rhel4edge_iso.md
+You can embed MicroShift into a {op-system-ostree-first} {op-system-version} image.
+
+== Embedding MicroShift into a {op-system-ostree} image
+
+Use the content within this section to build a {op-system-ostree-first} {op-system-version} image containing MicroShift.
+
+[NOTE]
+====
+{op-system} 9.0 is currently unsupported for MicroShift deployments.
+====
+
+//include modules/prerequisites-for-installing-microshift.adoc
+
+include::modules/embedding-microshift-rpm-ostree-image.adoc[leveloffset=+2]
+
+include::modules/accessing-microshift.adoc[leveloffset=+2]

microshift_install/microshift-install-rpm.adoc

@@ -1,8 +1,26 @@
 :_content-type: ASSEMBLY
 [id="microshift-install-rpm"]
-= Installing MicroShift from RPM
+= Installing MicroShift from an RPM package
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-install-rpm
 toc::[]
 
-// The content of this file should be based on https://github.com/openshift/microshift/blob/main/docs/devenv_rhel8.md but without the steps for building from source.
+You can install MicroShift from an RPM package on a machine with {op-system-first} {op-system-version}. 
+
+To embed MicroShift in a {op-system-ostree} image, see xref:../microshift_install/microshift-install-rhel-for-edge.adoc#microshift-install-rhel-for-edge[Embedding MicroShift into a {op-system-ostree-first} image].
+
+include::modules/system-requirements-installing-microshift.adoc[leveloffset=+2]
+
+include::modules/preparing-for-installing-microshift-rpm.adoc[leveloffset=+2]
+
+include::modules/installing-microshift-rpm.adoc[leveloffset=+2]
+
+include::modules/starting-microshift-service.adoc[leveloffset=+2]
+
+include::modules/stopping-microshift-service.adoc[leveloffset=+2]
+
+include::modules/accessing-microshift.adoc[leveloffset=+1]
+
+include::modules/accessing-microshift-cluster-locally.adoc[leveloffset=+2]
+
+include::modules/accessing-microshift-cluster-remotely.adoc[leveloffset=+2]

modules/accessing-microshift-cluster-locally.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-install-rpm.adoc 
+
+:_content-type: PROCEDURE
+[id="accssing-microshift-cluster-locally_{context}"]
+= Accessing the MicroShift cluster locally
+
+Use the following procedure to access the MicroShift cluster locally. 
+
+.Prerequisites 
+
+* You have installed the `oc` CLI. 
+
+.Procedure 
+
+. Optional: Enter the following command to create a `~/.kube/` folder if your {op-system} machine does not have one: 
++
+[source,terminal]
+----
+$ mkdir -p ~/.kube/
+----
+
+. Copy the generated `kubeconfig` file to the `~/.kube/config` folder: 
++
+[source,terminal]
+----
+$ sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig > ~/.kube/config
+----
+
+. Verify that MicroShift is running by entering the following command:
++
+[source,terminal]
+----
+$ oc get all -A
+----

modules/accessing-microshift-cluster-remotely.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-install-rpm.adoc 
+
+:_content-type: CONCEPT
+[id="accessing-microshift-cluster-remotely_{context}"]
+= Accessing the MicroShift cluster remotely
+
+Use the following procedure to access the MicroShift cluster from a remote workstation. 
+
+.Prerequisites 
+
+* You have installed the `oc` CLI. 
+
+.Procedure 
+
+[NOTE]
+====
+The following procedure assumes that there are two users. The first user, `user@microshift`, is the user on the {product-title} host machine. `user@microshift` is responsible for setting up the `op-system` machine so that it can be accessed by a remote user on a separate workstation.  
+
+The second user, `user@workstation`, accesses the {op-system} machine remotely from their workstation. 
+====
+
+. As `user@microshift` on the MicroShift host, open the firewall port for Kubernetes API server (`6443/tcp`) on your {op-system} machine by entering the following command:
++
+[source,terminal]
+----
+[user@microshift]$ sudo firewall-cmd --permanent --zone=public --add-port=6443/tcp && sudo firewall-cmd --reload
+----
+
+. Optional: As `user@workstation`, enter the following command to create a `~/.kube/` folder if your {op-system} machine does not have one: 
++
+[source,terminal]
+----
+[user@workstation]$ mkdir -p ~/.kube/
+----
+
+. As `user@workstation`, set a variable for the hostname of your MicroShift host by entering the following command:
++
+[source,terminal]
+----
+[user@microshift]$ MICROSHIFT_MACHINE=<name or IP address of MicroShift machine>
+----
+
+. As `user@workstation`, copy the generated `kubeconfig` file from the {op-system} machine running MicroShift to your local machine by entering the following command: 
++
+[source,terminal]
+----
+[user@workstation]$ ssh <user>@$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig" > ~/.kube/config
+----
++
+[NOTE]
+====
+The `<user>` value is the name of the user that `user@workstation` uses to log in to the MicroShift host. 
+====
+
+. As `user@workstation`, replace the `server` field in your `kubeconfig` file with the name or IP address of your {op-system} machine running MicroShift by entering the following command:
++
+[source,terminal]
+----
+[user@workstation]$ sed -i "s|server: https://127.0.0.1:6443|server: https://$MICROSHIFT_MACHINE:6443|" ~/.kube/config
+----
+
+. As `user@workstation`, verify that MicroShift is running by entering the following command:
++
+[source,terminal]
+----
+[user@workstation]$ oc get all -A
+----

modules/accessing-microshift.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-install-rpm.adoc 
+
+:_content-type: CONCEPT
+[id="accssing-microshift-cluster_{context}"]
+= Accessing the MicroShift Cluster 
+
+Use the procedures in this section to access the MicroShift cluster locally (from the same machine running the MicroShift service) or remotely (from a different machine running the MicroShift service). 

modules/embedding-microshift-rpm-ostree-image.adoc

@@ -0,0 +1,16 @@
+= Prerequisites
+
+You have read the documentation on how to compose {op-system-ostree} images either on your own {op-system} {op-system-version} machine with Image Builder or on Red Hat Hosted Image Builder service:
+
+* https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/composing_installing_and_managing_rhel_for_edge_images[Composing, installing, and managing RHEL for Edge images]
+* https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/creating_customized_rhel_images_using_the_image_builder_service[Creating customized RHEL images using the Image Builder service]
+
+= Building a {op-system-ostree} image embedding MicroShift
+
+== Adding MicroShift repositories to Image Builder
+
+== Adding MicroShift to an Image Builder blueprint
+
+== Adding MicroShift dependencies to an installer kickstart file
+
+= Building a {op-system-ostree} image embedding workloads

modules/installing-microshift-rpm.adoc

@@ -0,0 +1,74 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-install-rpm.adoc 
+
+:_content-type: PROCEDURE
+[id="installing-microshift-from-rpm-package_{context}"]
+= Installing MicroShift from an RPM package 
+
+Use the following procedure to install MicroShift from an RPM package. 
+
+.Prerequisites 
+
+* The xref:../microshift_install/microshift-install-rpm.adoc#system-requirements-installing-microshift[system requirements for installing MicroShift] have been met. 
+* You have completed the steps at xref:../microshift_install/microshift-install-rpm.adoc#preparing-install-microshift-from-rpm-package_microshift-install-rpm[Preparing to install MicroShift from an RPM package].
+
+.Procedure
+
+. As a root user, enable the MicroShift repositories by entering the following command:
++
+[source,terminal]
+----
+$ sudo subscription-manager repos \
+    --enable rhocp-{ocp-version}-for-rhel-8-$(uname -i)-rpms \
+    --enable fast-datapath-for-{rhel-major}-$(uname -i)-rpms
+----
+
+. Install MicroShift by entering the following command:
++
+[source,terminal]
+----
+$ sudo dnf install -y microshift
+----
+
+. Download your installation link:https://console.redhat.com/openshift/install/pull-secret[pull secret] from the Red Hat Hybrid Cloud Console to a temporary folder, for example, `$HOME/openshift-pull-secret`. This pull secret allows you to authenticate with the container registries that serve the container images used by MicroShift.
+
+. Enter the following command to copy the pull secret to the `/etc/crio` folder of your {op-system} machine: 
++
+[source,terminal]
+----
+$ sudo cp $HOME/openshift-pull-secret /etc/crio/openshift-pull-secret
+----
+
+. Make the root user the owner of the `/etc/crio/openshift-pull-secret` file by entering the following command: 
++
+[source,terminal]
+----
+$ sudo chown root:root /etc/crio/openshift-pull-secret
+----
+
+. Make the `/etc/crio/openshift-pull-secret` file readable and writeable by the root user only by entering the following command:
++
+[source,terminal]
+----
+$ sudo chmod 600 /etc/crio/openshift-pull-secret
+----
+
+. If your {op-system} machine has a firewall enabled, you must configure a few mandatory firewall rules. For `firewalld`, enter the following commands: 
++
+[source,terminal]
+----
+$ sudo firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16
+----
++
+[source,terminal]
+----
+$ sudo firewall-cmd --permanent --zone=trusted --add-source=169.254.169.1
+----
++
+[source,terminal]
+----
+$ sudo firewall-cmd --reload
+----
+
+If the Volume Group (VG) that you have prepared for MicroShift used the default name `rhel`, no further configuration is necessary. If you have used a different name, or if you want to change more configuration settings, see xref:../microshift_configuring/microshift-using-config-tools.adoc#microshift-using-config-tools[Configuring MicroShift]. 

modules/preparing-for-installing-microshift-rpm.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-install-rpm.adoc 
+
+[id="preparing-install-microshift-from-rpm-package_{context}"]
+= Preparing to install MicroShift from an RPM package
+
+Before installing MicroShift from an RPM package, you must configure your {op-system} machine to have a logical volume manager (LVM) volume group (VG) with sufficient capacity for the persistent volumes (PVs) of your workload.
+
+MicroShift uses the logical volume manager storage (LVMS) Container Storage Interface (CSI) provider for storing PVs. LVMS relies on Linux's LVM to dynamically manage the backing storage for PVs. For this reason, your machine must have an LVM VG in which LVMS can create the LVM logical volumes (LVs) for your workload's PVs.  
+
+To configure an LVM VG that allows LVMS to create the LVM LVs for your workload's PVs, adjust your root volume's size during the installation of {op-system}. Adjusting your root volume's size provides free space for additional LVs created by LVMS at runtime. 
+
+.Prerequisites 
+
+* The xref:../microshift_install/microshift-install-rpm.adoc#system-requirements-installing-microshift[system requirements for installing MicroShift] have been met. 
+* You have root user access to your machine. 
+
+.Procedure 
+
+. In the graphical installer under *Storage Configuration*, select *Custom* -> *Done* to open the dialog for configuring partitions and volumes. 
+
+. Under *New Red Hat Enterprise Linux 8.x Installation*, select *Click here to create them automatically*. 
+
+. Select the root partition, */*, reduce *Desired Capacity* so that the VG has sufficient capacity for your PVs, and then click *Update Settings*. 
+
+. Complete your installation. 
++
+[NOTE]
+====
+For more options on partition configuration, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/performing_a_standard_rhel_8_installation/index#manual-partitioning_graphical-installation[Configuring Manual Partitioning]. 
+====
+
+. As a root user, verify the VG capacity available on your system by entering the following command: 
++
+[source,terminal]
+----
+$ sudo vgs
+----
++
+Example output:
++
+[source,terminal]
+----
+VG   #PV #LV #SN Attr   VSize    VFree
+rhel   1   2   0 wz--n- <127.00g 54.94g
+----
++
+[NOTE]
+====
+For more information about resizing your existing LVs to free up capacity in your VGs, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/configuring_and_managing_logical_volumes/index#managing-lvm-volume-groups_configuring-and-managing-logical-volumes[Managing LVM Volume Groups]
+====
+

modules/starting-microshift-service.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// microshift/microshift-install-rpm.adoc 
+
+:_content-type: PROCEDURE
+[id="starting-microshift_service_{context}"]
+= Starting the MicroShift service
+
+Use the following procedure to start the MicroShift service. 
+
+.Prerequisites 
+
+* You have installed MicroShift from an RPM package. 
+
+.Procedure 
+
+. As a root user, start the MicroShift service by entering the following command: 
++
+[source,terminal]
+----
+$ sudo systemctl start microshift
+----
+
+. Optional: To configure your {op-system} machine to start MicroShift when your machine starts, enter the following command:
++
+[source,terminal]
+----
+$ sudo systemctl enable microshift
+----
+
+. Optional: To disable MicroShift from automatically starting when your machine starts, enter the following command:
++
+[source,terminal]
+----
+$ sudo systemctl disable microshift
+----
++
+[NOTE]
+====
+The first time that the MicroShift service starts, it downloads and initializes MicroShift's container images. As a result, it can take several minutes for {product-title} to start the first time that the service is deployed. 
+Boot time is reduced for subsequent starts of the MicroShift service. 
+====