openshift · kalexand-rh · Sep 8, 2020 · Nov 5, 2019
diff --git a/installing/install_config/installing-restricted-networks-preparations.adoc b/installing/install_config/installing-restricted-networks-preparations.adoc
@@ -5,32 +5,47 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. Installations on a restricted network are supported on only infrastructure that you provision, not infrastructure that the installer provisions.
+Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. Installations on a restricted network are supported on only infrastructure that you provision, not infrastructure that the installer provisions. You can also use this procedure in unrestricted networks to ensure your clusters only use container images that have satisfied your organizational controls on external content.
 
 [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. If you do not have access
-to a mirror host, use the method that best fits your restrictions to bring the
-contents of the mirror registry into your restricted network.
+to a mirror host, use the disconnected procedure to copy images to a device you
+can move across network boundaries with.
 ====
 
 include::modules/installation-about-mirror-registry.adoc[leveloffset=+1]
 
-[id="installing-preparing-bastion"]
 [id="installing-preparing-mirror"]
-== Preparing the mirror host
+== Preparing your mirror host
 
-Before you create the mirror registry, you must prepare the mirror host.
+Before you perform the mirror procedure, you must prepare the host to retrieve content
+and push it to the remote location.
 
 include::modules/cli-installing-cli.adoc[leveloffset=+2]
 
-include::modules/installation-creating-mirror-registry.adoc[leveloffset=+1]
+include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1]
 
-//include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1]
+//This command seems out of place. Where should it really go?
+////
+[id="installing-performing-connected-mirror"]
+== Performing a mirror while connected to the internet
 
-include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1]
+$ oc adm release mirror OPENSHIFT_VERSION --to MIRROR_REPOSITORY
+////
+
+////
+[id="installing-restricted-networks-preparations-mirroring"]
+== Mirroring the content
+
+In production environments, add the required images to a registry in your restricted network. For non-production environments, you can use the images without a separate registry.
+
+ modules/installation-performing-disconnected-mirror.adoc[leveloffset=+2]
+
+ modules/installation-performing-disconnected-mirror-without-registry.adoc[leveloffset=+2]
+////
 
 include::modules/installation-mirror-repository.adoc[leveloffset=+1]
 
@@ -40,6 +55,8 @@ include::modules/installation-restricted-network-samples.adoc[leveloffset=+1]
 
 == Next steps
 
+//* TODO need to add the registry secret to the machines, which is different
+
 * Install a cluster on infrastructure that you provision in your restricted nework, such as on
 xref:../../installing/installing_vsphere/installing-restricted-networks-vsphere.adoc#installing-restricted-networks-vsphere[VMware vSphere],
 xref:../../installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc#installing-restricted-networks-bare-metal[bare metal], or xref:../../installing/installing_aws/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[Amazon Web Services].
diff --git a/modules/installation-about-mirror-registry.adoc b/modules/installation-about-mirror-registry.adoc
@@ -5,17 +5,10 @@
 [id="installation-about-mirror-registry_{context}"]
 = About the mirror registry
 
-You can mirror the contents of the {product-title} registry and the images
-that are required to generate the installation program.
+You can mirror the images that are required for {product-title} installation and subsequent product updates to a mirror registry. These actions use the same process. The release image, which contains the description of the content, and the images it references are all mirrored. In addition, the Operator catalog source image and the images that it references must be mirrored for each Operator that you use. After you mirror the content, you configure each cluster to retrieve this content from your mirror registry.
 
-The mirror registry is a key component that is required to complete an
-installation in a restricted network. You can create this mirror on a bastion
-host, which can access both the internet and your closed network, or by using
-other methods that meet your restrictions.
+The mirror registry can be any container registry that supports the most recent container image API, which is referred to as `schema2`. All major cloud provider registries, as well as Red Hat Quay, Artifactory, and the open source link:https://github.com/docker/distribution[Docker distribution registry] have the necessary support. Using one of these registries ensures that {product-title} can verify the integrity of each image in disconnected environments.
 
