Skip to content

Commit 05b1a79

Browse files
skopacz1skopacz1
authored
Merge pull request #87754 from subhtk/osdocs13232
OSDOCS 12363: Added migration from v1 to v2 section in oc-mirror docs
2 parents 2a20cb8 + 7207946 commit 05b1a79

File tree

5 files changed

+234
-2
lines changed

5 files changed

+234
-2
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,8 @@ Topics:
130130
File: installing-mirroring-disconnected
131131
- Name: Mirroring images for a disconnected installation using oc-mirror plugin v2
132132
File: about-installing-oc-mirror-v2
133+
- Name: Migrating from oc-mirror plugin v1 to v2
134+
File: oc-mirror-migration-v1-to-v2
133135
- Name: Installing a cluster in a disconnected environment
134136
File: installing
135137
- Name: Using OLM in disconnected environments

‎disconnected/mirroring/oc-mirror-migration-v1-to-v2.adoc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="oc-mirror-migration-v1-to-v2"]
3+
= Migrating from oc-mirror plugin v1 to v2
4+
include::_attributes/common-attributes.adoc[]
5+
:context: oc-mirror-migration-v1-to-v2
6+
7+
toc::[]
8+
9+
The oc-mirror v2 plugin introduces major changes to image mirroring workflows. This guide provides step-by-step instructions for migration while ensuring compatibility with oc-mirror plugin v2.
10+
11+
[IMPORTANT]
12+
====
13+
You must manually update the configurations by modifying the API version and removing deprecated fields. For more information, see "Changes from oc-mirror plugin v1 to v2".
14+
====
15+
16+
// Differences between oc-mirror plugin v1 and v2
17+
include::modules/oc-mirror-migration-differences.adoc[leveloffset=+1]
18+
19+
// Migrating from oc-mirror plugin v1 to oc-mirror plugin v2
20+
include::modules/oc-mirror-migration-process.adoc[leveloffset=+1]
21+
22+
[role="_additional-resources"]
23+
[id="additional-resources_{context}"]
24+
== Additional resources
25+
26+
* xref:../../disconnected/mirroring/about-installing-oc-mirror-v2#oc-mirror-workflows-partially-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a partially disconnected environment]
27+
* xref:../../disconnected/mirroring/about-installing-oc-mirror-v2#oc-mirror-workflows-fully-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a fully disconnected environment]
28+
* For details regarding configuration changes, see xref:../../disconnected/mirroring/oc-mirror-migration-v1-to-v2#oc-mirror-migration-differences_oc-mirror-migration-v1-to-v2[Changes from oc-mirror plugin v1 to v2].
29+
* For more information about deleting images, see xref:../../disconnected/mirroring/about-installing-oc-mirror-v2#oc-mirror-procedure-delete-v2_about-installing-oc-mirror-v2[Deletion of images from your disconnected environment].

