Merge pull request #101964 from ShaunaDiaz/OSDOCS-15651

ShaunaDiaz · web-flow · commit 475c2f90ee96 · 2025-11-11T09:37:05.000-05:00
OSDOCS-15651: mods GitOps assembly MicroShift
diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc
@@ -14,7 +14,7 @@
 //gitops version for 4.17-4.19
 :gitops-ver: 1.16
 :gitops-title: Red{nbsp}Hat OpenShift GitOps
-:gitops-shortname: GitOps
+:gitops: GitOps
 :product-registry: OpenShift image registry
 :product-version: 4.20
 :rhel-major: rhel-9
diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml
@@ -270,7 +270,7 @@ Distros: microshift
 Topics:
 - Name: The etcd service
   File: microshift-etcd
-- Name: The sos report tool
+- Name: Using sos reports
   File: microshift-sos-report
 - Name: Getting your node ID
   File: microshift-getting-node-id
diff --git a/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc b/microshift_install_rpm_opt/microshift-install-optional-rpms.adoc
@@ -23,7 +23,8 @@ include::modules/microshift-rhoai-install.adoc[leveloffset=+1]
 [id="additional-resources_microshift-install-optional-rpms"]
 [role="_additional-resources"]
 == Additional resources
-* xref:../microshift_running_apps/microshift-gitops.adoc#microshift-gitops[Automating application management with the {gitops-shortname} controller]
+
+* xref:../microshift_running_apps/microshift-gitops.adoc#microshift-gitops[Automating application management with the {gitops-short} controller]
 * xref:../microshift_networking/microshift_multiple_networks/microshift-cni-multus.adoc#microshift-cni-multus[About using multiple networks]
 * xref:../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}]
 * xref:../microshift_running_apps/microshift-observability-service.adoc#microshift-observability-service[Using {microshift-short} Observability]
diff --git a/microshift_running_apps/microshift-gitops.adoc b/microshift_running_apps/microshift-gitops.adoc
@@ -1,52 +1,29 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-gitops"]
 = Automating application management with the GitOps controller
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-gitops
 
 toc::[]
 
-GitOps with Argo CD for {microshift-short} is a lightweight, optional add-on controller derived from the Red Hat OpenShift GitOps Operator. GitOps for {microshift-short} uses the command-line interface (CLI) of Argo CD to interact with the GitOps controller that acts as the declarative GitOps engine. You can consistently configure and deploy Kubernetes-based infrastructure and applications across node and development lifecycles.
-
-[id="microshift-gitops-can-do_{context}"]
-== What you can do with the GitOps agent
-By using the GitOps with Argo CD agent with {microshift-short}, you can utilize the following principles:
+[role="_abstract"]
+You can consistently configure and deploy Kubernetes-based infrastructure and applications across node and development lifecycles by using the declarative {gitops-title} engine.
 
-* Implement application lifecycle management.
-** Create and manage your node and application configuration files using the core principles of developing and maintaining software in a Git repository.
-** You can update the single repository and GitOps automates the deployment of new applications or updates to existing ones.
-** For example, if you have 1,000 edge devices, each using {microshift-short} and a local GitOps agent, you can easily add or update an application on all 1,000 devices with just one change in your central Git repository.
-* The Git repository contains a declarative description of the infrastructure you need in your specified environment and contains an automated process to make your environment match the described state.
-* You can also use the Git repository as an audit trail of changes so that you can create processes based on Git flows such as review and approval for merging pull requests that implement configuration changes.
+include::modules/microshift-gitops-can-do.adoc[leveloffset=+1]
 
-include::modules/microshift-gitops-adding-apps.adoc[leveloffset=+1]
-
-[role="_additional-resources"]
-.Additional resources
-* xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-installing-rpms-for-gitops_microshift-install-rpm[Installing the GitOps Argo CD manifests from an RPM package]
+include::modules/microshift-gitops-limitations.adoc[leveloffset=+1]
 