-Because of the way that {product-title} verifies integrity for the release
-payload, the image references in your local registry are identical to the ones
-that are hosted by Red Hat on link:https://quay.io[Quay.io].
-During the bootstrapping process of installation, the images must have the same
-digests no matter which repository they are pulled from. To ensure that the
-release payload is identical, you mirror the images to your local repository.
+The mirror registry must be reachable by every machine in the clusters that you provision. If the registry is unreachable installation, updating, or normal operations such as workload relocation might fail. For that reason, you must run mirror registries in a highly available way, and the mirror registries must at least match the production availability of your {product-title} clusters.
+
+When you populate a mirror registry with {product-title} images, you can follow two scenarios. If you have a host that can access both the internet and your mirror registry, but not your cluster nodes, you can directly mirror the content from that machine. This process is referred to as _connected mirroring_. If you have no such host, you must mirror the images to a file system and then bring that host or removable media into your restricted environment. This process is referred to as _disconnected mirroring_.
diff --git a/modules/installation-adding-registry-pull-secret.adoc b/modules/installation-adding-registry-pull-secret.adoc
@@ -1,111 +1,52 @@
 // Module included in the following assemblies:
 //
+// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc
 // * openshift_images/samples-operator-alt-registry.adoc
 
+ifeval::["{context}" == "installing-restricted-networks-preparations"]
+:restricted:
+endif::[]
+
 [id="installation-adding-registry-pull-secret_{context}"]
-= Adding the registry to your pull secret
+= Configuring credentials that allow images to be mirrored
+
+Create a container image registry credentials file that allows mirroring
+images from Red Hat to your mirror.
 
-Modify your the pull secret for your {product-title} cluster to describe
-your local registry before you install an {product-title} cluster in a
-restricted network.
+ifdef::restricted[]
+[WARNING]
+====
+Do not use this image registry credentials file as the pull secret when you install a cluster. If you provide this file when you install cluster, all of the machines in the cluster will have write access to your mirror registry.
+====
+endif::restricted[]
 
 .Prerequisites
 
 * You configured a mirror registry to use in your restricted network.
+ifdef::restricted[]
+* You identified an image repository location on your mirror registry to mirror images into.
+* You provisioned a mirror registry account that allows images to be uploaded to that image repository.
+endif::restricted[]
 
 .Procedure
 
-Complete the following steps on the mirror host:
+Complete the following steps on the installation host:
 
 . Download your `registry.redhat.io` pull secret from the
-link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site.
+link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site and save it to a `.json` file.
 
-. Generate the base64-encoded user name and password or token for your mirror
-registry:
+. Log in to your registry by using the following command:
 +
 ----
-$ echo -n '<user_name>:<password>' | base64 -w0 <1>
-
-BGVtbYk3ZHAtqXs=
+$ oc registry login --to ./pull-secret.json --registry "<registry_host_and_port>" --auth-basic=<username>:<password>
 ----
-<1> For `<user_name>` and `<password>`, specify the user name and password that
-you configured for your registry.
-
-. Make a copy of your pull secret in JSON format:
 +
-----
-$ cat ./pull-secret.text | jq .  > <path>/<pull-secret-file><1>
-----
-<1> Specify the path to the folder to store the pull secret in and a name for
-the JSON file that you create.
-+
-The contents of the file resemble the following example:
-+
-----
-{
-  "auths": {
-    "cloud.openshift.com": {
-      "auth": "b3BlbnNo...",
-      "email": "[email protected]"
-    },
-    "quay.io": {
-      "auth": "b3BlbnNo...",
-      "email": "[email protected]"
-    },
-    "registry.connect.redhat.com": {
-      "auth": "NTE3Njg5Nj...",
-      "email": "[email protected]"
-    },
-    "registry.redhat.io": {
-      "auth": "NTE3Njg5Nj...",
-      "email": "[email protected]"
-    }
-  }
-}
-----
+Provide both the registry details and a valid user name and password for the registry.
 