‎modules/oc-mirror-migration-differences.adoc

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * disconnected/mirroring/oc-mirror-migration-v1-to-v2.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="oc-mirror-migration-differences_{context}"]
7+
= Changes from oc-mirror plugin v1 to v2
8+
9+
Before migrating from oc-mirror plugin v1 to v2, see the following differences between oc-mirror plugin v1 and v2:
10+
11+
* Explicit version selection: Users must explicitly specify `--v2` when using `oc-mirror`. If no version is specified, v1 is executed by default. This behavior is expected to change in future releases, where `--v2` will be the default.
12+
13+
* Updated commands: Commands for mirroring workflows have changed to align with oc-mirror plugin v2's new workflow.
14+
15+
** For mirror-to-disk, run the following command:
16+
+
17+
[source,terminal]
18+
----
19+
$ oc-mirror --config isc.yaml file://<directory_name> --v2
20+
----
21+
22+
** For disk-to-mirror, run the following command:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc-mirror --config isc.yaml --from file://<directory_name> docker://<remote_registry> --v2
27+
----
28+
29+
** For mirror-to-mirror, run the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ oc-mirror --config isc.yaml --workspace file://<directory_name> docker://<remote_registry> --v2
34+
----
35+
+
36+
[NOTE]
37+
====
38+
`--workspace` is now required for mirror-to-mirror operation.
39+
====
40+
41+
* API version update: The `ImageSetConfiguration` API version changes from `v1alpha2` (v1) to `v2alpha1` (v2). You must manually update the configuration files before migration.
42+
43+
* Configuration changes:
44+
- `storageConfig` must be removed in oc-mirror plugin v2.
45+
- Incremental mirroring is now handled automatically through the working directory or local cache.
46+
47+
* Changes in results directory: All custom resources to be applied to the disconnected cluster are generated in the `<workspace_path>/working-dir/cluster-resources` directory after the migration.
48+
- Outputs in oc-mirror plugin v2 are not stored in the same location as oc-mirror plugin v1.
49+
- You must check the `cluster-resources` folder under the working directory for the following resources:
50+
** `ImageDigestMirrorSet` (IDMS)
51+
** `ImageTagMirrorSet` (ITMS)
52+
** `CatalogSource`
53+
** `ClusterCatalog`
54+
** `UpdateService`
55+
56+
* Workspace and directory naming: Follow the new oc-mirror v2 convention to prevent any potential data inconsistencies when transitioning between versions.
57+
- The oc-mirror plugin v1 `oc-mirror-workspace` directory is no longer needed.
58+
- Use a new directory for oc-mirror plugin v2 to avoid conflicts.
59+
60+
* Replacing `ImageContentSourcePolicy` (ICSP) resources with IDMS/ITMS:
61+
+
62+
[IMPORTANT]
63+
====
64+
Deleting all `ImageContentSourcePolicy` (ICSP) resources might remove configurations unrelated to oc-mirror.
65+
66+
To avoid unintended deletions, identify ICSP resources generated by oc-mirror before removing them. If you are unsure, check with your cluster administrator. For more information, see "Mirroring images for a disconnected installation by using the oc-mirror plugin v2".
67+
====
68+
69+
- In oc-mirror plugin v2, the ICSP resource is replaced by `ImageDigestMirrorSet` (IDMS) and `ImageTagMirrorSet` (ITMS) resources.