-[id="microshift-gitops-cannot-do_{context}"]
-== Limitations of using the GitOps agent with {microshift-short}
-GitOps with Argo CD for {microshift-short} has the following differences from the Red Hat OpenShift GitOps Operator:
+include::modules/microshift-install-rpms-gitops.adoc[leveloffset=+1]
 
-* The `gitops-operator` component is not used with {microshift-short}.
-* To maintain the small resource use of {microshift-short}, the Argo CD web console is not available. You can use the Argo CD CLI.
-* Because {microshift-short} is single-node, there is no multi-node support. Each instance of {microshift-short} is paired with a local GitOps agent.
-* The `oc adm must-gather` command is not available in {microshift-short}.
-
-[id="microshift-gitops-troubleshooting_{context}"]
-== Troubleshooting GitOps
-If you have problems with your GitOps controller, you can use the {oc-first} tool.
+include::modules/microshift-gitops-adding-apps.adoc[leveloffset=+1]
 
-include::modules/microshift-gitops-debug.adoc[leveloffset=+2]
+include::modules/microshift-gitops-debug.adoc[leveloffset=+1]
 
 [id="additional-resources_microshift-gitops_{context}"]
 [role="_additional-resources"]
 == Additional resources
-* xref:../microshift_install_rpm/microshift-install-rpm.adoc#microshift-installing-rpms-for-gitops_microshift-install-rpm[Installing the GitOps Argo CD manifests from an RPM package]
 
 * xref:../microshift_support/microshift-sos-report.adoc#microshift-sos-report[Using sos reports]
-
-* link:https://access.redhat.com/documentation/en-us/red_hat_openshift_gitops/1.12[Red Hat OpenShift GitOps]
-
-* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/getting_the_most_from_your_support_experience/generating-an-sos-report-for-technical-support_getting-the-most-from-your-support-experience[Generating an sos report for technical support] (Red Hat Enterprise Linux)
+* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/getting_the_most_from_your_support_experience/generating-an-sos-report-for-technical-support_getting-the-most-from-your-support-experience[Generating an sos report for technical support]
+* link:https://docs.redhat.com/en/documentation/red_hat_openshift_gitops/latest[{gitops-title}]
diff --git a/microshift_support/microshift-sos-report.adoc b/microshift_support/microshift-sos-report.adoc
@@ -1,19 +1,22 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-sos-report"]
 = Using sos reports
+
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-sos-report
 
 toc::[]
 
-You can use the `sos` tool to collect troubleshooting information about a host. The `sos report` command generates a detailed report that shows all of the enabled plugins and data from the different components and applications in a system.
+[role="_abstract"]
+As an administrator, you can use the `sos` tool to collect troubleshooting information about a {op-system-full} host and share that information with Red{nbsp}Hat support.
 
 include::modules/microshift-about-sos-reports.adoc[leveloffset=+1]
 
 include::modules/microshift-gathering-sos-report.adoc[leveloffset=+1]
 
-[role="_additional-resources"]
 [id="additional-resources_microshift-sos-report_{context}"]
+[role="_additional-resources"]
 == Additional resources
-* link:https://access.redhat.com/solutions/2112[How to provide files to Red Hat Support (vmcore, rhev logcollector, sosreports, heap dumps, log files, etc.]
-* link:https://access.redhat.com/solutions/3592[What is an sos report and how to create one in {op-system-base-full}?]
+
+* link:https://access.redhat.com/solutions/2112[How to provide files to Red Hat Support]
+* link:https://access.redhat.com/solutions/3592[What is an sos report and how to create one in {op-system-base-full}?]
diff --git a/modules/microshift-about-sos-reports.adoc b/modules/microshift-about-sos-reports.adoc
@@ -6,7 +6,10 @@
 [id="about-microshift-sos-reports_{context}"]
 = About sos reports
 