-. Edit the new file and add a section that describes your registry to it:
-+
-----
-  "auths": {
-...
-    "<mirror_registry>": { <1>
-      "auth": "<credentials>", <2>
-      "email": "[email protected]"
-  },
-...
-----
-<1> For `<mirror_registry>`, 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:5000`
-<2> For `<credentials>`, specify the base64-encoded user name and password for
-the mirror registry.
-+
-The file resembles the following example:
-+
-----
-{
-  "auths": {
-    "cloud.openshift.com": {
-      "auth": "b3BlbnNo...",
-      "email": "[email protected]"
-    },
-    "quay.io": {
-      "auth": "b3BlbnNo...",
-      "email": "[email protected]"
-    },
-    "registry.connect.redhat.com": {
-      "auth": "NTE3Njg5Nj...",
-      "email": "[email protected]"
-    },
-    "<mirror_registry>": {
-      "auth": "<credentials>",
-      "email": "[email protected]"
-    },
-    "registry.redhat.io": {
-      "auth": "NTE3Njg5Nj...",
-      "email": "[email protected]"
-    }
-  }
-}
-----
+ifeval::["{context}" == "installing-restricted-networks-preparations"]
+:!restricted:
+endif::[]
+
+ifeval::["{context}" == "updating-restricted-network-cluster"]
+:!restricted:
+endif::[]
diff --git a/modules/installation-bare-metal-config-yaml.adoc b/modules/installation-bare-metal-config-yaml.adoc
@@ -64,7 +64,7 @@ ifndef::restricted[]
 pullSecret: '{"auths": ...}' <12>
 endif::restricted[]
 ifdef::restricted[]
-pullSecret: '{"auths":{"<mirror_registry>": {"auth": "<credentials>","email": "[email protected]"}}}' <12>
+pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "[email protected]"}}}' <12>
 endif::restricted[]
 sshKey: 'ssh-ed25519 AAAA...' <13>
 ifdef::restricted[]
@@ -82,10 +82,10 @@ ifdef::ibm-z[]
   source: quay.io/openshift-release-dev/ocp-v4.0-art-devsshKey: 'ssh-ed25519 AAAA...'
 endif::ibm-z[]
 ifndef::ibm-z[]
-  - <mirror_registry>/<repo_name>/release
+  - <local_registry>/<local_repository_name>/release
   source: quay.io/openshift-release-dev/ocp-release
 - mirrors:
-  - <mirror_registry>/<repo_name>/release
+  - <local_registry>/<local_repository_name>/release
   source: registry.svc.ci.openshift.org/ocp/release
 endif::ibm-z[]
 endif::restricted[]
@@ -150,7 +150,7 @@ provided by the included authorities, including Quay.io, which serves the
 container images for {product-title} components.
 endif::restricted[]
 ifdef::restricted[]
-<12> For `<mirror_registry>`, specify the registry domain name, and optionally the
+<12> For `<local_registry>`, 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:5000`. For `<credentials>`,
 specify the base64-encoded user name and password for your mirror registry.

diff --git a/modules/installation-generate-aws-user-infra-install-config.adoc b/modules/installation-generate-aws-user-infra-install-config.adoc
@@ -58,7 +58,7 @@ installation program.
 ... Paste the pull secret that you obtained from the
 link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site.
 
-. Edit the `install-config.yaml` file to set the number of compute replicas, which are also known as worker 
+. Edit the `install-config.yaml` file to set the number of compute replicas, which are also known as worker
 replicas, to `0`, as shown in the following `compute` stanza:
 +
 [source,yaml]
@@ -77,10 +77,10 @@ is required for an installation in a restricted network.
 your registry:
 +
 ----
-pullSecret: '{"auths":{"<mirror_registry>": {"auth": "<credentials>","email": "[email protected]"}}}'
+pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "[email protected]"}}}'
 ----
 +