‎modules/oc-mirror-migration-process.adoc

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * disconnected/mirroring/oc-mirror-migration-v1-to-v2.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="oc-mirror-migration-process_{context}"]
7+
= Migrating to oc-mirror plugin v2
8+
9+
To migrate from oc-mirror plugin v1 to v2, you must manually update the `ImageSetConfiguration` file, modify mirroring commands, and clean up v1 artifacts. Follow these steps to complete the migration.
10+
11+
.Procedure
12+
13+
. Modify the API version and remove deprecated fields in your `ImageSetConfiguration`.
14+
+
15+
.Example `ImageSetConfiguration` file with oc-mirror plugin v1 configuration
16+
[source,yaml]
17+
----
18+
kind: ImageSetConfiguration
19+
apiVersion: mirror.openshift.io/v1alpha2
20+
mirror:
21+
platform:
22+
channels:
23+
- name: stable-4.17
24+
graph: true
25+
helm:
26+
repositories:
27+
- name: sbo
28+
url: https://redhat-developer.github.io/service-binding-operator-helm-chart/
29+
additionalImages:
30+
- name: registry.redhat.io/ubi8/ubi:latest
31+
- name: quay.io/openshifttest/hello-openshift@sha256:example_hash
32+
operators:
33+
- catalog: oci:///test/redhat-operator-index
34+
packages:
35+
- name: aws-load-balancer-operator
36+
storageConfig: # REMOVE this field in v2
37+
local:
38+
path: /var/lib/oc-mirror
39+
----
40+
+
41+
.Example `ImageSetConfiguration` file with oc-mirror plugin v2 configuration
42+
[source,yaml]
43+
----
44+
kind: ImageSetConfiguration
45+
apiVersion: mirror.openshift.io/v2alpha1
46+
mirror:
47+
platform:
48+
channels:
49+
- name: stable-4.17
50+
graph: true
51+
helm:
52+
repositories:
53+
- name: sbo
54+
url: https://redhat-developer.github.io/service-binding-operator-helm-chart/
55+
additionalImages:
56+
- name: registry.redhat.io/ubi8/ubi:latest
57+
- name: quay.io/openshifttest/hello-openshift@sha256:example_hash
58+
operators:
59+
- catalog: oci:///test/redhat-operator-index
60+
packages:
61+
- name: aws-load-balancer-operator
62+
----
63+
64+
. Check the `cluster-resources` directory inside the working directory for IDMS, ITMS, `CatalogSource`, and `ClusterCatalog` resources by running the following command:
65+
+
66+
[source,terminal]
67+
----
68+
$ ls <v2_workspace>/working-dir/cluster-resources/
69+
----
70+
71+
. Once the migration is complete, verify that mirrored images and catalogs are available:
72+
- Ensure that no errors or warnings occurred during mirroring.
73+
- Ensure that no error file was generated (`working-dir/logs/mirroring_errors_YYYYMMdd_HHmmss.txt`).
74+
75+
. Verify that mirrored images and catalogs are available using the following the commands:
76+
+
77+
[source,terminal]
78+
----
79+
$ oc get catalogsource -n openshift-marketplace
80+
----
81+
+
82+
[source,terminal]
83+
----
84+
$ oc get imagedigestmirrorset,imagetagmirrorset -n openshift-config
85+
----
86+
+
87+
For more information, refer to "Mirroring images for a disconnected installation using oc-mirror plugin v2".
88+
89+
. Optional: Remove images mirrored using oc-mirror plugin v1:
90+
91+
.. Mirror the images using oc-mirror plugin v1.
92+
93+
.. Update the API version in the `ImageSetConfiguration` file from `v1alpha2` (v1) to `v2alpha1` (v2), then run the following command:
94+
+
95+
[source,terminal]
96+
----
97+
$ oc-mirror -c isc.yaml file://some-dir --v2
98+
----
99+
+
100+
[NOTE]
101+
====
102+
`storageConfig` is not a valid field in the `ImageSetConfiguration` and `DeleteImageSetConfiguration` files. Remove this field when updating to oc-mirror plugin v2.
103+
====
104+
105+
.. Generate a delete manifest and delete v1 images by running the following command:
106+
+
107+
[source,terminal]
108+
----
109+
$ oc-mirror delete --config=delete-isc.yaml --generate --delete-v1-images --workspace file://some-dir docker://registry.example:5000 --v2
110+
----
111+
+
112+
[IMPORTANT]
113+
====
114+
oc-mirror plugin v2 does not automatically prune the destination registry, unlike oc-mirror plugin v1. To clean up images that are no longer needed, use the delete functionality in v2 with the `--delete-v1-images` command flag.
115+
116+
Once all images mirrored with oc-mirror plugin v1 are removed, you no longer need to use this flag. If you need to delete images mirrored with oc-mirror plugin v2, do not set `--delete-v1-images`.
117+
====
118+
+
119+
For more information about deleting images, see "Deletion of images from your disconnected environment".
120+
121+
.. Delete images based on the generated manifest by running the following command:
122+
+
123+
[source,terminal]
124+
----
125+
$ oc-mirror delete --delete-yaml-file some-dir/working-dir/delete/delete-images.yaml docker://registry.example:5000 --v2
126+
----

‎modules/oc-mirror-workflows-delete-v2.adoc

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,13 @@ For more information, see "Resolving storage cleanup issues in the distribution
5959

6060
[IMPORTANT]
6161
====
62-
To skip deleting the Operator catalog image while you are deleting Operator images, you must list the specific Operators under the Operator catalog image in the `DeleteImageSetConfiguration` file. This ensures that only the specified Operators are deleted, not the catalog image.
63-
62+
* To skip deleting the Operator catalog image while you are deleting Operator images, you must list the specific Operators under the Operator catalog image in the `DeleteImageSetConfiguration` file. This ensures that only the specified Operators are deleted, not the catalog image.
63+
+
6464
If only the Operator catalog image is specified, all Operators within that catalog, as well as the catalog image itself, will be deleted.
65+
66+
* oc-mirror plugin v2 does not delete Operator catalog images automatically because other Operators may still be deployed and depend on these images.
67+
+
68+
If you are certain that no Operators from a catalog remain in the registry or cluster, you can explicitly add the catalog image to `additionalImages` in `DeleteImageSetConfiguration` to remove it.
69+
70+
* Garbage collection behavior depends on the registry. Some registries do not automatically remove deleted images, requiring a system administrator to manually trigger garbage collection to free up space.
6571
====

0 commit comments

Comments
 (0)