-The `sos` tool is composed of different plugins that help you gather information from different applications. A {microshift-short}-specific plugin from sos version 4.5.1 can gather the following data:
+[role="_abstract"]
+You can use an sos report to troubleshoot a failing host or problems with {gitops-title}. The `sos` tool combines plugins that help you gather information from different applications. The `sos report` command generates a detailed report that shows all of the enabled plugins and data from the different components and applications in a system.
+
+A {microshift-short}-specific plugin from sos version 4.5.1 gathers the following data:
 
 * {microshift-short} configuration and version
 * YAML output for node and system namespaced resources
diff --git a/modules/microshift-gathering-sos-report.adoc b/modules/microshift-gathering-sos-report.adoc
@@ -6,9 +6,13 @@
 [id="gathering-data-microshift-sos-report_{context}"]
 = Gathering data from an sos report
 
+[role="_abstract"]
+You can create an sos report about a failing {op-system-full} host that you can share with Red{nbsp}Hat support for troubleshooting.
+
 .Prerequisites
 
 * You must have the `sos` package installed.
+* You have root access to the host.
 
 .Procedure
 
@@ -76,4 +80,4 @@ Your sosreport has been generated and saved in:
  sha256	922e5ff2db25014585b7c6c749d2c44c8492756d619df5e9838ce863f83d4269
 
 Please send this file to your support representative.
-----
+----
diff --git a/modules/microshift-gitops-adding-apps.adoc b/modules/microshift-gitops-adding-apps.adoc
@@ -6,12 +6,12 @@
 [id="microshift-gitops-adding-apps_{context}"]
 = Creating GitOps applications on {microshift-short}
 
-You can create a custom YAML configuration to deploy and manage applications in your {microshift-short} service. To install the necessary packages to run GitOps applications, follow the documentation in "Installing the GitOps Argo CD manifests from an RPM package".
+[role="_abstract"]
+You can create a custom configuration by using a YAML file to deploy and manage applications in your {microshift-short} service after you install the {gitops-title} Argo CD manifests from an RPM package.
 
 .Prerequisites
 
 * You installed the `microshift-gitops` packages.
-
 * The Argo CD pods are running in the `openshift-gitops` namespace.
 
 .Procedure
@@ -60,12 +60,12 @@ spec:
 
 . To deploy the applications defined in the YAML file, run the following command:
 +
-[source,terminal]
-[subs="+quotes"]
+[source,terminal,subs="+quotes"]
 ----
-$ oc apply -f __<my_app.yaml>__ <1>
+$ oc apply -f _<my_app.yaml>_
 ----
-<1> Replace `_<my_app.yaml>_` with the name of your application YAML.
++
+Replace `_<my_app.yaml>_` with the name of your application YAML.
 
 .Verification
 
@@ -75,11 +75,12 @@ $ oc apply -f __<my_app.yaml>__ <1>
 ----
 $ oc get applications -A
 ----
-It might take a few minutes for the application to show the `Healthy` status.
++
+Wait a few minutes for the application to show a `Healthy` status.
 +
 .Example output
 [source,terminal]
 ----
 NAMESPACE          NAME               SYNC STATUS   HEALTH STATUS
 openshift-gitops   spring-petclinic   Synced        Healthy