-For `<mirror_registry>`, specify the registry domain name, and optionally the
+For `<local_registry>`, 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:5000`. For `<credentials>`,
 specify the base64-encoded user name and password for your mirror registry.
@@ -97,15 +97,14 @@ additionalTrustBundle: |
 ----
 imageContentSources:
 - mirrors:
-  - <mirror_registry>/<repo_name>/release
+  - <local_registry>/<local_repository_name>/release
   source: quay.io/openshift-release-dev/ocp-release
 - mirrors:
-  - <mirror_registry>/<repo_name>/release
+  - <local_registry>/<local_repository_name>/release
   source: registry.svc.ci.openshift.org/ocp/release
 ----
 +
-Use the `imageContentSources` section from the output of the command to
-mirror the repository.
+Use the `imageContentSources` section from the output of the command to mirror the repository or the values that you used when you mirrored the content from the media that you brought into your restricted network.
 endif::restricted[]
 
 . Optional: Back up the `install-config.yaml` file.

diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc
@@ -6,19 +6,19 @@
 [id="installation-mirror-repository_{context}"]
 = Mirroring the {product-title} image repository
 
-Mirror the {product-title} image repository to use during cluster installation
-or upgrade.
+Mirror the {product-title} image repository to your registry to use during cluster installation or upgrade.
 
 .Prerequisites
 
+* Your mirror host has access to the internet.
 * You configured a mirror registry to use in your restricted network and
 can access the certificate and credentials that you configured.
 * You downloaded the pull secret from the
 link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site and modified it to include authentication to your mirror repository.
 
 .Procedure
 
-Complete the following steps on a host that can access both quay.io and your mirror registry:
+Complete the following steps on the mirror host:
 
 . Review the
 link:https://access.redhat.com/downloads/content/290/[{product-title} downloads page]
@@ -29,26 +29,55 @@ to determine the version of {product-title} that you want to install and determi
 ----
 $ export OCP_RELEASE=<release_version> <1>
 $ export LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>' <2>
-$ export LOCAL_REPOSITORY='<repository_name>' <3>
+$ export LOCAL_REPOSITORY='<local_repository_name>' <3>
 $ export PRODUCT_REPO='openshift-release-dev' <4>
 $ export LOCAL_SECRET_JSON='<path_to_pull_secret>' <5>
 $ export RELEASE_NAME="ocp-release" <6>
+$ export ARCHITECTURE=<server_architecture> <7>
+$ REMOVABLE_MEDIA_PATH=<path> <8>
 ----
 <1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} to
 install for your architecture, such as `4.3.0-x86_64`.
 <2> For `<local_registry_host_name>`, specify the registry domain name for your mirror
 repository, and for `<local_registry_host_port>`, specify the port that it
 serves content on.
-<3> For `<repository_name>`, specify the name of the repository to create in your
+<3> For `<local_repository_name>`, specify the name of the repository to create in your
 registry, such as `ocp4/openshift4`.
 <4> The repository to mirror. For a production release, you must specify
 `openshift-release-dev`.
 <5> For `<path_to_pull_secret>`, specify the absolute path to and file name of
 the pull secret for your mirror registry that you created.
 <6> The release mirror. For a production release, you must specify
 `ocp-release`.
+<7> For `server_architecture`, specify the architecture of the server, such as `x86_64`.
+<8> For `<path>`, specify the path to the directory to host the mirrored images.
 
-. Mirror the repository:
+. Mirror the version images to the internal container registry:
+** If your mirror host does not have internet access, take the following actions:
+... Connect the removable media to a system that is connected to the internet.
+... Review the images and configuration manifests to mirror:
++
+----
+$ oc adm -a ${LOCAL_SECRET_JSON} release mirror
+--from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
+--to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
+--to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} --run-dry
+----
+... 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.
+... Mirror the images to a directory on the removable media:
++
+----
+$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE}
+----
+... Take the media to the restricted network environment and upload the images to the local container registry.
++
+----
+$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror 'file://openshift/release:${OCP_RELEASE}*' ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}
+----
+
+** If the local container registry is connected to the mirror host, take the following actions:
+... Directly push the release images to the local registry by using following command:
 +
 ----
 $ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
@@ -60,7 +89,7 @@ $ oc adm -a ${LOCAL_SECRET_JSON} release mirror \
 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
+... 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.
 
 . To create the installation program that is based on the content that you