Merge pull request #63332 from GroceryBoyJr/install-config-yaml

OCPBUGS-10304: Document oc-mirror command for creating ImageContentSou…

Author: jab-rh

modules/installation-bare-metal-config-yaml.adoc

@@ -298,7 +298,14 @@ ifdef::ibm-z,ibm-z-kvm[]
 <15> Add the `additionalTrustBundle` parameter and value. The value must be the contents of the certificate file that you used for your mirror registry. The certificate file can be an existing, trusted certificate authority or the self-signed certificate that you generated for the mirror registry.
 endif::ibm-z,ibm-z-kvm[]
 ifndef::openshift-origin[]
-<16> Provide the `imageContentSources` section from the output of the command to mirror the repository.
+<16> Provide the `imageContentSources` section according to the output of the command that you used to mirror the repository. 
++
+[IMPORTANT]
+====
+* When using the `oc adm release mirror` command, use the output from the `imageContentSources` section.
+* When using `oc mirror` command, use the `repositoryDigestMirrors` section of the `ImageContentSourcePolicy` file that results from running the command.
+* `ImageContentSourcePolicy` is deprecated. For more information see _Configuring image registry repository mirroring_. 
+====
 endif::openshift-origin[]
 ifdef::openshift-origin[]
 <15> Provide the `imageContentSources` section from the output of the command to mirror the repository.

modules/installation-initializing-manual.adoc

@@ -144,16 +144,26 @@ it in the `<installation_directory>`.
 ====
 You must name this configuration file `install-config.yaml`.
 ====
++
 ifdef::restricted,restricted-upi[]
++
 ** Unless you use a registry that {op-system} trusts by default, such as
 `docker.io`, you must provide the contents of the certificate for your mirror
 repository in the `additionalTrustBundle` section. In most cases, you must
 provide the certificate for your mirror.
 ** You must include the `imageContentSources` section from the output of the command to
 mirror the repository.
++
+[IMPORTANT]
+====
+** The `ImageContentSourcePolicy` file is generated as an output of `oc mirror` after the mirroring process is finished.
+** The `oc mirror` command generates an `ImageContentSourcePolicy` file which contains the YAML needed to define `ImageContentSourcePolicy`.
+Copy the text from this file and paste it into your `install-config.yaml` file. 
+** You must run the 'oc mirror' command twice. The first time you run the `oc mirror` command, you get a full `ImageContentSourcePolicy` file. The second time you run the `oc mirror` command, you only get the difference between the first and second run.
+Because of this behavior, you must always keep a backup of these files in case you need to merge them into one complete `ImageContentSourcePolicy` file. Keeping a backup of these two output files ensures that you have a complete `ImageContentSourcePolicy` file.
+====
 endif::restricted,restricted-upi[]
 +
-
 ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,ash-default,ash-network,gcp-shared,ibm-cloud-private,ibm-power-vs-private[]
 [NOTE]
 ====
@@ -272,4 +282,4 @@ endif::[]
 ifeval::["{context}" == "installing-ibm-power-vs-private-cluster"]
 :!ibm-power-vs-private:
 endif::[]
-:!platform:
+:!platform:

modules/oc-mirror-mirror-to-mirror.adoc

@@ -40,6 +40,11 @@ $ oc mirror --config=./imageset-config.yaml \// <1>
 . Navigate into the `oc-mirror-workspace/` directory that was generated.
 . Navigate into the results directory, for example, `results-1639608409/`.
 . Verify that YAML files are present for the `ImageContentSourcePolicy` and `CatalogSource` resources.
+
+[NOTE]
+====
+The `repositoryDigestMirrors` section of the `ImageContentSourcePolicy` YAML file is used for the `install-config.yaml` file during installation.
+====
 +
 // TODO: Test and get some better wording/example output.