diff --git a/modules/installation-about-mirror-registry.adoc b/modules/installation-about-mirror-registry.adoc index 2a487b4cf7e7..c571a8999aee 100644 --- a/modules/installation-about-mirror-registry.adoc +++ b/modules/installation-about-mirror-registry.adoc @@ -17,6 +17,9 @@ endif::[] [id="installation-about-mirror-registry_{context}"] = About the mirror registry +[role="_abstract"] +You must have access to the internet to obtain the necessary container images. Using an alternative registry means that you place the mirror registry on a mirror host that has access to both your network and the internet. + ifndef::oc-mirror[] You can mirror the images that are required for {product-title} installation and subsequent product updates to a container mirror registry such as {quay}, JFrog Artifactory, Sonatype Nexus Repository, or Harbor. If you do not have access to a large-scale container registry, you can use the _mirror registry for Red{nbsp}Hat OpenShift_, a small-scale container registry included with {product-title} subscriptions. @@ -41,7 +44,7 @@ For mirrored registries, to view the source of pulled images, you must review th [NOTE] ==== -Red Hat does not test third party registries with {product-title}. +Red{nbsp}Hat does not test third party registries with {product-title}. ==== ifeval::["{context}" == "installing-mirroring-disconnected"] diff --git a/modules/installation-adding-registry-pull-secret.adoc b/modules/installation-adding-registry-pull-secret.adoc index f0b3ce1f5528..435eccec6856 100644 --- a/modules/installation-adding-registry-pull-secret.adoc +++ b/modules/installation-adding-registry-pull-secret.adoc @@ -29,7 +29,8 @@ endif::[] [id="installation-adding-registry-pull-secret_{context}"] = Configuring credentials that allow images to be mirrored -Create a container image registry credentials file that enables you to mirror images from Red{nbsp}Hat to your mirror. +[role="_abstract"] +Create a container image registry credentials file so that you can mirror images from Red{nbsp}Hat to your mirror. Complete the following steps on the installation host. ifdef::restricted[] [WARNING] @@ -54,9 +55,6 @@ ifdef::restricted[] endif::restricted[] .Procedure - -Complete the following steps on the installation host: - ifndef::openshift-origin[] . Download your `registry.redhat.io` {cluster-manager-url-pull}. @@ -64,9 +62,10 @@ ifndef::openshift-origin[] + [source,terminal] ---- -$ cat ./pull-secret | jq . > / <1> +$ cat ./pull-secret | jq . > / ---- -<1> Specify the path to the folder to store the pull secret in and a name for the JSON file that you create. ++ +Specify the path to the directory to store the pull secret in and a name for the JSON file that you create. + .Example pull secret [source,json] @@ -92,9 +91,13 @@ $ cat ./pull-secret | jq . > / <1> } } ---- ++ +-- // An additional step for following this procedure when using oc-mirror as part of the disconnected install process. ifdef::oc-mirror[] +-- . Save the file as either `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`: + .. If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command: + [source,terminal] @@ -103,6 +106,7 @@ $ mkdir -p ---- + Where `` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`. + .. Copy the pull secret to the appropriate directory by entering the following command: + [source,terminal] @@ -110,12 +114,15 @@ Where `` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`. $ cp / / ---- + -Where `` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `` is either `config.json` or `auth.json`. +The `` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `` is either `config.json` or `auth.json` +-- endif::oc-mirror[] // Similar to the additional step above, except it is framed as optional because it is included in a disconnected update page (where users may or may not use oc-mirror for their process) ifdef::update-oc-mirror[] + . Optional: If using the oc-mirror plugin, save the file as either `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`: -.. If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command: + +** If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command: + [source,terminal] ---- @@ -123,7 +130,8 @@ $ mkdir -p ---- + Where `` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`. -.. Copy the pull secret to the appropriate directory by entering the following command: + +** Copy the pull secret to the appropriate directory by entering the following command: + [source,terminal] ---- @@ -131,10 +139,12 @@ $ cp / / ---- + Where `` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `` is either `config.json` or `auth.json`. + endif::update-oc-mirror[] // Additional step for allowing this procedure for oc-mirror-v2 // Should this step below also have the "if you don't have this directory, create it using this command" substeps? ifdef::oc-mirror-v2[] + . If the `$XDG_RUNTIME_DIR/containers` directory does not exist, create one by entering the following command: + [source,terminal] @@ -145,14 +155,15 @@ $ mkdir -p $XDG_RUNTIME_DIR/containers . Save the pull secret file as `$XDG_RUNTIME_DIR/containers/auth.json`. endif::oc-mirror-v2[] endif::openshift-origin[] +-- . Generate the base64-encoded user name and password or token for your mirror registry by running the following command: + [source,terminal] ---- -$ echo -n ':' | base64 -w0 <1> +$ echo -n ':' | base64 -w0 ---- -<1> For `` and ``, specify the user name and password that you configured for your registry. +For `` and ``, specify the user name and password that you configured for your registry. + .Example output [source,terminal] @@ -167,17 +178,17 @@ ifdef::openshift-origin[] ---- { "auths": { - "": { <1> - "auth": "", <2> + "": { + "auth": "", "email": "you@example.com" } } } ---- -<1> Specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, -`registry.example.com` or `registry.example.com:8443` -<2> Specify the base64-encoded user name and password for -the mirror registry. ++ +* For the `` value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, `registry.example.com` or `registry.example.com:8443`. ++ +* For the `` value, specify the base64-encoded user name and password for the mirror registry. endif::openshift-origin[] @@ -187,16 +198,16 @@ ifndef::openshift-origin[] [source,json] ---- "auths": { - "": { <1> - "auth": "", <2> + "": { + "auth": "", "email": "you@example.com" } }, ---- -<1> Specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, -`registry.example.com` or `registry.example.com:8443` -<2> Specify the base64-encoded user name and password for -the mirror registry. ++ +* For the `` value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, `registry.example.com` or `registry.example.com:8443`. ++ +* For the `` value, specify the base64-encoded user name and password for the mirror registry. + .Example modified pull secret [source,json] diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc index f69bfbb35483..50d53d95cfbc 100644 --- a/modules/installation-mirror-repository.adoc +++ b/modules/installation-mirror-repository.adoc @@ -7,7 +7,8 @@ [id="installation-mirror-repository_{context}"] = Mirroring the {product-title} image repository -Mirror the {product-title} image repository to your registry to use during cluster installation or upgrade. +[role="_abstract"] +Mirror the {product-title} image repository to your registry to use during cluster installation or upgrade. Complete the following steps on the mirror host. .Prerequisites @@ -25,13 +26,10 @@ endif::[] ifdef::openshift-origin[] * You have created a pull secret for your mirror repository. endif::[] - * If you use self-signed certificates, you have specified a Subject Alternative Name in the certificates. .Procedure -Complete the following steps on the mirror host: - . Review the ifndef::openshift-origin[] link:https://access.redhat.com/downloads/content/290/[{product-title} downloads page] @@ -42,7 +40,8 @@ link:https://github.com/okd-project/okd/releases/[{product-title} releases page] to determine the version and tag of {product-title} that you want to install. endif::[] -. Set the required environment variables: +. Set the following required environment variables: + .. Export the release version: + [source,terminal] @@ -50,8 +49,7 @@ endif::[] $ OCP_RELEASE= ---- + -For ``, specify the tag that corresponds to the version of {product-title} to -install, such as `4.5.4`. +For ``, specify the tag that corresponds to the version of {product-title} to install, such as `4.20.1`. .. Export the local registry name and host port: + @@ -60,9 +58,7 @@ install, such as `4.5.4`. $ LOCAL_REGISTRY=':' ---- + -For ``, specify the registry domain name for your mirror -repository, and for ``, specify the port that it -serves content on. +For ``, specify the registry domain name for your mirror repository, and for ``, specify the port that it serves content on. .. Export the local repository name: + @@ -71,8 +67,7 @@ serves content on. $ LOCAL_REPOSITORY='' ---- + -For ``, specify the name of the repository to create in your -registry, such as `ocp4/openshift4`. +For ``, specify the name of the repository to create in your registry, such as `ocp4/openshift4`. .. Export the name of the repository to mirror: + @@ -122,19 +117,20 @@ ifndef::openshift-origin[] + [source,terminal] ---- -$ ARCHITECTURE= <1> +$ ARCHITECTURE= ---- -<1> Specify the architecture of the cluster, such as `x86_64`, `aarch64`, `s390x`, or `ppc64le`. - ++ +Specify the architecture of the cluster, such as `x86_64`, `aarch64`, `s390x`, or `ppc64le`. endif::[] .. Export the path to the directory to host the mirrored images: + [source,terminal] ---- -$ REMOVABLE_MEDIA_PATH= <1> +$ REMOVABLE_MEDIA_PATH= ---- -<1> Specify the full path, including the initial forward slash (/) character. ++ +Specify the full path, including the initial forward slash (/) character. ifndef::openshift-rosa,openshift-dedicated[] . Mirror the version images to the mirror registry: @@ -182,14 +178,14 @@ endif::[] + [source,terminal] ---- -$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} <1> +$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} ---- + -<1> For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images. +For the `REMOVABLE_MEDIA_PATH` variable, you must use the same path that you specified when you mirrored the images. + [IMPORTANT] ==== -Running `oc image mirror` might result in the following error: `error: unable to retrieve source image`. This error occurs when image indexes include references to images that no longer exist on the image registry. Image indexes might retain older references to allow users running those images an upgrade path to newer points on the upgrade graph. As a temporary workaround, you can use the `--skip-missing` option to bypass the error and continue downloading the image index. For more information, see link:https://access.redhat.com/solutions/6975305[Service Mesh Operator mirroring failed]. +Running the `oc image mirror` command might result in the following error: `error: unable to retrieve source image`. This error occurs when image indexes include references to images that no longer exist on the image registry. Image indexes might retain older references to allow users running those images an upgrade path to newer points on the upgrade graph. As a temporary workaround, you can use the `--skip-missing` option to bypass the error and continue downloading the image index. For more information, see link:https://access.redhat.com/solutions/6975305[Service Mesh Operator mirroring failed]. ==== ** If the local container registry is connected to the mirror host, take the following actions: @@ -214,15 +210,14 @@ $ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ ---- endif::[] + -This command pulls the release information as a digest, and its output includes -the `imageContentSources` data that you require when you install your cluster. +This command pulls the release information as a digest, and its output includes the `imageContentSources` data that you require when you install your cluster. ... Record the entire `imageContentSources` section from the output of the previous command. The information about your mirrors is unique to your mirrored repository, and you must add the `imageContentSources` section to the `install-config.yaml` file during installation. + [NOTE] ==== -The image name gets patched to Quay.io during the mirroring process, and the podman images will show Quay.io in the registry on the bootstrap virtual machine. +The image name gets patched to Quay.io during the mirroring process, and the Podman images will show Quay.io in the registry on the bootstrap virtual machine. ==== . To create the installation program that is based on the content that you @@ -232,9 +227,10 @@ mirrored, extract it and pin it to the release: [source,terminal] ---- $ oc adm release extract -a ${LOCAL_SECRET_JSON} --icsp-file= --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}" \ ---insecure=true <1> +--insecure=true ---- -<1> Optional: If you do not want to configure trust for the target registry, add the `--insecure=true` flag. ++ +Optional: If you do not want to configure trust for the target registry, add the `--insecure=true` flag. ** If the local container registry is connected to the mirror host, run the following command: + @@ -253,9 +249,7 @@ endif::[] + [IMPORTANT] ==== -To ensure that you use the correct images for the version of {product-title} -that you selected, you must extract the installation program from the mirrored -content. +To ensure that you use the correct images for the version of {product-title} that you selected, you must extract the installation program from the mirrored content. You must perform this step on a machine with an active internet connection. ==== @@ -282,19 +276,16 @@ $ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} ---- + -This command pulls the release information as a digest, and its output includes -the `imageContentSources` data that you require when you install your cluster. +This command pulls the release information as a digest, and its output includes the `imageContentSources` data that you require when you install your cluster. -.. Record the entire `imageContentSources` section from the output of the previous -command. The information about your mirrors is unique to your mirrored repository, and you must add the `imageContentSources` section to the `install-config.yaml` file during installation. +.. Record the entire `imageContentSources` section from the output of the previous command. The information about your mirrors is unique to your mirrored repository, and you must add the `imageContentSources` section to the `install-config.yaml` file during installation. + [NOTE] ==== -The image name gets patched to Quay.io during the mirroring process, and the podman images will show Quay.io in the registry on the bootstrap virtual machine. +The image name gets patched to Quay.io during the mirroring process, and the Podman images show `quay.io` in the registry on the bootstrap virtual machine. ==== -. To create the installation program that is based on the content that you -mirrored, extract it and pin it to the release by running the following command: +. To create the installation program that is based on the content that you mirrored, extract it and pin it to the release by running the following command: + [source,terminal] ---- @@ -303,9 +294,7 @@ $ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${ + [IMPORTANT] ==== -To ensure that you use the correct images for the version of {product-title} -that you selected, you must extract the installation program from the mirrored -content. +To ensure that you use the correct images for the version of {product-title} that you selected, you must extract the installation program from the mirrored content. You must perform this step on a machine with an active internet connection. ==== diff --git a/modules/installation-restricted-network-samples.adoc b/modules/installation-restricted-network-samples.adoc index b4dece70fbbb..cdc2a33c6ccb 100644 --- a/modules/installation-restricted-network-samples.adoc +++ b/modules/installation-restricted-network-samples.adoc @@ -15,23 +15,22 @@ endif::[] [id="installation-restricted-network-samples_{context}"] = Using Cluster Samples Operator image streams with alternate or mirrored registries -Most image streams in the `openshift` namespace managed by the Cluster Samples Operator -point to images located in the Red Hat registry at link:https://registry.redhat.io[registry.redhat.io]. +[role="_abstract"] +You can use an alternate or mirror registry to host your images streams instead of using the Red{nbsp}Hat registry. + +Most image streams in the `openshift` namespace managed by the Cluster Samples Operator point to images located in the Red{nbsp}Hat registry at link:https://registry.redhat.io[registry.redhat.io]. ifdef::restrictednetwork[] -Mirroring -will not apply to these image streams. +Mirroring does not apply to these image streams. endif::[] [NOTE] ==== -The `cli`, `installer`, `must-gather`, and `tests` image streams, while -part of the install payload, are not managed by the Cluster Samples Operator. These are -not addressed in this procedure. +The `cli`, `installer`, `must-gather`, and `tests` image streams, while part of the install payload, are not managed by the Cluster Samples Operator. These are not addressed in this procedure. ==== [IMPORTANT] ==== -The Cluster Samples Operator must be set to `Managed` in a disconnected environment. To install the image streams, you have a mirrored registry. +The Cluster Samples Operator must be set to `Managed` in a disconnected environment. To install the image streams, you must have a mirrored registry. ==== .Prerequisites @@ -65,49 +64,40 @@ endif::[] $ oc image mirror registry.redhat.io/rhscl/ruby-25-rhel7:latest ${MIRROR_ADDR}/rhscl/ruby-25-rhel7:latest ---- -. Create the cluster's image configuration object: +. Create the image configuration object for the cluster by running the following command: + [source,terminal] ---- $ oc create configmap registry-config --from-file=${MIRROR_ADDR_HOSTNAME}..5000=$path/ca.crt -n openshift-config ---- -. Add the required trusted CAs for the mirror in the cluster's image -configuration object: +. Add the required trusted CAs for the mirror in the image configuration object: + [source,terminal] ---- $ oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-config"}}}' --type=merge ---- -. Update the `samplesRegistry` field in the Cluster Samples Operator configuration object -to contain the `hostname` portion of the mirror location defined in the mirror -configuration: +. Update the `samplesRegistry` field in the Cluster Samples Operator configuration object to contain the `hostname` portion of the mirror location defined in the mirror configuration: + [source,terminal] ---- $ oc edit configs.samples.operator.openshift.io -n openshift-cluster-samples-operator ---- + -[NOTE] +[IMPORTANT] ==== -This is required because the image stream import process does not use the mirror or search mechanism at this time. +This step is required because the image stream import process does not use the mirror or search mechanism at this time. ==== -+ -. Add any image streams that are not mirrored into the `skippedImagestreams` field -of the Cluster Samples Operator configuration object. Or if you do not want to support -any of the sample image streams, set the Cluster Samples Operator to `Removed` in the -Cluster Samples Operator configuration object. + +. Add any image streams that are not mirrored into the `skippedImagestreams` field of the Cluster Samples Operator configuration object. Or if you do not want to support any of the sample image streams, set the Cluster Samples Operator to `Removed` in the Cluster Samples Operator configuration object. + [NOTE] ==== The Cluster Samples Operator issues alerts if image stream imports are failing but the Cluster Samples Operator is either periodically retrying or does not appear to be retrying them. ==== + -Many of the templates in the `openshift` namespace -reference the image streams. So using `Removed` to purge both the image streams -and templates will eliminate the possibility of attempts to use them if they -are not functional because of any missing image streams. +Many of the templates in the `openshift` namespace reference the image streams. You can use `Removed` to purge both the image streams and templates. This eliminates the possibility of attempts to use the templates if they are not functional because of any missing image streams. ifeval::["{context}" == "post-install-cluster-tasks"] :!restrictednetwork: diff --git a/openshift_images/image-configuration-hcp.adoc b/openshift_images/image-configuration-hcp.adoc index 2dbe50eb97f7..af347dfb4893 100644 --- a/openshift_images/image-configuration-hcp.adoc +++ b/openshift_images/image-configuration-hcp.adoc @@ -3,9 +3,9 @@ include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated,openshift-rosa[] include::_attributes/attributes-openshift-dedicated.adoc[] endif::openshift-dedicated,openshift-rosa[] -:context: image-configuration-hcp [id="image-configuration-hcp"] = Image configuration resources for {hcp-title} +:context: image-configuration-hcp toc::[] diff --git a/openshift_images/samples-operator-alt-registry.adoc b/openshift_images/samples-operator-alt-registry.adoc index a9e290654eed..289de265c669 100644 --- a/openshift_images/samples-operator-alt-registry.adoc +++ b/openshift_images/samples-operator-alt-registry.adoc @@ -6,29 +6,15 @@ include::_attributes/common-attributes.adoc[] toc::[] -You can use the Cluster Samples Operator with an alternate registry by first creating a mirror registry. - -[IMPORTANT] -==== -You must have access to the internet to obtain the necessary container images. In this procedure, you place the mirror registry on a mirror host that has access to both your network and the internet. -==== +[role="_abstract"] +You can use the Cluster Samples Operator with an alternate registry by first creating a mirror registry. Before you create the mirror registry, you must prepare the mirror host. include::modules/installation-about-mirror-registry.adoc[leveloffset=+1] -ifndef::openshift-rosa,openshift-dedicated[] -.Additional information - -For information on viewing the CRI-O logs to view the image source, see xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source]. -endif::openshift-rosa,openshift-dedicated[] - -[id="samples-preparing-bastion"] -=== Preparing the mirror host - -Before you create the mirror registry, you must prepare the mirror host. +//Incorrect rendering of ROSA attributes discovered during Pruning HCP task. I believe some of the following content is not correct for managed OpenShift. I have created JIRA issue to investigate further. include::modules/cli-installing-cli.adoc[leveloffset=+2] - -//include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1] +//the CLI module will need to be made compliant in a separate PR; touches too many files (SD, during CQA 2.0) include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1] @@ -38,4 +24,11 @@ include::modules/installation-restricted-network-samples.adoc[leveloffset=+1] include::modules/installation-images-samples-disconnected-mirroring-assist.adoc[leveloffset=+2] -See xref:../openshift_images/samples-operator-alt-registry.adoc#installation-restricted-network-samples_samples-operator-alt-registry[Using Cluster Samples Operator image streams with alternate or mirrored registries] for a detailed procedure. +ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] +[id="additional-resources_samples-operator-alt-registry"] +[role="_additional-resources"] +== Additional resources + +* xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source] +* xref:../openshift_images/samples-operator-alt-registry.adoc#installation-restricted-network-samples_samples-operator-alt-registry[Using Cluster Samples Operator image streams with alternate or mirrored registries] +endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] \ No newline at end of file