OSDOCS 8197: Added delete, dry run, and enclave support functionality for oc-mirror v2 #77289
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,53 +1,85 @@ | ||
| :_mod-docs-content-type: ASSEMBLY | ||
| [id="about-installing-oc-mirror-v2"] | ||
| = Mirroring images for a disconnected installation by using the oc-mirror plugin v2 | ||
| include::_attributes/common-attributes.adoc[] | ||
| :context: installing-mirroring-disconnected | ||
|
|
||
| toc::[] | ||
|
|
||
| You can run your cluster in a restricted network without direct internet connectivity if you install the cluster from a mirrored set of {product-title} container images in a private registry. This registry must be running whenever your cluster is running. | ||
|
|
||
| Just as you can use the `oc-mirror` OpenShift CLI (`oc`) plugin, you can also use oc-mirror plugin v2 to mirror images to a mirror registry in your fully or partially disconnected environments. To download the required images from the official Red Hat registries, you must run oc-mirror plugin v2 from a system with internet connectivity. | ||
|
|
||
| :FeatureName: oc-mirror plugin v2 | ||
| include::snippets/technology-preview.adoc[] | ||
|
|
||
| [id="prerequisites_oc-mirror-v2_{context}"] | ||
| == Prerequisites | ||
|
|
||
| * You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker V2-2] in the location that hosts the {product-title} cluster, such as {quay}. | ||
| + | ||
| [NOTE] | ||
| ==== | ||
| If you use {quay}, use version 3.6 or later with the oc-mirror plugin. See the documentation on link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying the Red Hat Quay Operator on OpenShift Container Platform (Red Hat Quay documentation)]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support. | ||
| ==== | ||
|
|
||
| [Optional] | ||
| * If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry. You can use this registry to mirror the necessary container images of {product-title} for disconnected installations. | ||
|
|
||
| * Every machine in the provisioned clusters must have access to the mirror registry. If the registry is unreachable, tasks like installation, updating, or routine operations such as workload relocation, might fail. Mirror registries must be operated in a highly available manner, ensuring their availability aligns with the production availability of your {product-title} clusters. | ||
|
|
||
| .High level workflow | ||
|
There was a problem hiding this comment. This to me feels out of place with a prereq section. I think it would be better in the opening assembly text or a separate module. There was a problem hiding this comment. Other procedures have this prereq as well. I can remove this here. |
||
|
|
||
| The following steps outline the high-level workflow on how to mirror images to a mirror registry by using the oc-mirror plugin v2: | ||
|
|
||
| . Create an image set configuration file. | ||
|
|
||
| . Mirror the image set to the target mirror registry by using one of the following workflows: | ||
|
|
||
| ** Mirror an image set directly to the target mirror registry (Mirror-to-Mirror). | ||
|
|
||
| ** Mirror an image set to disk (Mirror-to-Disk), transfer the `tar` file to the target environment, then mirror the image set to the target mirror registry (Disk-to-Mirror). | ||
|
|
||
| . Configure your cluster to use the resources generated by the oc-mirror plugin v2. | ||
|
|
||
| . Repeat these steps to update your target mirror registry as necessary. | ||
|
|
||
|
|
||
| // About oc-mirror plugin v2 | ||
| include::modules/oc-mirror-v2-about.adoc[leveloffset=+1] | ||
|
|
||
| // oc-mirror compatibility and support | ||
| include::modules/oc-mirror-v2-support.adoc[leveloffset=+2] | ||
|
|
||
| //Delete Feature | ||
| // workflows of delete feature | ||
| include::modules/oc-mirror-workflows-delete-v2.adoc[leveloffset=+1] | ||
|
|
||
| // procedure for delete feature | ||
| include::modules/oc-mirror-procedure-delete-v2.adoc[leveloffset=+2] | ||
|
|
||
| // About dry-run | ||
| include::modules/oc-mirror-v2-about-dry-run.adoc[leveloffset=+1] | ||
|
|
||
| // Performing Dry-run for V2 | ||
| include::modules/oc-mirror-dry-run-v2.adoc[leveloffset=+2] | ||
|
|
||
| //oc-mirror-enclave-support-about | ||
| include::modules//oc-mirror-enclave-support-about.adoc[leveloffset=+1] | ||
|
|
||
| // How to mirror to an Enclave | ||
| include::modules/oc-mirror-enclave-support.adoc[leveloffset=+2] | ||
|
|
||
| [id="additional-resources"] | ||
| == Additional resources | ||
|
|
||
| * xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.html[Updating a cluster in a disconnected environment using the OpenShift Update Service]. | ||
|
|
||
| //operator catalog filtering | ||
| include::modules/oc-mirror-operator-catalog-filtering.adoc[leveloffset=+1] | ||
|
|
||
| //Image set configuration parameters | ||
| 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] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,80 @@ | ||||||
| // Module included in the following assemblies: | ||||||
| // | ||||||
| // * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc | ||||||
|
|
||||||
|
|
||||||
| :_mod-docs-content-type: REFERENCE | ||||||
| [id="oc-mirror-command-reference-v2_{context}"] | ||||||
| = Command reference for oc-mirror plugin v2 | ||||||
|
|
||||||
| The following tables describe the `oc mirror` subcommands and flags for oc-mirror plugin v2: | ||||||
subhtk marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| .Subcommands and flags for the oc-mirror plugin v2: | ||||||
| [cols="1,2",options="header"] | ||||||
| |=== | ||||||
| |Subcommand | ||||||
| |Description | ||||||
|
|
||||||
| |`help` | ||||||
| |Show help about any subcommand | ||||||
|
There was a problem hiding this comment.
Suggested change
Add a closing full stop for all description entries? There was a problem hiding this comment. It was suggested not to add. |
||||||
|
|
||||||
| |`version` | ||||||
| |Output the oc-mirror version | ||||||
|
|
||||||
| |`delete` | ||||||
| |Deletes images in remote registry and local cache. | ||||||
|
|
||||||
| |=== | ||||||
|
|
||||||
| .oc mirror flags | ||||||
| [cols="1,2",options="header"] | ||||||
| |=== | ||||||
| |Flag | ||||||
| |Description | ||||||
|
|
||||||
| |`--authfile` | ||||||
| |Displays the string path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`. | ||||||
|
|
||||||
| |`-c`, `--config` `<string>` | ||||||
| |Specifies the path to an image set configuration file. | ||||||
|
|
||||||
| |`--dest-tls-verify` | ||||||
| |Requires HTTPS and verifies certificates when accessing the container registry or daemon. | ||||||
|
|
||||||
| |`--dry-run` | ||||||
| |Prints actions without mirroring images | ||||||
|
|
||||||
| |`--from <string>` | ||||||
| |Specifies the path to an image set archive that was generated by executing oc-mirror plugin v2 to load a target registry. | ||||||
|
|
||||||
| |`-h`, `--help` | ||||||
| |Displays help | ||||||
|
|
||||||
| |`--loglevel` | ||||||
| |Displays string log levels. Supported values include info, debug, trace, error. The default is `info`. | ||||||
|
|
||||||
| |`-p`, `--port` | ||||||
| |Determines the HTTP port used by oc-mirror plugin v2 local storage instance. The default is `55000`. | ||||||
|
|
||||||
| |`--max-nested-paths <int>` | ||||||
| |Specifies the maximum number of nested paths for destination registries that limit nested paths. The default is `0`. | ||||||
|
|
||||||
| |`--secure-policy` | ||||||
| |Default value is `false`. If you set a non-default value, the command enables signature verification, which is the secure policy for signature verification. | ||||||
|
|
||||||
| |`--since` | ||||||
| |Includes all new content since a specified date (format: `yyyy-mm-dd`). When not provided, new content since previous mirroring is mirrored. | ||||||
|
|
||||||
| |`--src-tls-verify` | ||||||
| |Requires HTTPS and verifies certificates when accessing the container registry or daemon. | ||||||
|
|
||||||
| |`--strict-archive` | ||||||
| |Default value is `false`. If you set a value, the command generates archives that are strictly less than the `archiveSize` that was set in the `imageSetConfig` custom resource (CR). Mirroring exist in error if a file being archived exceeds `archiveSize` (GB). | ||||||
|
|
||||||
| |`-v`, `--version` | ||||||
| |Displays the version for oc-mirror plugin v2. | ||||||
|
|
||||||
| |`--workspace` | ||||||
| |Determines string oc-mirror plugin v2 workspace where resources and internal artifacts are generated. | ||||||
|
|
||||||
| |=== | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc | ||
|
|
||
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="oc-mirror-dry-run-v2_{context}"] | ||
| = Performing dry run for oc-mirror plugin v2 | ||
|
|
||
| To perform a dry run and verify your image set configuration without mirroring any images, follow the procedure. | ||
|
|
||
| .Procedure | ||
|
|
||
| * To perform a test run, run the `oc mirror` command and append the `--dry-run` argument to the command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc mirror -c <image_set_config_yaml> --from file://<oc_mirror_workspace_path> docker://<mirror_registry_url> --dry-run --v2 | ||
| ---- | ||
subhtk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Where: | ||
| - `<image_set_config_yaml>`: Use the image set configuration file that you just created. | ||
| - `<oc_mirror_workspace_path>`: Insert the address of the workspace path. | ||
| - `<mirror_registry_url>`: Insert the URL or address of the remote container registry from which images will be deleted. | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| $ oc mirror --config /tmp/isc_dryrun.yaml file://<oc_mirror_workspace_path> --dry-run --v2 | ||
|
|
||
| [INFO] : :warning: --v2 flag identified, flow redirected to the oc-mirror v2 version. This is Tech Preview, it is still under development and it is not production ready. | ||
| [INFO] : :wave: Hello, welcome to oc-mirror | ||
| [INFO] : :gear: setting up the environment for you... | ||
| [INFO] : :twisted_rightwards_arrows: workflow mode: mirrorToDisk | ||
| [INFO] : :sleuth_or_spy: going to discover the necessary images... | ||
| [INFO] : :mag: collecting release images... | ||
| [INFO] : :mag: collecting operator images... | ||
| [INFO] : :mag: collecting additional images... | ||
| [WARN] : :warning: 54/54 images necessary for mirroring are not available in the cache. | ||
| [WARN] : List of missing images in : CLID-19/working-dir/dry-run/missing.txt. | ||
| please re-run the mirror to disk process | ||
| [INFO] : :page_facing_up: list of all images for mirroring in : CLID-19/working-dir/dry-run/mapping.txt | ||
| [INFO] : mirror time : 9.641091076s | ||
| [INFO] : :wave: Goodbye, thank you for using oc-mirror | ||
| ---- | ||
|
|
||
| .Verification | ||
|
|
||
| . Navigate to the workspace directory that was generated: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ cd <oc_mirror_workspace_path> | ||
| ---- | ||
|
|
||
| . Review the `mapping.txt` and `missing.txt` files that were generated. These files contain a list of all images that would be mirrored. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| // Module included in the following assemblies: | ||
| // | ||
| // * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc | ||
|
|
||
| :_mod-docs-content-type: CONCEPT | ||
| [id="oc-mirror-enclave-support-about_{context}"] | ||
| = Benefits of enclave support | ||
|
|
||
| Enclave support restricts internal access to a specific part of a network. Unlike a demilitarized zone (DMZ) network, which allows inbound and outbound traffic access through firewall boundaries, enclaves do not cross firewall boundaries. | ||
|
|
||
| :FeatureName: Enclave Support | ||
| include::snippets/technology-preview.adoc[] | ||
subhtk marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The new enclave support functionality is for scenarios where mirroring is needed for multiple enclaves that are secured behind at least one intermediate disconnected network. | ||
|
|
||
| Enclave support has the following benefits: | ||
|
|
||
| * You can mirror content for multiple enclaves and centralize it in a single internal registry. Because some customers want to run security checks on the mirrored content, with this setup they can run these checks all at once. The content is then vetted before being mirrored to downstream enclaves. | ||
|
|
||
| * You can mirror content directly from the centralized internal registry to enclaves without restarting the mirroring process from the internet for each enclave. | ||
|
|
||
| * You can minimize data transfer between network stages, so to ensure that a blob or image is transferred only once from one stage to another. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.