Merge pull request #84633 from aravipra/OSDOCS-12183-rework

[WIP] OSDOCS-12183-rework: rework of changes in delete Kustomize manifest resources

Author: ShaunaDiaz

_topic_maps/_topic_map_ms.yml

@@ -195,7 +195,7 @@ Distros: microshift
 Topics:
 - Name: Using Kustomize to deploy applications
   File: microshift-applications
-- Name: Deleting resource manifests
+- Name: Deleting or updating Kustomize manifest resources
   File: microshift-deleting-resource-manifests
 - Name: Embedding applications on RHEL for Edge
   File: microshift-embedded-apps-on-rhel-edge

microshift_running_apps/microshift-applications.adoc

@@ -12,4 +12,8 @@ include::modules/microshift-manifests-overview.adoc[leveloffset=+1]
 
 include::modules/microshift-manifests-override-paths.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../microshift_running_apps/microshift-deleting-resource-manifests.adoc#microshift-deleting-resource-manifests[Deleting or updating Kustomize manifest resources]
+
 include::modules/microshift-applying-manifests-example.adoc[leveloffset=+1]

microshift_running_apps/microshift-deleting-resource-manifests.adoc

@@ -1,34 +1,38 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-deleting-resource-manifests"]
-= Deleting resource manifests
+= Deleting or updating Kustomize manifest resources
 include::_attributes/attributes-microshift.adoc[]
 :context: microshift-deleting-resource-manifests
 
 toc::[]
 
-{microshift-short} supports the deletion of resource manifests in the following situations:
+{microshift-short} supports the deletion of manifest resources in the following situations:
 
 * Manifest removal: Manifests can be removed when you need to completely remove a resource from the cluster.
 * Manifest upgrade: During an application upgrade, some resources might need to be removed while others are retained to preserve data.
 
-When creating new manifests, you can use resource manifest deletion to remove or update old objects, ensuring there are no conflicts or issues.
+When creating new manifests, you can use manifest resource deletion to remove or update old objects, ensuring there are no conflicts or issues.
 
 [IMPORTANT]
 ====
-Manifest files placed in the `delete` subdirectories are not automatically removed and require manual deletion.
+Manifest files placed in the `delete` subdirectories are not automatically removed and require manual deletion. Only the resources listed in the manifest files placed in the delete subdirectories are deleted.
 ====
 
 include::modules/microshift-manifests-deletion-overview.adoc[leveloffset=+1]
 
 [id="microshift-examples-of-usecase_{context}"]
-== Use cases for resource manifest deletion
+== Use cases for manifest resource deletion
 
-The following explains the use case in which the resource manifest deletion is used.
+The following sections explain the use case in which the manifest resource deletion is used.
 
 include::modules/microshift-manifests-removal-scenario-rpm.adoc[leveloffset=+2]
 
 include::modules/microshift-manifests-removal-scenario-ostree.adoc[leveloffset=+2]
 
 include::modules/microshift-manifests-upgrade-scenario-rpm.adoc[leveloffset=+2]
 
-include::modules/microshift-manifests-upgrade-scenario-ostree.adoc[leveloffset=+2]
+include::modules/microshift-manifests-upgrade-scenario-ostree.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+== Additional resources
+* xref:../microshift_running_apps/microshift-applications.adoc#applications-with-microshift[Using Kustomize manifests to deploy applications]

modules/microshift-manifests-deletion-overview.adoc

@@ -8,11 +8,11 @@
 
 By default, {microshift-short} searches for deletion manifests in the `delete` subdirectories within the manifests path. When a user places a manifest in these subdirectories, {microshift-short} removes the manifests when the system is started. Read through the following to understand how manifests deletion works in {microshift-short}.
 
-. Each time the system starts, before applying the manifests, {microshift-short} scans the following `delete` subdirectories within the configured manifests directory to identify the Kustomize manifests that need to be deleted:
+. Each time the system starts, before applying the manifests, {microshift-short} scans the following `delete` subdirectories within the configured manifests directory to identify the manifests that need to be deleted:
 
