From 27beefb8008e4394de01e6e7c3d7adddeb282267 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Tue, 14 Oct 2025 13:33:08 -0400 Subject: [PATCH] OSDOCS-15650: dita fixes install optional RPMS MicroShift --- _attributes/attributes-microshift.adoc | 2 + .../microshift-install-optional-rpms.adoc | 43 ++++++------------- .../microshift-observability-service.adoc | 9 +--- modules/microshift-install-multus-rpm.adoc | 12 +++--- modules/microshift-install-rpms-gitops.adoc | 13 +++--- modules/microshift-install-rpms-olm.adoc | 5 ++- modules/microshift-otel-config-examples.adoc | 1 + modules/microshift-otel-config-large.adoc | 1 + modules/microshift-otel-config-medium.adoc | 3 +- modules/microshift-otel-config-small.adoc | 1 + modules/microshift-otel-config.adoc | 11 +++-- modules/microshift-otel-install.adoc | 4 +- modules/microshift-otel-verify.adoc | 2 +- modules/microshift-rhoai-install.adoc | 26 +++++------ 14 files changed, 57 insertions(+), 76 deletions(-) diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc index e2c12eddf8cd..82522879c92b 100644 --- a/_attributes/attributes-microshift.adoc +++ b/_attributes/attributes-microshift.adoc @@ -13,6 +13,8 @@ :microshift-short: MicroShift //gitops version for 4.17-4.19 :gitops-ver: 1.16 +:gitops-title: Red{nbsp}Hat OpenShift GitOps +:gitops-shortname: GitOps :product-registry: OpenShift image registry :product-version: 4.20 :rhel-major: rhel-9 diff --git a/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc b/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc index cd0f31c929a3..bde50b92f4d1 100644 --- a/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc +++ b/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc @@ -1,49 +1,30 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-install-optional-rpms"] = Installing optional RPM packages + include::_attributes/attributes-microshift.adoc[] :context: microshift-install-optional-rpm toc::[] -You can install optional RPM packages with {microshift-short} to provide additional node and application services. +[role="_abstract"] +When you install {microshift-short}, you can add optional RPM packages to help manage your deployments. Examples of optional RPMs include those designed to expand your network, add and manage Operators, and manage applications. Use the following procedures to add the packages that you need. -[id="microshift-install-rpm-add-ons"] -== Installing optional packages +include::modules/microshift-install-rpms-gitops.adoc[leveloffset=+1] -When you install {microshift-short}, optional RPM packages can be added. Examples of optional RPMs include those designed to expand your network, add and manage operators, and manage applications. Use the following procedures to add the packages that you need. +include::modules/microshift-install-multus-rpm.adoc[leveloffset=+1] -include::modules/microshift-install-rpms-gitops.adoc[leveloffset=+2] +include::modules/microshift-install-rpms-olm.adoc[leveloffset=+1] -//additional resources for installing GitOps -[role="_additional-resources"] -.Additional resources -* xref:../microshift_running_apps/microshift-gitops.adoc#microshift-gitops[Automating application management with the GitOps controller] +include::modules/microshift-otel-install.adoc[leveloffset=+1] -include::modules/microshift-install-multus-rpm.adoc[leveloffset=+2] +include::modules/microshift-rhoai-install.adoc[leveloffset=+1] -//additional resources for installing Multus +[id="additional-resources_microshift-install-optional-rpms"] [role="_additional-resources"] -.Additional resources +== Additional resources +* xref:../microshift_running_apps/microshift-gitops.adoc#microshift-gitops[Automating application management with the {gitops-shortname} controller] * xref:../microshift_networking/microshift_multiple_networks/microshift-cni-multus.adoc#microshift-cni-multus[About using multiple networks] - -include::modules/microshift-install-rpms-olm.adoc[leveloffset=+2] - -//additional resources for installing OLM -[role="_additional-resources"] -.Additional resources * xref:../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] - -include::modules/microshift-otel-install.adoc[leveloffset=+2] - -//additional resources for installing Observability -[role="_additional-resources"] -.Additional resources * xref:../microshift_running_apps/microshift-observability-service.adoc#microshift-observability-service[Using {microshift-short} Observability] - -include::modules/microshift-rhoai-install.adoc[leveloffset=+2] - -//additional resources for installing RHOAI -[role="_additional-resources"] -.Additional resources -* xref:../microshift_ai/microshift-rhoai.adoc#microshift-rh-openshift-ai[Using {rhoai} with {microshift-short}] \ No newline at end of file +* xref:../microshift_ai/microshift-rhoai.adoc#microshift-rh-openshift-ai[Using {rhoai} with {microshift-short}] diff --git a/microshift_running_apps/microshift-observability-service.adoc b/microshift_running_apps/microshift-observability-service.adoc index 17c5b76492f5..b41553ad4991 100644 --- a/microshift_running_apps/microshift-observability-service.adoc +++ b/microshift_running_apps/microshift-observability-service.adoc @@ -1,17 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-observability-service"] -= Using {microshift-short} Observability += Using MicroShift Observability include::_attributes/attributes-microshift.adoc[] :context: microshift-observability-service toc::[] +[role="_abstract"] {microshift-short} Observability collects and transmits system data for monitoring and analysis. The data includes performance and usage metrics, and error reporting. include::modules/microshift-otel-install.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources - * xref:../microshift_install_rpm_opt/microshift-install-optional-rpms.adoc#microshift-install-optional-rpms[Installing optional RPM packages] include::modules/microshift-otel-config.adoc[leveloffset=+1] @@ -26,6 +24,3 @@ include::modules/microshift-otel-config-medium.adoc[leveloffset=+1] include::modules/microshift-otel-config-large.adoc[leveloffset=+1] include::modules/microshift-otel-verify.adoc[leveloffset=+1] - - - diff --git a/modules/microshift-install-multus-rpm.adoc b/modules/microshift-install-multus-rpm.adoc index 12158eee439d..20a50392bffc 100644 --- a/modules/microshift-install-multus-rpm.adoc +++ b/modules/microshift-install-multus-rpm.adoc @@ -6,6 +6,7 @@ [id="microshift-installing-multus_{context}"] = Installing the multiple networks plugin +[role="_abstract"] You can install the {microshift-short} Multus Container Network Interface (CNI) plugin alongside a new {microshift-short} installation. If you want to attach additional networks to a pod for high-performance network configurations, install the `microshift-multus` RPM package. [IMPORTANT] @@ -29,10 +30,7 @@ If you create your custom resources (CRs) while you are completing your installa .Next steps -. Continue with your new {microshift-short} installation, including any add-ons. - -. Create the custom resources (CRs) needed for your {microshift-short} Multus CNI plugin. - -. Configure other networking CNIs as needed. - -. After you have finished installing all of the RPMs that you want to include, start the {microshift-short} service. The {microshift-short} Multus CNI plugin is automatically deployed. +* Continue with your new {microshift-short} installation, including any add-ons. +* Create the custom resources (CRs) needed for your {microshift-short} Multus CNI plugin. +* Configure other networking CNIs as needed. +* After you have finished installing all of the RPMs that you want to include, start the {microshift-short} service. The {microshift-short} Multus CNI plugin is automatically deployed. diff --git a/modules/microshift-install-rpms-gitops.adoc b/modules/microshift-install-rpms-gitops.adoc index dd80b611ed57..92a66d5b07f2 100644 --- a/modules/microshift-install-rpms-gitops.adoc +++ b/modules/microshift-install-rpms-gitops.adoc @@ -1,16 +1,17 @@ // Module included in the following assemblies: // -// microshift/microshift-install-rpm.adoc +// microshift/microshift-install-optional-rpms.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-installing-rpms-for-gitops_{context}"] -= Installing the GitOps Argo CD manifests from an RPM package += Installing the {gitops-shortname} Argo CD manifests from an RPM package -You can use a lightweight version of OpenShift GitOps with {microshift-short} to help manage your applications by installing the `microshift-gitops` RPM package. The `microshift-gitops` RPM package includes the necessary manifests to run core Argo CD. +[role="_abstract"] +You can use a lightweight version of {gitops-title} with {microshift-short} to help manage your applications by installing the `microshift-gitops` RPM package. You can consistently configure and deploy Kubernetes-based infrastructure and applications across node and development lifecycles by using the declarative {gitops-shortname} engine. The `microshift-gitops` RPM package includes the necessary manifests to run core Argo CD. [IMPORTANT] ==== -The Argo CD CLI is not available on {microshift-short}. This process installs basic GitOps functions. +The Argo CD CLI is not available on {microshift-short}. This process installs basic {gitops-shortname} functions. ==== .Prerequisites @@ -20,14 +21,14 @@ The Argo CD CLI is not available on {microshift-short}. This process installs ba .Procedure -. Enable the GitOps repository with the subscription manager by running the following command: +. Enable the {gitops-shortname} repository with the subscription manager by running the following command: + [source,terminal,subs="attributes+"] ---- $ sudo subscription-manager repos --enable=gitops-{gitops-ver}-for-{rhel-major}-$(uname -m)-rpms ---- -. Install the {microshift-short} GitOps package by running the following command: +. Install the {microshift-short} {gitops-shortname} package by running the following command: + [source,terminal] ---- diff --git a/modules/microshift-install-rpms-olm.adoc b/modules/microshift-install-rpms-olm.adoc index a2151c54b6d8..21a0fe3884f1 100644 --- a/modules/microshift-install-rpms-olm.adoc +++ b/modules/microshift-install-rpms-olm.adoc @@ -6,7 +6,8 @@ [id="microshift-installing-with-olm-from-rpm-package_{context}"] = Installing the Operator Lifecycle Manager (OLM) from an RPM package -When you install {microshift-short}, the Operator Lifecycle Manager (OLM) package is not installed by default. You can install the OLM on your {microshift-short} instance by using an RPM package. +[role="_abstract"] +When you install {microshift-short}, the Operator Lifecycle Manager (OLM) package is not installed by default. You can install the OLM on your {microshift-short} instance by using an RPM package. OLM helps you install, update, and manage the lifecycle of Kubernetes native applications (Operators) and their associated services running in each {microshift-short} node. .Procedure @@ -22,4 +23,4 @@ $ sudo dnf install microshift-olm [source,terminal] ---- $ sudo systemctl restart microshift ----- \ No newline at end of file +---- diff --git a/modules/microshift-otel-config-examples.adoc b/modules/microshift-otel-config-examples.adoc index 729b7511c60b..7e3fcf00e0ec 100644 --- a/modules/microshift-otel-config-examples.adoc +++ b/modules/microshift-otel-config-examples.adoc @@ -6,6 +6,7 @@ [id="microshift-otel-config-examples_{context}"] = Selecting a {microshift-short} Observability configuration +[role="_abstract"] The amount and complexity of the data depends on predefined configurations. These configurations determine the number of data sources and the amount of collected data that is transmitted. These configurations are defined as small, medium, and large (default). The `opentelemetry-collector.yaml` file includes specific parameters that are used to collect data for monitoring the system resources. All warnings for node events are included in the collected data. {microshift-short} Observability collects and transmits data for the following resources: diff --git a/modules/microshift-otel-config-large.adoc b/modules/microshift-otel-config-large.adoc index 517332a0154e..b56c89e81a3e 100644 --- a/modules/microshift-otel-config-large.adoc +++ b/modules/microshift-otel-config-large.adoc @@ -6,6 +6,7 @@ [id="microshift-otel-config-large_{context}"] = Selecting a large configuration +[role="_abstract"] You can configure {microshift-short} Observability to collect the maximum amount of performance and resource information, from the maximum number of sources, by updating the YAML file. .Procedure diff --git a/modules/microshift-otel-config-medium.adoc b/modules/microshift-otel-config-medium.adoc index 64e36a87e200..b26080d1d0dd 100644 --- a/modules/microshift-otel-config-medium.adoc +++ b/modules/microshift-otel-config-medium.adoc @@ -6,6 +6,7 @@ [id="microshift-otel-config-medium_{context}"] = Selecting a medium configuration +[role="_abstract"] You can configure {microshift-short} Observability to collect performance and resource information from various sources by updating the YAML file. .Procedure @@ -71,7 +72,7 @@ service: otlp: protocol: http/protobuf endpoint: http://${env:OTEL_BACKEND}:4318 <2> ----- +---- <1> Replace the variable `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. Any unreachable endpoint is reported in the `microshift-observability` service logs. <2> Replace the variable `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. Any unreachable endpoint is reported in the `microshift-observability` service logs. diff --git a/modules/microshift-otel-config-small.adoc b/modules/microshift-otel-config-small.adoc index cafa0f2e248f..6ee80003a885 100644 --- a/modules/microshift-otel-config-small.adoc +++ b/modules/microshift-otel-config-small.adoc @@ -6,6 +6,7 @@ [id="microshift-otel-config-small_{context}"] = Selecting a small configuration +[role="_abstract"] You can configure {microshift-short} Observability to collect the smallest amount of performance and resource information from various sources by updating the YAML file. .Procedure diff --git a/modules/microshift-otel-config.adoc b/modules/microshift-otel-config.adoc index 16c851037189..bbd735e34440 100644 --- a/modules/microshift-otel-config.adoc +++ b/modules/microshift-otel-config.adoc @@ -6,9 +6,8 @@ [id="microshift-otel-config_{context}"] = Configuring {microshift-short} Observability -You must configure {microshift-short} Observability after it is installed by specifying a valid endpoint. If an endpoint is not specified, {microshift-short} Observability does not start. - -You can specify any OpenTelemetry Protocol (OTLP)-compatible endpoint for each configuration before starting {microshift-short}. +[role="_abstract"] +You must configure {microshift-short} Observability after it is installed by specifying a valid endpoint. If an endpoint is not specified, {microshift-short} Observability does not start. You can specify any OpenTelemetry Protocol (OTLP)-compatible endpoint for each configuration before starting {microshift-short}. .Procedure @@ -36,10 +35,10 @@ service: otlp: protocol: http/protobuf endpoint: http://${env:OTEL_BACKEND}:4318 <2> -# ... ----- +# ... +---- <1> Replace `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. An unreachable endpoint is reported in the {microshift-short} service logs. -<2> Replace `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. An unreachable endpoint is reported in the {microshift-short} service logs. +<2> Replace `${env:OTEL_BACKEND}` with the IP address or hostname of the remote back end. This IP address resolves to the local node's hostname. An unreachable endpoint is reported in the {microshift-short} service logs. . Each time that you update the `opentelemetry-collector.yaml` file, you must restart {microshift-short} Observability to apply the updates. + diff --git a/modules/microshift-otel-install.adoc b/modules/microshift-otel-install.adoc index a7818ad23aae..348fc91a89a2 100644 --- a/modules/microshift-otel-install.adoc +++ b/modules/microshift-otel-install.adoc @@ -6,7 +6,8 @@ [id="microshift-otel-install_{context}"] = Installing and enabling {microshift-short} Observability -You can install {microshift-short} Observability at any time, including during the initial {microshift-short} installation. +[role="_abstract"] +You can install {microshift-short} Observability at any time, including during the initial {microshift-short} installation. Observability collects and transmits system data for monitoring and analysis, such as performance and usage metrics and error reporting. .Procedure . Install the `microshift-observability` RPM by entering the following command: @@ -38,4 +39,3 @@ $ sudo systemctl restart microshift-observability ---- The installation is successful if there is no output after you start the `microshift-observability` RPM. - \ No newline at end of file diff --git a/modules/microshift-otel-verify.adoc b/modules/microshift-otel-verify.adoc index ac7eeb67b02a..30e3a96d6e1c 100644 --- a/modules/microshift-otel-verify.adoc +++ b/modules/microshift-otel-verify.adoc @@ -6,6 +6,7 @@ [id="microshift-otel-verify_{context}"] = Verifying the {microshift-short} Observability state +[role="_abstract"] After {microshift-short} Observability starts, you can verify the state by using a `systemd` service. The {microshift-short} Observability service logs are available as `journald` logs. .Procedure @@ -23,4 +24,3 @@ $ sudo systemctl status microshift-observability ---- $ sudo journalctl -u microshift-observability ---- - \ No newline at end of file diff --git a/modules/microshift-rhoai-install.adoc b/modules/microshift-rhoai-install.adoc index d48f2ba7c376..19c622f8a98a 100644 --- a/modules/microshift-rhoai-install.adoc +++ b/modules/microshift-rhoai-install.adoc @@ -6,16 +6,17 @@ [id="microshift-rhoai-install_{context}"] = Installing the {rhoai-full} RPM -To use AI models in {microshift-short} deployments, use this procedure to install the {rhoai-full} ({rhoai}) RPM with a new {microshift-short} installation. You can also install the RPM on an existing {microshift-short} instance if you restart the system. +[role="_abstract"] +To use AI models in {microshift-short} deployments, install the {rhoai-full} ({rhoai}) RPM with a new {microshift-short} installation. You can also install the RPM on an existing {microshift-short} instance if you restart the system. + +[NOTE] +==== +The `microshift-ai-model-serving` RPM contains manifests that deploy `kserve`, with the raw deployment mode enabled, and `ServingRuntimes` objects in the `redhat-ods-applications` namespace. +==== :FeatureName: {rhoai-full} include::snippets/technology-preview.adoc[leveloffset=+1] -//[IMPORTANT] -//==== -//Installing the `microshift-ai-model-serving` RPM before running the `$ systemctl start microshift` command for the first time can cause {microshift-short} to fail to start. However, {microshift-short} automatically restarts successfully in this case. -//==== - .Prerequisites * The system requirements for installing {microshift-short} have been met. @@ -26,11 +27,6 @@ include::snippets/technology-preview.adoc[leveloffset=+1] * You configured the required accelerators, hardware, operating system, and {microshift-short} to provide the resources your model needs. * Your AI model is ready to use. -[NOTE] -==== -The `microshift-ai-model-serving` RPM contains manifests that deploy `kserve`, with the raw deployment mode enabled, and `ServingRuntimes` objects in the `redhat-ods-applications` namespace. -==== - .Procedure . Install the {microshift-short} AI-model-serving RPM package by running the following command: @@ -51,9 +47,13 @@ $ sudo systemctl restart microshift + [source,terminal] ---- -$ sudo dnf install microshift-ai-model-serving-release-info <1> +$ sudo dnf install microshift-ai-model-serving-release-info ---- -<1> The release information package contains a JSON file with image references useful for offline procedures or deploying copy of a `ServingRuntime` to your namespace during a bootc image build. ++ +[NOTE] +==== +The `microshift-ai-model-serving-release-info` RPM contains a JSON file with image references useful for offline procedures or deploying a copy of a `ServingRuntime` Custom Resource to your namespace during a bootc image build. +==== .Verification