Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Migrating from oc-mirror plugin v1 to v2

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.

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

Before migrating from oc-mirror plugin v1 to v2, see the following differences between oc-mirror plugin v1 and v2:

  • 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.

  • Updated commands: Commands for mirroring workflows have changed to align with oc-mirror plugin v2’s new workflow.

    • For mirror-to-disk, run the following command:

      $ oc-mirror --config isc.yaml file://<directory_name> --v2

    • For disk-to-mirror, run the following command:

      $ oc-mirror --config isc.yaml --from file://<directory_name> docker://<remote_registry> --v2

    • For mirror-to-mirror, run the following command:

      $ oc-mirror --config isc.yaml --workspace file://<directory_name> docker://<remote_registry> --v2

      --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 <workspace_path>/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:

    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

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.

Procedure

  1. Modify the API version and remove deprecated fields in your ImageSetConfiguration.

    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
    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

  2. Check the cluster-resources directory inside the working directory for IDMS, ITMS, CatalogSource, and ClusterCatalog resources by running the following command:

    $ ls <v2_workspace>/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:

    $ oc get catalogsource -n openshift-marketplace
    $ oc get imagedigestmirrorset,imagetagmirrorset -n openshift-config

    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:

      $ oc-mirror -c isc.yaml file://some-dir --v2

      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:

      $ oc-mirror delete --config=delete-isc.yaml --generate --delete-v1-images --workspace file://some-dir docker://registry.example:5000  --v2

      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:

      $ oc-mirror delete --delete-yaml-file some-dir/working-dir/delete/delete-images.yaml docker://registry.example:5000 --v2

Additional resources