-* /usr/lib/microshift/manifests/delete
-* /usr/lib/microshift/manifests.d/delete/*
-* /etc/microshift/manifests/delete
-* /etc/microshift/manifests.d/delete/*
+* `/usr/lib/microshift/manifests/delete`
+* `/usr/lib/microshift/manifests.d/delete/*`
+* `/etc/microshift/manifests/delete`
+* `/etc/microshift/manifests.d/delete/*`
 
-. {microshift-short} deletes the resources defined in the Kustomize manifests found in the `delete` directories by running the equivalent of the `kubectl delete --ignore-not-found -k` command.
+. {microshift-short} deletes the resources defined in the manifests found in the `delete` directories by running the equivalent of the `kubectl delete --ignore-not-found -k` command.

modules/microshift-manifests-overview.adoc

@@ -13,6 +13,11 @@ The `kustomize` configuration management tool is integrated with {microshift-sho
 * Using a manifest copy with an overlay keeps the original configuration file for your application intact, while enabling you to deploy iterations and customizations of your applications efficiently.
 * You can then deploy the application in your {microshift-short} cluster with an `oc` command.
 
+[NOTE]
+====
+At each system start, {microshift-short} deletes the manifests found in the `delete` subdirectories and then applies the manifest files found in the manifest directories to the cluster.
+====
+
 [id="how-microshift-uses-manifests"]
 == How {microshift-short} uses manifests
 At every start, {microshift-short} searches the following manifest directories for Kustomize manifest files:

modules/microshift-manifests-removal-scenario-ostree.adoc

@@ -6,11 +6,11 @@
 [id="microshift-manifests-removal-scenario-ostree_{context}"]
 = Removing manifests for OSTree systems
 
-Use the following procedure to completely delete the resource defined in the Kustomize manifests.
+Use the following procedure to completely delete the resource defined in the manifests.
 
 [IMPORTANT]
 ====
-For OSTree installation, the `delete` subdirectories are read only.
+For OSTree installation, the `delete` subdirectories are read-only.
 ====
 
 .Procedure

modules/microshift-manifests-removal-scenario-rpm.adoc

@@ -6,7 +6,7 @@
 [id="microshift-manifests-removal-scenario-rpm_{context}"]
 = Removing manifests for RPM systems
 
-Use the following procedure in the data removal scenario for RPM systems to completely delete the resource defined in the Kustomize manifests.
+Use the following procedure in the data removal scenario for RPM systems to completely delete the resource defined in the manifests.
 
 .Procedure
 
@@ -15,16 +15,19 @@ Use the following procedure in the data removal scenario for RPM systems to comp
 +
 [source,terminal]
 ----
-$ sudo mkdir -p _<path_of_delete_directory>_ <1>
+$ sudo mkdir -p <path_of_delete_directory> <1>
 ----
-<1> Replace `_<path_of_delete_directory>_` with the path of the delete subdirectory, for example, `/etc/microshift/manifests.d/delete`, `/etc/microshift/manifests/delete/`, `/usr/lib/microshift/manifests.d/delete` or `/usr/lib/microshift/manifests/delete`.
+<1> Replace `_<path_of_delete_directory>_` with one of the following valid directory paths: `/etc/microshift/manifests.d/delete`, `/etc/microshift/manifests/delete/`, `/usr/lib/microshift/manifests.d/delete`, or `/usr/lib/microshift/manifests/delete`.
 . Move the manifest file into one of the `delete` subdirectories under the configured manifests directory by running the following command:
 +
 [source,terminal]
 ----
-$ [sudo] mv _<path_of_manifests>_ _<path_of_delete_directory>_ <1>
+$ [sudo] mv <path_of_manifests> <path_of_delete_directory>
 ----
-<1> Replace `_<path_of_manifests>_` with the path of the manifest to be deleted, for example, `/etc/microshift/manifests.d/010-SOME-MANIFEST`. Replace `_<path_of_delete_directory>_` with the path of the delete subdirectory, for example, `/etc/microshift/manifests.d/delete`, `/etc/microshift/manifests/delete`, `/usr/lib/microshift/manifests.d/delete` or `/usr/lib/microshift/manifests/delete`.
++
+where:
+`_<path_of_manifests>_`:: Specifies the path of the manifest to be deleted, for example `/etc/microshift/manifests.d/010-SOME-MANIFEST`.
+`_<path_of_delete_directory>_`:: Specifies one of the following valid directory paths: `/etc/microshift/manifests.d/delete`, `/etc/microshift/manifests/delete`, `/usr/lib/microshift/manifests.d/delete` or `/usr/lib/microshift/manifests/delete`.
 . Restart {microshift-short} by running the following command:
 +
 [source,terminal]

modules/microshift-manifests-upgrade-scenario-ostree.adoc

@@ -10,12 +10,12 @@ Use the following procedure to remove some resources while retaining others to p
 
 [IMPORTANT]
 ====
-For OSTree systems, the `delete` subdirectories are read only.
+For OSTree systems, the `delete` subdirectories are read-only.
 ====
 
 .Procedure
 
 . Identify the manifest that needs updating.
-. Create a new manifest to apply in the manifest path. See link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/applications-with-microshift#microshift-applying-manifests-example_applications-microshift[Using manifests example] to create new manifests using the example.
+. Create a new manifest to apply in the manifest directories. See link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/applications-with-microshift#microshift-applying-manifests-example_applications-microshift[Using manifests example] to create new manifests using the example.
 . Create a new manifest for resource deletion to be placed in the `delete` subdirectories.
 . Use the procedure in "Removing manifests for OSTree systems" to remove the manifests.

modules/microshift-manifests-upgrade-scenario-rpm.adoc

@@ -11,6 +11,6 @@ Use the following procedure to remove some resources while retaining others to p
 .Procedure
 
 . Identify the manifest that requires updating.
-. Create new manifests to be applied in the manifest path.
+. Create new manifests to be applied in the manifest directories.
 . Create new manifests for resource deletion. It is not necessary to include the `spec` in these manifests. See link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/applications-with-microshift#microshift-applying-manifests-example_applications-microshift[Using manifests example] to create new manifests using the example.
 . Use the procedure in "Removing manifests for RPM systems" to create `delete` subdirectories and place the manifests created for resource deletion in this path.