--- title: Migrating from oc-mirror plugin v1 to v2 --- # Migrating from oc-mirror plugin v1 to v2 {#oc-mirror-migration-v1-to-v2} The oc-mirror v2 plugin introduces major changes to image mirroring workflows. Understand the migration process and check for compatibility with oc-mirror plugin v2 to ensure a successful migration. > [!IMPORTANT] > 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". ## Changes from oc-mirror plugin v1 to v2 {#oc-mirror-migration-differences_oc-mirror-migration-v1-to-v2} Before migrating from oc-mirror plugin v1 to v2, you must review the updated mirroring workflow commands, which have changed to align with the new v2 workflow. - For mirror-to-disk, run the following command: ```terminal $ oc-mirror --config isc.yaml file:// --v2 ``` - For disk-to-mirror, run the following command: ```terminal $ oc-mirror --config isc.yaml --from file:// docker:// --v2 ``` - For mirror-to-mirror, run the following command: ```terminal $ oc-mirror --config isc.yaml --workspace file:// docker:// --v2 ``` > [!NOTE] > `--workspace` is now required for mirror-to-mirror operation. - API version update: The `ImageSetConfiguration` API version changes from `v1alpha2` (v1) to `v2alpha1` (v2). You must manually update the configuration files before migration. - Configuration changes: - `storageConfig` must be removed in oc-mirror plugin v2. - Incremental mirroring is now handled automatically through the working directory or local cache. - Changes in results directory: All custom resources to be applied to the disconnected cluster are generated in the `/working-dir/cluster-resources` directory after the migration. - Outputs in oc-mirror plugin v2 are not stored in the same location as oc-mirror plugin v1. - You must check the `cluster-resources` folder under the working directory for the following resources: - `ImageDigestMirrorSet` (IDMS) - `ImageTagMirrorSet` (ITMS) - `CatalogSource` - `ClusterCatalog` - `UpdateService` - Workspace and directory naming: Follow the new oc-mirror v2 convention to prevent any potential data inconsistencies when transitioning between versions. - The oc-mirror plugin v1 `oc-mirror-workspace` directory is no longer needed. - Use a new directory for oc-mirror plugin v2 to avoid conflicts. - Replacing `ImageContentSourcePolicy` (ICSP) resources with IDMS/ITMS: > [!IMPORTANT] > Deleting all `ImageContentSourcePolicy` (ICSP) resources might remove configurations unrelated to oc-mirror. > > 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". - In oc-mirror plugin v2, the ICSP resource is replaced by `ImageDigestMirrorSet` (IDMS) and `ImageTagMirrorSet` (ITMS) resources. ## Migrating to oc-mirror plugin v2 {#oc-mirror-migration-process_oc-mirror-migration-v1-to-v2} To migrate from oc-mirror plugin v1 to v2, you must manually update the `ImageSetConfiguration` file, modify mirroring commands, and clean up v1 artifacts. **Procedure** 1. Modify the API version and remove deprecated fields in your `ImageSetConfiguration`. ```yaml {title="Example ImageSetConfiguration file with oc-mirror plugin v1 configuration"} kind: ImageSetConfiguration apiVersion: mirror.openshift.io/v1alpha2 mirror: platform: channels: - name: stable-4.17 graph: true helm: repositories: - name: sbo url: https://redhat-developer.github.io/service-binding-operator-helm-chart/ additionalImages: - name: registry.redhat.io/ubi8/ubi:latest - name: quay.io/openshifttest/hello-openshift@sha256:example_hash operators: - catalog: oci:///test/redhat-operator-index packages: - name: aws-load-balancer-operator storageConfig: # REMOVE this field in v2 local: path: /var/lib/oc-mirror ``` ```yaml {title="Example ImageSetConfiguration file with oc-mirror plugin v2 configuration"} kind: ImageSetConfiguration apiVersion: mirror.openshift.io/v2alpha1 mirror: platform: channels: - name: stable-4.17 graph: true helm: repositories: - name: sbo url: https://redhat-developer.github.io/service-binding-operator-helm-chart/ additionalImages: - name: registry.redhat.io/ubi8/ubi:latest - name: quay.io/openshifttest/hello-openshift@sha256:example_hash operators: - catalog: oci:///test/redhat-operator-index packages: - name: aws-load-balancer-operator ``` > [!NOTE] > When migrating from oc-mirror plugin v1 to v2, you must use explicit registry hostnames for all images listed under `additionalImages`. Otherwise, images are mirrored to incorrect target paths. 2. Check the `cluster-resources` directory inside the working directory for IDMS, ITMS, `CatalogSource`, and `ClusterCatalog` resources by running the following command: ```terminal $ ls /working-dir/cluster-resources/ ``` 3. Once the migration is complete, verify that mirrored images and catalogs are available: - Ensure that no errors or warnings occurred during mirroring. - Ensure that no error file was generated (`working-dir/logs/mirroring_errors_YYYYMMdd_HHmmss.txt`). 4. Verify that mirrored images and catalogs are available using the following the commands: ```terminal $ oc get catalogsource -n openshift-marketplace ``` ```terminal $ oc get imagedigestmirrorset,imagetagmirrorset ``` For more information, refer to "Mirroring images for a disconnected installation using oc-mirror plugin v2". 5. Optional: Remove images mirrored using oc-mirror plugin v1: 1. Mirror the images using oc-mirror plugin v1. 2. Update the API version in the `ImageSetConfiguration` file from `v1alpha2` (v1) to `v2alpha1` (v2), then run the following command: ```terminal $ oc-mirror -c isc.yaml file://some-dir --v2 ``` > [!NOTE] > `storageConfig` is not a valid field in the `ImageSetConfiguration` and `DeleteImageSetConfiguration` files. Remove this field when updating to oc-mirror plugin v2. 3. Generate a delete manifest and delete v1 images by running the following command: ```terminal $ oc-mirror delete --config=delete-isc.yaml --generate --delete-v1-images --workspace file://some-dir docker://registry.example:5000 --v2 ``` > [!IMPORTANT] > 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. > > 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`. For more information about deleting images, see "Deletion of images from your disconnected environment". 4. Delete images based on the generated manifest by running the following command: ```terminal $ oc-mirror delete --delete-yaml-file some-dir/working-dir/delete/delete-images.yaml docker://registry.example:5000 --v2 ``` **Additional resources** {._additional-resources} - [Mirroring an image set in a partially disconnected environment](/openshift-docs-markdown/disconnected/about-installing-oc-mirror-v2#oc-mirror-workflows-partially-disconnected-v2_about-installing-oc-mirror-v2) - [Mirroring an image set in a fully disconnected environment](/openshift-docs-markdown/disconnected/about-installing-oc-mirror-v2#oc-mirror-workflows-fully-disconnected-v2_about-installing-oc-mirror-v2) - [Changes from oc-mirror plugin v1 to v2](/openshift-docs-markdown/disconnected/oc-mirror-migration-v1-to-v2#oc-mirror-migration-differences_oc-mirror-migration-v1-to-v2) - [Deletion of images from your disconnected environment](/openshift-docs-markdown/disconnected/about-installing-oc-mirror-v2#oc-mirror-procedure-delete-v2_about-installing-oc-mirror-v2)