diff --git a/microshift_install_get_ready/microshift-install-get-ready.adoc b/microshift_install_get_ready/microshift-install-get-ready.adoc index 58bcc2d20454..3694b23d36de 100644 --- a/microshift_install_get_ready/microshift-install-get-ready.adoc +++ b/microshift_install_get_ready/microshift-install-get-ready.adoc @@ -1,27 +1,29 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-install-get-ready"] -= Getting ready to install {microshift-short} += Getting ready to install MicroShift include::_attributes/attributes-microshift.adoc[] :context: microshift-install-get-ready toc::[] -Plan for your {microshift-short} installation and complete host configuration steps as needed. +To use {op-system-bundle} to compute at the edge, plan your {op-system-base-full} installation type and your {microshift-short} configuration. include::modules/microshift-install-system-requirements.adoc[leveloffset=+1] -[id="embed-offline-rhde-compatibility-table"] -== Compatibility table +include::modules/microshift-install-rhde-compat-table.adoc[leveloffset=+1] -Plan to pair a supported version of {op-system-ostree} with the {microshift-short} version you are using as described in the following compatibility table: +include::modules/microshift-install-tools-intro.adoc[leveloffset=+1] -include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1] +include::modules/microshift-install-rhel-types.adoc[leveloffset=+1] + +include::modules/microshift-install-rhel-tools-concepts.adoc[leveloffset=+1] + +include::modules/microshift-install-rhde-steps.adoc[leveloffset=+1] [id="additional-resources_microshift-install-get-ready"] [role="_additional-resources"] == Additional resources * xref:../microshift_cli_ref/microshift-oc-cli-install.adoc#microshift-oc-cli-install[Getting started with the OpenShift CLI] -* xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-install-rpm[Installing from an RPM package] +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/installing_with_an_rpm_package/index[Installing from an RPM package] * xref:../microshift_networking/microshift-networking-settings.adoc#microshift-networking[Understanding networking settings] -* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/managing_storage_devices/encrypting-block-devices-using-luks_managing-storage-devices#luks-disk-encryption_encrypting-block-devices-using-luks[LUKS disk encryption] diff --git a/modules/microshift-install-rhde-compat-table.adoc b/modules/microshift-install-rhde-compat-table.adoc new file mode 100644 index 000000000000..748d6847d1ce --- /dev/null +++ b/modules/microshift-install-rhde-compat-table.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * microshift_install_get_ready/microshift-install-get-ready.adoc + +:_mod-docs-content-type: REFERENCE +[id="microshift-install-rhde-compat-table_{context}"] += Compatibility table + +You must pair a supported version of {op-system-base-full} with the {microshift-short} version you are using as described in the following compatibility table. + +include::snippets/microshift-rhde-compatibility-table-snip.adoc[leveloffset=+1] diff --git a/modules/microshift-install-rhde-steps.adoc b/modules/microshift-install-rhde-steps.adoc new file mode 100644 index 000000000000..f230a49cc5e3 --- /dev/null +++ b/modules/microshift-install-rhde-steps.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * microshift_install_get_ready/microshift-install-get-ready.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-install-rhde-steps_{context}"] += {op-system-bundle} installation steps + +For most installation types, you must also take the following steps: + +* Download the pull secret from the Red{nbsp}Hat Hybrid Cloud Console using the following link: + +** link:https://console.redhat.com/openshift/install/pull-secret[Pull secret] + +* Be ready to configure {microshift-short} by adding parameters and values to the {microshift-short} YAML configuration file. For more information, see the following link: + +** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/configuring/using-the-microshift-configuration-file[Using the {microshift-short} configuration file] + +* Decide whether you need to configure storage for the application and tasks you are using in your {microshift-short} node, or disable the {microshift-short} storage plugin completely. + +* For more information about creating volume groups and persistent volumes on {op-system-base}, see the following link: + +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/overview-of-logical-volume-management_configuring-and-managing-logical-volumes[Overview of logical volume management] + +* Configure networking settings according to the access needs you plan for your {microshift-short} node and applications. Consider whether you want to use single or dual-stack networks, configure a firewall, or configure routes. diff --git a/modules/microshift-install-rhel-tools-concepts.adoc b/modules/microshift-install-rhel-tools-concepts.adoc new file mode 100644 index 000000000000..e293494b8bea --- /dev/null +++ b/modules/microshift-install-rhel-tools-concepts.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * microshift_install_get_ready/microshift-install-get-ready.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-install-rhel-tools-concepts_{context}"] += {op-system-base} installation tools and concepts + +Familiarize yourself with the following {op-system-base} tools and concepts: + +* A Kickstart file, which contains the configuration and instructions used during the installation of your specific operating system. For more information, see the following link: + +** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/using_rhel_kickstarts/microshift-rhel-kickstarts[Using Kickstart files for installing {microshift-short} in {op-system-base}] + +* {op-system-base} image builder is a tool for creating deployment-ready customized system images. {op-system-base} image builder uses a blueprint that you create to make the ISO. {op-system-base} image builder is best installed on a {op-system-base} VM and is built with the `composer-cli` tool. To set up these tools and review the workflow, see the following {op-system-base} documentation links: + +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-system-images-with-composer-command-line-interface_composing-a-customized-rhel-system-image#composer-command-line-interface_creating-system-images-with-composer-command-line-interface[Introducing the RHEL image builder command-line interface] +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/installing-composer_composing-a-customized-rhel-system-image[Installing image builder] +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-system-images-with-composer-command-line-interface_composing-a-customized-rhel-system-image#creating-a-system-image-with-composer-in-the-command-line-interface_creating-system-images-with-composer-command-line-interface[Creating a system image with RHEL image builder in the command-line interface] + +* A blueprint file directs {op-system-base} image builder to the items to include in the ISO. An image blueprint provides a persistent definition of image customizations. You can create multiple builds from a single blueprint. You can also edit an existing blueprint to build a new ISO as requirements change. See the following link for more information: + +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-system-images-with-composer-command-line-interface_composing-a-customized-rhel-system-image#creating-a-composer-blueprint-with-command-line-interface_creating-system-images-with-composer-command-line-interface[Creating a blueprint by using the command-line interface] + +* An ISO, which is the bootable operating system on which {microshift-short} runs. See the following links for more information: + +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-a-boot-iso-installer-image-with-image-builder_composing-a-customized-rhel-system-image#creating-a-boot-iso-installer-image-with-image-builder-in-the-command-line-interface_creating-a-boot-iso-installer-image-with-image-builder[Creating a boot ISO installer image using the RHEL image builder CLI] +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/creating-a-boot-iso-installer-image-with-image-builder_composing-a-customized-rhel-system-image#installing-the-iso-to-a-bare-metal-system_creating-a-boot-iso-installer-image-with-image-builder[Installing a bootable ISO to a media and booting it] +** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/latest/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree[Embedding in a {op-system-ostree} image using image builder] diff --git a/modules/microshift-install-rhel-types.adoc b/modules/microshift-install-rhel-types.adoc new file mode 100644 index 000000000000..59cc677a8e1b --- /dev/null +++ b/modules/microshift-install-rhel-types.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * microshift_install_get_ready/microshift-install-get-ready.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-install-rhel-types_{context}"] += {op-system-base} installation types + +Choose the best {op-system-base-full} installation type based on where you want to run your cluster and what your applications need to do. For the best results, apply the following principles: + +* For every installation target, you must configure both the operating system and {microshift-short}. +* Consider your application storage needs, networking for cluster or application access, and your authentication and security requirements. +* Understand the differences between the {op-system-base} installation types, including the support scope of each, and the tools used. + +[id="microshift-get-ready-install-rpm_{context}"] +== Using RPMs, or package-based installation + +This simple installation type uses a basic command to install {microshift-short} on an existing {op-system-base} machine. Basic CLI tools are required for this installation type. + +[id="microshift-get-ready-install-rhel-image-based_{context}"] +== {op-system-base} image-based installations + +Image-based installation types involve creating an `rpm-ostree`-based, immutable version of {op-system-base} that is optimized for edge deployment. + +* {op-system-ostree} can be deployed to the edge in production environments. You can use this installation type where network connections are present, restricted, or completely offline, depending on the local environment. + +When choosing an image-based installation, consider whether the installation target is intended to be in an offline or networked state, where you plan to build system images, and how you plan to load your {op-system-bundle}. Use the following scenarios as general guidance: + +* If you build a fully self-contained {op-system-ostree} ISO outside a disconnected environment, and then install the ISO locally on your edge devices, you likely do not need an RPM repository or a mirror registry. +* If you build an ISO outside a disconnected environment that does not include the container images, but consists of only the RPMs, you need a mirror registry inside your disconnected environment. You use your mirror registry to pull container images. +* If you build images inside a disconnected environment, or use package-based installations, you need both a mirror registry and a local RPM mirror repository. You can use either the {op-system-base} reposync utility or Red{nbsp}Hat Satellite for advanced use cases. See the following links for more information: + +** link:https://access.redhat.com/solutions/7019225[Creating a local mirror of the latest update for {op-system-base} without using Satellite Server] +** link:https://www.redhat.com/en/technologies/management/satellite[Red{nbsp}Hat Satellite] diff --git a/modules/microshift-install-system-requirements.adoc b/modules/microshift-install-system-requirements.adoc index 559b0b6a0fb2..639794db1f8c 100644 --- a/modules/microshift-install-system-requirements.adoc +++ b/modules/microshift-install-system-requirements.adoc @@ -6,26 +6,24 @@ [id="microshift-install-system-requirements_{context}"] = System requirements for installing {microshift-short} +These requirements are the minimum system requirements for {microshift-short} and {op-system-base}. Add the system requirements for the workload you plan to run. + +For example, if an IoT gateway solution requires 4 GB of RAM, your system needs to have at least 2 GB for {op-system-base} and {microshift-short}, plus 4 GB for the workloads. Thus, this example deployment requires 6 GB of RAM in total. + +Allow for extra capacity for future needs if you are deploying physical devices in remote locations. If you are uncertain of the RAM required, use the maximum RAM capacity that the device can support. + The following conditions must be met before installing {microshift-short}: -* A compatible version of {op-system-base-full}. +* A compatible version of {op-system-base-full}. For more information, see the following link: + +** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/getting_ready_to_install_microshift/microshift-install-get-ready#get-ready-install-rhde-compatibility-table_microshift-install-get-ready[Compatibility table] + * AArch64 or x86_64 system architecture. * 2 CPU cores. * 2 GB RAM. Installing from the network (UEFI HTTPs or PXE boot) requires 3 GB RAM for {op-system-base}. * 10 GB of storage. * You have an active {microshift-short} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. -* If your workload requires Persistent Volumes (PVs), you have a Logical Volume Manager (LVM) Volume Group (VG) with sufficient free capacity for the workloads. - -[IMPORTANT] -==== -These requirements are the minimum system requirements for {microshift-short} and {op-system-base-full}. Add the system requirements for the workload you plan to run. - -For example, if an IoT gateway solution requires 4 GB of RAM, your system needs to have at least 2 GB for {op-system-base-full} and {microshift-short}, plus 4 GB for the workloads. In total, 6 GB of RAM is required. - -Allow for extra capacity for future needs if you are deploying physical devices in remote locations. If you are uncertain of the RAM required and if the budget permits, use the maximum RAM capacity that the device can support. -==== +* If your workload requires Persistent Volumes (PVs), you have a Logical Volume Manager (LVM) Volume Group (VG) with enough free capacity for the workloads. +* You configure secure access to the system to be able to manage it. For more information, see the following link: -[IMPORTANT] -==== -Ensure you configure secure access to the system to be able to manage it accordingly. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/assembly_using-secure-communications-between-two-systems-with-openssh_securing-networks[Using secure communications between two systems with OpenSSH]. -==== \ No newline at end of file +** link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/assembly_using-secure-communications-between-two-systems-with-openssh_securing-networks[Using secure communications between two systems with OpenSSH] diff --git a/modules/microshift-install-tools-intro.adoc b/modules/microshift-install-tools-intro.adoc new file mode 100644 index 000000000000..6ca05a72d6b2 --- /dev/null +++ b/modules/microshift-install-tools-intro.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * microshift_install_get_ready/microshift-install-get-ready.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-install-tools-intro_{context}"] += {microshift-short} installation tools + +To use {microshift-short}, you must already have or plan to install a {op-system-base-full} type, such as on bare metal, or as a virtual machine (VM) that you provision. Although each use case has different details, each installation of {op-system-bundle} uses {op-system-base} tools and the {oc-first}. + +You can use RPMs to install {microshift-short} on an existing {op-system-base} machine. You do not need other tools unless you are also installing an image-based {op-system-base} system or VM at the same time.