-----
+----
diff --git a/modules/microshift-gitops-can-do.adoc b/modules/microshift-gitops-can-do.adoc
@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// microshift_running_apps/microshift-gitops.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-gitops-can-do_{context}"]
+= What you can do with the GitOps agent
+
+[role="_abstract"]
+You can manage application lifecycles and use automated processes to manage application changes with {gitops-title}.
+
+{gitops} with Argo CD for {microshift-short} is a lightweight, optional add-on controller derived from the {gitops} Operator.
+
+The {gitops} agent for {microshift-short} uses the command-line interface (CLI) of Argo CD to interact with the {gitops} controller. The controller acts as the declarative {gitops} engine. By using the {gitops} with Argo CD agent for {microshift-short}, you can use the following principles:
+
+* Implement application lifecycle management:
+
+** Create and manage your node and application configuration files using the core principles of developing and maintaining software in a Git repository.
+** You can update the single repository and GitOps automates the deployment of new applications or updates to existing ones.
+** For example, if you have 1,000 edge devices, each using {microshift-short} and a local GitOps agent, you can easily add or update an application on all 1,000 devices with just one change in your central Git repository.
+
+* The Git repository contains a declarative description of the infrastructure you need in your specified environment and contains an automated process to make your environment match the described state.
+
+* You can also use the Git repository as an audit trail of changes so that you can create processes based on Git flows such as review and approval for merging pull requests that implement configuration changes.
diff --git a/modules/microshift-gitops-debug.adoc b/modules/microshift-gitops-debug.adoc
@@ -4,17 +4,18 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-gitops-debug_{context}"]
-= Debugging GitOps with oc adm inspect
+= Debugging {gitops} with oc adm inspect
 
-You can debug GitOps by using the {oc-first}.
+[role="_abstract"]
+If you have problems with your Argo CD for {microshift-short} {gitops-title} controller, you can use the {oc-first} tool to inspect it for errors.
 
 .Prerequisites
 
 * The `oc` command-line tool is installed.
 
 .Procedure
 
-. Run the `oc adm inspect` command when in the GitOps namespace:
+* Run the `oc adm inspect` command when in the {gitops} namespace:
 +
 [source,terminal]
 ----
@@ -32,4 +33,5 @@ Wrote inspect data to inspect.local.2673575938140296280.
 ----
 
 .Next steps
-* If `oc adm inspect` did not provide the information you need, you can run an sos report.
+
+* If `oc adm inspect` did not show the information you need, you can run an sos report.
diff --git a/modules/microshift-gitops-limitations.adoc b/modules/microshift-gitops-limitations.adoc
@@ -0,0 +1,16 @@
+
+// Module included in the following assemblies:
+//
+// microshift_running_apps/microshift-gitops.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-gitops-limitations_{context}"]
+= Limitations of using the {gitops} agent with {microshift-short}
+
+[role="_abstract"]
+Using {gitops-title} with Argo CD for {microshift-short} is different from using the entire {gitops} Operator in the following ways:
+
+* The `gitops-operator` component is not used with {microshift-short}.
+* To maintain the small resource use of {microshift-short} use the Argo CD CLI. The Argo CD web console is not available.
+* Because {microshift-short} is single-node, there is no multi-node support. Each instance of {microshift-short} is paired with a local {gitops} agent.
+* The `oc adm must-gather` command is not available in {microshift-short}.
diff --git a/modules/microshift-install-rpms-gitops.adoc b/modules/microshift-install-rpms-gitops.adoc
@@ -1,34 +1,37 @@
 // Module included in the following assemblies:
 //
 // microshift/microshift-install-optional-rpms.adoc
+// microshift_running_apps/microshift.gitops.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-installing-rpms-for-gitops_{context}"]
-= Installing the {gitops-shortname} Argo CD manifests from an RPM package
+= Installing the {gitops} Argo CD manifests from an RPM package
 
 [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.
+You can use a lightweight version of {gitops-title} 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.
 
 [IMPORTANT]
 ====
-The Argo CD CLI is not available on {microshift-short}. This process installs basic {gitops-shortname} functions.
+The Argo CD web console is not available on {microshift-short}. This process installs basic {gitops} functions.
 ====
 
 .Prerequisites
 
-* You installed {microshift-short} version 4.14 or later.
+* You installed {microshift-short} version 4.16 or later.
 * You configured 250MB RAM of additional storage.
 
 .Procedure
 
-. Enable the {gitops-shortname} repository with the subscription manager by running the following command:
+. Enable the {gitops} 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-shortname} package by running the following command:
+. Install the {microshift-short} {gitops} package by running the following command:
 +
 [source,terminal]
 ----
