openshift · kalexand-rh · Jul 9, 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,39 +5,56 @@ 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]
 
 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,18 +1,29 @@
 // Module included in the following assemblies:
 //
+// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc
 // * openshift_images/samples-operator-alt-registry.adoc
 // * updating/updating-restricted-network-cluster.adoc
 
 ifeval::["{context}" == "updating-restricted-network-cluster"]
 :restricted:
 endif::[]
 
+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
 
-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.
+Create a container image registry credentials file that allows mirroring
+images from Red Hat to your mirror.
+
+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[]
 
 ifdef::restricted[]
 [WARNING]
@@ -29,106 +40,31 @@ 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:
 
 ifndef::openshift-origin[]
 . 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.
 endif::[]
 
-. Generate the base64-encoded user name and password or token for your mirror
-registry:
-+
-----
-$ echo -n '<user_name>:<password>' | base64 -w0 <1>
-
-BGVtbYk3ZHAtqXs=
-----
-<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:
+. Log in to your registry by using the following command:
 +
 ----
-$ cat ./pull-secret.text | jq .  > <path>/<pull-secret-file><1>
+$ oc registry login --to ./pull-secret.json --registry "<registry_host_and_port>"
 ----
-<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]"
-    }
-  }
-}
-----
-
-. 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]"
-    }
-  }
-}
-----
+When prompted, enter the user name and password for the registry.
 
+ifeval::["{context}" == "installing-restricted-networks-preparations"]
+:!restricted:
+endif::[]
 
 ifeval::["{context}" == "updating-restricted-network-cluster"]
 :!restricted:

diff --git a/modules/installation-bare-metal-config-yaml.adoc b/modules/installation-bare-metal-config-yaml.adoc
@@ -43,7 +43,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[]
@@ -53,10 +53,10 @@ additionalTrustBundle: | <14>
   -----END CERTIFICATE-----
 imageContentSources: <15>
 - 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
 endif::restricted[]
 ----
@@ -112,7 +112,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
@@ -61,7 +61,7 @@ ifdef::openshift-origin[]
 This field is optional.
 endif::[]
 
-. 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]
@@ -80,10 +80,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.
@@ -100,15 +100,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.