diff --git a/installing/install_config/installing-restricted-networks-preparations.adoc b/installing/install_config/installing-restricted-networks-preparations.adoc index 49859dc0fed8..9ac58f64445b 100644 --- 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] @@ -38,6 +53,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 index ce18cd46afb7..0ad4fc482440 100644 --- 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 index e96c9420a32f..6f769d82ad73 100644 --- a/modules/installation-adding-registry-pull-secret.adoc +++ b/modules/installation-adding-registry-pull-secret.adoc @@ -1,5 +1,6 @@ // 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 @@ -7,12 +8,22 @@ 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 + +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[] ifdef::restricted[] [WARNING] @@ -29,104 +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. - -. Generate the base64-encoded user name and password or token for your mirror -registry: -+ ----- -$ echo -n ':' | base64 -w0 <1> - -BGVtbYk3ZHAtqXs= ----- -<1> For `` and ``, 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 . > /<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": "you@example.com" - }, - "quay.io": { - "auth": "b3BlbnNo...", - "email": "you@example.com" - }, - "registry.connect.redhat.com": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - }, - "registry.redhat.io": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - } - } -} ----- +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::[] -. Edit the new file and add a section that describes your registry to it: +. Log in to your registry by using the following command: + ---- - "auths": { -... - "": { <1> - "auth": "", <2> - "email": "you@example.com" - }, -... +$ oc registry login --to ./pull-secret.json --registry "" ---- -<1> For ``, 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 ``, 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": "you@example.com" - }, - "quay.io": { - "auth": "b3BlbnNo...", - "email": "you@example.com" - }, - "registry.connect.redhat.com": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - }, - "": { - "auth": "", - "email": "you@example.com" - }, - "registry.redhat.io": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - } - } -} ----- +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 index 8564e1df8030..7a23142fc41b 100644 --- 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":{"": {"auth": "","email": "you@example.com"}}}' <12> +pullSecret: '{"auths":{"": {"auth": "","email": "you@example.com"}}}' <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[] - - //release + - //release source: quay.io/openshift-release-dev/ocp-release - mirrors: - - //release + - //release source: registry.svc.ci.openshift.org/ocp/release endif::ibm-z[] endif::restricted[] @@ -152,7 +152,7 @@ provided by the included authorities, including Quay.io, which serves the container images for {product-title} components. endif::restricted[] ifdef::restricted[] -<12> For ``, specify the registry domain name, and optionally the +<12> For ``, 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 ``, 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 index b612a82a1a85..ef6917c2b338 100644 --- 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":{"": {"auth": "","email": "you@example.com"}}}' +pullSecret: '{"auths":{"": {"auth": "","email": "you@example.com"}}}' ---- + -For ``, specify the registry domain name, and optionally the +For ``, 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 ``, specify the base64-encoded user name and password for your mirror registry. @@ -97,15 +97,14 @@ additionalTrustBundle: | ---- imageContentSources: - mirrors: - - //release + - //release source: quay.io/openshift-release-dev/ocp-release - mirrors: - - //release + - //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 index 9f0979f18399..751cd056fed8 100644 --- a/modules/installation-mirror-repository.adoc +++ b/modules/installation-mirror-repository.adoc @@ -6,11 +6,11 @@ [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 @@ -18,7 +18,7 @@ link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on .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,18 +29,19 @@ to determine the version of {product-title} that you want to install and determi ---- $ export OCP_RELEASE= <1> $ export LOCAL_REGISTRY=':' <2> -$ export LOCAL_REPOSITORY='' <3> +$ export LOCAL_REPOSITORY='' <3> $ export PRODUCT_REPO='openshift-release-dev' <4> $ export LOCAL_SECRET_JSON='' <5> $ export RELEASE_NAME="ocp-release" <6> $ export ARCHITECTURE= <7> +$ REMOVABLE_MEDIA_PATH= <8> ---- <1> For ``, specify the tag that corresponds to the version of {product-title} to install, such as `4.5.0`. <2> For ``, specify the registry domain name for your mirror repository, and for ``, specify the port that it serves content on. -<3> For ``, specify the name of the repository to create in your +<3> For ``, 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`. @@ -49,9 +50,34 @@ 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 ``, specify the path to the directory to host the mirrored images. +. 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} +---- -. Mirror the 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 \ @@ -63,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 diff --git a/modules/installation-performing-disconnected-mirror-without-registry.adoc b/modules/installation-performing-disconnected-mirror-without-registry.adoc new file mode 100644 index 000000000000..b42b3d6afe96 --- /dev/null +++ b/modules/installation-performing-disconnected-mirror-without-registry.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc + +[id="installation-performing-disconnected-mirror-without-registry"] += Performing a mirror to disk for use in disconnected environments with a non-production mirror registry + +If a production mirror registry is not available, you can configure a simple mirror registry by using the disconnected procedure to serve container images that you downloaded to disk. + +.Procedure + +. Determine the IP of your host within the restricted network as ``. + +. On a local host, copy the required `imageContentSources` and `ImageContentSourcePolicy`: +.. Make the mirror directory and change to it: ++ +---- +$ mkdir ; cd +---- + +.. Mirror the images: ++ +---- +$ oc adm release mirror --to file://openshift/release +---- + +. From within the restricted network, start an image mirror server on port 5000 on all interfaces on the host: +.. Change to the mirror directory: ++ +---- +$ cd MIRROR_DIR +---- + +.. Serve the images for the installation program to use: ++ +---- +$ oc image serve +---- + +This registry does not perform authentication and does not require TLS in order to guarantee integrity of the provided images. diff --git a/modules/installation-performing-disconnected-mirror.adoc b/modules/installation-performing-disconnected-mirror.adoc new file mode 100644 index 000000000000..f87630457d58 --- /dev/null +++ b/modules/installation-performing-disconnected-mirror.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc + +[id="installation-performing-disconnected-mirror"] += Mirroring the {product-title} image registry contents to disk for use in disconnected environments + +When you mirror images to disk, you download images as files. Then, you move your +mirror host, which can be a laptop or a removable media device, like a +USB drive, into the restricted network and complete the mirror +procedure. + +.Procedure + +. On a local host, test the mirror process: ++ +---- +$ oc adm release mirror --to --dry-run +---- + +. On a local host, copy the required `imageContentSources` and `ImageContentSourcePolicy`: +.. Make the mirror directory and change to it: ++ +---- +$ mkdir ; cd +---- + +.. Mirror the images: ++ +---- +$ oc adm release mirror --to file://openshift/release +---- + +. From within the restricted network, mirror the images to your restricted mirror repository: ++ +---- +$ oc adm release mirror file://openshift/release:* --to +---- diff --git a/modules/installation-vsphere-config-yaml.adoc b/modules/installation-vsphere-config-yaml.adoc index 9a4b3d77031d..9cdffb0150e8 100644 --- a/modules/installation-vsphere-config-yaml.adoc +++ b/modules/installation-vsphere-config-yaml.adoc @@ -41,7 +41,7 @@ pullSecret: '{"auths": ...}' <13> endif::restricted[] ifdef::restricted[] fips: false <12> -pullSecret: '{"auths":{"": {"auth": "","email": "you@example.com"}}}' <13> +pullSecret: '{"auths":{"": {"auth": "","email": "you@example.com"}}}' <13> endif::restricted[] sshKey: 'ssh-ed25519 AAAA...' <14> ifdef::restricted[] @@ -51,10 +51,10 @@ additionalTrustBundle: | <15> -----END CERTIFICATE----- imageContentSources: <16> - mirrors: - - //release + - //release source: quay.io/openshift-release-dev/ocp-release - mirrors: - - //release + - //release source: registry.svc.ci.openshift.org/ocp/release endif::restricted[] ---- @@ -106,7 +106,7 @@ provided by the included authorities, including Quay.io, which serves the container images for {product-title} components. endif::restricted[] ifdef::restricted[] -<13> For ``, specify the registry domain name, and optionally the +<13> For ``, 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 ``, specify the base64-encoded user name and password for your mirror registry. diff --git a/modules/update-mirror-repository.adoc b/modules/update-mirror-repository.adoc index 001f0be79cd5..7cedb670b15c 100644 --- a/modules/update-mirror-repository.adoc +++ b/modules/update-mirror-repository.adoc @@ -16,7 +16,7 @@ Before you upgrade a cluster on infrastructure that you provision in a restricte ---- $ OCP_RELEASE= # <1> $ LOCAL_REGISTRY=':' # <2> -$ LOCAL_REPOSITORY='' # <3> +$ LOCAL_REPOSITORY='' # <3> $ PRODUCT_REPO='openshift-release-dev' # <4> $ LOCAL_SECRET_JSON='' # <5> $ RELEASE_NAME='ocp-release' # <6>