OSDOCS-12183: adding how to delete manifests

_topic_maps/_topic_map_ms.yml

@@ -195,6 +195,8 @@ Distros: microshift
 Topics:
 - Name: Using Kustomize to deploy applications
   File: microshift-applications
+- Name: Deleting resource manifests
+  File: microshift-deleting-resource-manifests
 - Name: Embedding applications on RHEL for Edge
   File: microshift-embedded-apps-on-rhel-edge
 - Name: Embedding applications for offline use

microshift_running_apps/microshift-deleting-resource-manifests.adoc

@@ -0,0 +1,34 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="microshift-deleting-resource-manifests"]
+= Deleting resource manifests
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-deleting-resource-manifests
+
+toc::[]
+
+{microshift-short} supports the deletion of resource manifests 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.
+
+[IMPORTANT]
+====
+Manifest files placed in the `delete` subdirectories are not automatically removed and require manual deletion.
+====
+
+include::modules/microshift-manifests-deletion-overview.adoc[leveloffset=+1]
+
+[id="microshift-examples-of-usecase_{context}"]
+== Use cases for resource manifest deletion
+
+The following explains the use case in which the resource manifest 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]

modules/microshift-manifests-deletion-overview.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * microshift//running_applications/microshift-deleting-resource-manifests.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-manifests-deletion-overview_{context}"]
+= How manifest deletion works
+
+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:
+
+* /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.

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

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * microshift/running_applications/microshift-deleting-resource-manifests.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[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.
+
+[IMPORTANT]
+====
+For OSTree installation, the `delete` subdirectories are read only.
+====
+
+.Procedure
+
+. Identify the manifest that needs to be placed in the `delete` subdirectories.
+. Package the manifest into an RPM. See link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/microshift-embedding-apps-tutorial#microshift-building-apps-rpms_microshift-embedding-apps-tutorial[Building the RPM package for the application] for the procedure to package the manifest into an RPM.
+. Add the packaged RPM to the blueprint file to install it into correct location. See link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/microshift-embedding-apps-tutorial#microshift-adding-app-rpms-to-blueprint_microshift-embedding-apps-tutorial[Adding application RPMs to a blueprint] for the procedure to add an RPM to a blueprint.

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

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * microshift//running_applications/microshift-deleting-resource-manifests.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[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.
+
+.Procedure
+
+. Identify the manifest that needs to be placed in the `delete` subdirectories.
+. Create the `delete` subdirectory in which the manifest will be placed by running the following command:
++
+[source,terminal]
+----
+$ 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`.
+. 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>
+----
+<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`.
+. Restart {microshift-short} by running the following command:
++
+[source,terminal]
+----
+$ sudo systemctl restart microshift
+----
+. {microshift-short} detects and removes the resource after the manifest file is placed in the `delete` subdirectories.

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

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * microshift/running_applications/microshift-deleting-resource-manifests.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-manifests-upgrade-scenario-ostree_{context}"]
+= Upgrading manifests for OSTree systems
+
+Use the following procedure to remove some resources while retaining others to preserve data.
+
+[IMPORTANT]
+====
+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 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

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * microshift/running_applications/microshift-deleting-resource-manifests.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-manifests-upgrade-scenario-rpm_{context}"]
+= Upgrading manifests for RPM systems
+
+Use the following procedure to remove some resources while retaining others to preserve data.
+
+.Procedure
+
+. Identify the manifest that requires updating.
+. Create new manifests to be applied in the manifest path.
+. 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.