OSDOCS#13788: Added info for cache and workspace directories in oc-mirror doc

disconnected/mirroring/about-installing-oc-mirror-v2.adoc

@@ -136,6 +136,7 @@ include::modules/oc-mirror-imageset-config-parameters-v2.adoc[leveloffset=+1]
 // Command reference for oc-mirror v2
 include::modules/oc-mirror-command-reference-v2.adoc[leveloffset=+1]
 include::modules/oc-mirror-command-reference-v2-delete.adoc[leveloffset=+2]
+include::modules/oc-mirror-about-cache-and-workspace-dirs.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources

modules/oc-mirror-about-cache-and-workspace-dirs.adoc

@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="oc-mirror-about-cache-and-workspace-dirs_{context}"]
+= About the --cache-dir and --workspace flags
+
+You can use the `--cache-dir` flag to specify a directory where the oc-mirror plugin stores a persistent cache of image blobs and manifests for use during mirroring operations.
+
+The oc-mirror plugin uses the cache in the `disk-to-mirror` and `mirror-to-disk` workflows but does not use the cache in the `mirror-to-mirror` workflow. The plugin uses the cache to perform incremental mirroring and avoids remirroring unchanged images, which saves time and reduces network bandwidth usage.
+
+The cache directory only contains data up to the last successful mirroring operation. If you delete or corrupt the cache directory, the oc-mirror plugin pulls the image blobs and manifests again, which can force a full remirror and increase network usage.
+
+You can use the `--workspace` flag to specify a directory where the oc-mirror plugin stores the working files that it creates during a mirroring operation, such as the `ImageDigestMirrorSet` and `ImageTagMirrorSet` manifests. You can also use the workspace directory to perform the following actions:
+
+* Store the untarred metadata for release and operator images.
+* Generate tar archives for use in `disk-to-mirror` workflows.
+* Apply the generated configuration to clusters.
+* Repeat or resume previous mirroring operations.
+
+If you remove or modify the workspace directory, future mirroring operations might fail, or clusters may use inconsistent image sources.
+
+[WARNING]
+====
+Deleting or modifying the contents of cache or workspace directories can cause the following issues:
+
+* Failed or incomplete mirroring operations.
+* Loss of incremental mirroring data.
+* Full remirroring requirements and increased network overhead.
+
+Do not modify, relocate, or delete these directories unless you fully understand the impact. You must regularly back up the cache directory after successful mirroring operations. It is not necessary to back up the workspace directory because its contents are regenerated during each mirroring cycle.
+====
+
+Consider the following best practices so that you can better manage the cache and workspace directories effectively:
+
+* Use persistent storage: Place the cache and workspace directories on reliable and backed‑up storage.
+* Back up after successful operations: Regularly back up the cache directory, especially after completing a mirroring cycle.
+* Restore when needed: In case of data loss, restore the cache and workspace directories from backup to resume mirroring operations without performing a full remirror.
+* Separate environments: Use dedicated directories for different environments to prevent conflicts.
+
+Use the following example to specify the cache and workspace directories when running the oc-mirror command:
+
+[source,terminal]
+----
+$ oc mirror --config=imageset-config.yaml \
+    file://local_mirror \
+    --workspace /mnt/mirror-data/workspace \
+    --cache-dir /mnt/mirror-data/cache
+    --v2
+----
+
+After the mirroring operation completes, your directory structure is as follows:
+
+[source,text]
+----
+/mnt/mirror-data/
+├── cache/
+│   ├── manifests/
+│   ├── metadata.db
+│   └── previous-mirror-state.json
+└── workspace/
+    ├── imageset-config-state.yaml
+    ├── manifests/
+    └── icsp/
+----
+You must back up the `/mnt/mirror-data/cache` directory after each successful mirroring operation.
+

modules/oc-mirror-command-reference-v2-delete.adoc

@@ -19,7 +19,7 @@ The following tables describe the `oc mirror` subcommands and flags for deleting
 |Path of the authentication file. The default value is `${XDG_RUNTIME_DIR}/containers/auth.json`.
 
 |`--cache-dir <string>`
-|oc-mirror cache directory location. The default is `$HOME`.
+|Use this flag to specify a directory where the oc-mirror plugin stores a persistent cache of image blobs and manifests for use during mirroring operations. The oc-mirror plugin uses the cache in the `disk-to-mirror` and `mirror-to-disk` workflows but does not use the cache in the `mirror-to-mirror` workflow. The plugin uses the cache to perform incremental mirroring and avoids remirroring unchanged images, which saves time and reduces network bandwidth usage. The default cache directory is `$HOME`. For more information, see "About the --cache-dir and --workspace flags".
 
 |`-c <string>`, `--config <string>`
 |Path to the delete imageset configuration file.
@@ -67,6 +67,6 @@ The following tables describe the `oc mirror` subcommands and flags for deleting
 |Require HTTPS and verify certificates when talking to the container registry or daemon. The default value is `true`.
 
 |`--workspace <string>`
-|oc-mirror workspace where resources and internal artifacts are generated.
+|You can use the `--workspace` flag to specify a directory where the oc-mirror plugin stores the working files that it creates during a mirroring operation, such as the `ImageDigestMirrorSet` and `ImageTagMirrorSet` manifests. Use this directory to apply the generated configuration to clusters and repeat mirroring operations. For more information, see "About the --cache-dir and --workspace flags".
 
 |===

modules/oc-mirror-command-reference-v2.adoc

@@ -39,7 +39,7 @@ The following tables describe the `oc mirror` subcommands and flags for oc-mirro
 |Specifies the path to an image set configuration file.
 
 |`--cache-dir <string>` 
-|oc-mirror cache directory location. The default value is `$HOME`.
+|Use this flag to specify a directory where the oc-mirror plugin stores a persistent cache of image blobs and manifests for use during mirroring operations. The oc-mirror plugin uses the cache in the `disk-to-mirror` and `mirror-to-disk` workflows but does not use the cache in the `mirror-to-mirror` workflow. The plugin uses the cache to perform incremental mirroring and avoids remirroring unchanged images, which saves time and reduces network bandwidth usage. The default cache directory is `$HOME`. For more information, see "About the --cache-dir and --workspace flags".
 
 |`--dest-tls-verify`
 |Requires HTTPS and verifies certificates when accessing the container registry or daemon. The default value is `true`.
@@ -87,7 +87,7 @@ The following tables describe the `oc mirror` subcommands and flags for oc-mirro
 |Displays the version for oc-mirror plugin v2.
 
 |`--workspace` 
-|Determines string oc-mirror plugin v2 workspace where resources and internal artifacts are generated.
+|You can use the `--workspace` flag to specify a directory where the oc-mirror plugin stores the working files that it creates during a mirroring operation, such as the `ImageDigestMirrorSet` and `ImageTagMirrorSet` manifests. Use this directory to apply the generated configuration to clusters and repeat mirroring operations. For more information, see "About the --cache-dir and --workspace flags".
 
 |`--retry-delay duration` 
 |Delay between 2 retries. The default value is `1s`.