From c0921ddfd2fdd39bce33052ce39354b0c665d81e Mon Sep 17 00:00:00 2001 From: "Frank A. Zdarsky" Date: Mon, 5 Dec 2022 16:15:17 +0100 Subject: [PATCH] Add microshift-install Signed-off-by: Frank A. Zdarsky --- _attributes/attributes-microshift.adoc | 9 ++- .../microshift-install-rhel-for-edge.adoc | 19 ++++- .../microshift-install-rpm.adoc | 22 +++++- .../accessing-microshift-cluster-locally.adoc | 36 +++++++++ ...accessing-microshift-cluster-remotely.adoc | 69 +++++++++++++++++ modules/accessing-microshift.adoc | 9 +++ ...embedding-microshift-rpm-ostree-image.adoc | 16 ++++ modules/installing-microshift-rpm.adoc | 74 +++++++++++++++++++ ...eparing-for-installing-microshift-rpm.adoc | 53 +++++++++++++ modules/starting-microshift-service.adoc | 42 +++++++++++ modules/stopping-microshift-service.adoc | 37 ++++++++++ ...em-requirements-installing-microshift.adoc | 41 ++++++++++ 12 files changed, 421 insertions(+), 6 deletions(-) create mode 100644 modules/accessing-microshift-cluster-locally.adoc create mode 100644 modules/accessing-microshift-cluster-remotely.adoc create mode 100644 modules/accessing-microshift.adoc create mode 100644 modules/embedding-microshift-rpm-ostree-image.adoc create mode 100644 modules/installing-microshift-rpm.adoc create mode 100644 modules/preparing-for-installing-microshift-rpm.adoc create mode 100644 modules/starting-microshift-service.adoc create mode 100644 modules/stopping-microshift-service.adoc create mode 100644 modules/system-requirements-installing-microshift.adoc diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc index 824cdcd57d2e..b2eb2bdea367 100644 --- a/_attributes/attributes-microshift.adoc +++ b/_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 \ No newline at end of file diff --git a/microshift_install/microshift-install-rhel-for-edge.adoc b/microshift_install/microshift-install-rhel-for-edge.adoc index 57a17fb983d3..fe2e951b2b3f 100644 --- a/microshift_install/microshift-install-rhel-for-edge.adoc +++ b/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] diff --git a/microshift_install/microshift-install-rpm.adoc b/microshift_install/microshift-install-rpm.adoc index ae5ea56e6b88..8c33cbbca62b 100644 --- a/microshift_install/microshift-install-rpm.adoc +++ b/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] diff --git a/modules/accessing-microshift-cluster-locally.adoc b/modules/accessing-microshift-cluster-locally.adoc new file mode 100644 index 000000000000..3ba02ef6ce13 --- /dev/null +++ b/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 +---- \ No newline at end of file diff --git a/modules/accessing-microshift-cluster-remotely.adoc b/modules/accessing-microshift-cluster-remotely.adoc new file mode 100644 index 000000000000..4f8373419302 --- /dev/null +++ b/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= +---- + +. 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 @$MICROSHIFT_MACHINE "sudo cat /var/lib/microshift/resources/kubeadmin/kubeconfig" > ~/.kube/config +---- ++ +[NOTE] +==== +The `` 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 +---- diff --git a/modules/accessing-microshift.adoc b/modules/accessing-microshift.adoc new file mode 100644 index 000000000000..509b84428426 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/modules/embedding-microshift-rpm-ostree-image.adoc b/modules/embedding-microshift-rpm-ostree-image.adoc new file mode 100644 index 000000000000..b9fd8701720c --- /dev/null +++ b/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 diff --git a/modules/installing-microshift-rpm.adoc b/modules/installing-microshift-rpm.adoc new file mode 100644 index 000000000000..34c6e7ca2515 --- /dev/null +++ b/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]. \ No newline at end of file diff --git a/modules/preparing-for-installing-microshift-rpm.adoc b/modules/preparing-for-installing-microshift-rpm.adoc new file mode 100644 index 000000000000..d28edf5dc195 --- /dev/null +++ b/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] +==== + diff --git a/modules/starting-microshift-service.adoc b/modules/starting-microshift-service.adoc new file mode 100644 index 000000000000..24ed21c4cdf3 --- /dev/null +++ b/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. +==== \ No newline at end of file diff --git a/modules/stopping-microshift-service.adoc b/modules/stopping-microshift-service.adoc new file mode 100644 index 000000000000..61cacc31a57e --- /dev/null +++ b/modules/stopping-microshift-service.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// microshift/microshift-install-rpm.adoc + +:_content-type: PROCEDURE +[id="stopping-microshift-service_{context}"] += Stopping the MicroShift service + +Use the following procedure to stop the MicroShift service. + +.Prerequisites + +* The MicroShift service is running. + +.Procedure + +. Enter the following command to stop the MicroShift service: ++ +[source,terminal] +---- +$ sudo systemctl stop microshift +---- + +. Workloads deployed on MicroShift will continue running even after the MicroShift service has been stopped. Enter the following command to display running workloads: ++ +[source,terminal] +---- +$ sudo crictl ps -a +---- + +. Enter the following commands to stop the deployed workloads: ++ +[source,terminal] +---- +$ sudo systemctl stop kubepods.slice +---- + diff --git a/modules/system-requirements-installing-microshift.adoc b/modules/system-requirements-installing-microshift.adoc new file mode 100644 index 000000000000..c2e021eaa091 --- /dev/null +++ b/modules/system-requirements-installing-microshift.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// microshift/microshift-install-rpm.adoc + +[id="system-requirements-installing-microshift"] +== System requirements for installing MicroShift + +The following conditions must be met prior to installing MicroShift: + +* {op-system-first} {op-system-version} +* 2 CPU cores +* 2 GB of RAM +* 10 GB of storage +* You have an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. +* You have a subscription that includes MicroShift RPMs. +* You have a Logical Volume Manager (LVM) Volume Group (VG) with sufficient capacity for the Persistent Volumes (PVs) of your workload. + +.MicroShift supported architectures +[options="header"] +|=== +|Architecture |String + +|AMD64 +|`amd64` + +|Intel +|`x86_64` + +|ARM64 +|`aarch64` +|=== + + +.MicroShift supported operating systems +[options="header"] +|=== +|Operating system |String + +|{op-system-first} {op-system-version} +|`linux` +|=== \ No newline at end of file