osdocs-626 preparing for disconnected installation

_topic_map.yml

@@ -107,7 +107,7 @@ Topics:
 - Name: Installing on GCP
   Dir: installing_gcp
   Topics:
-  - Name: Configuring an GCP account
+  - Name: Configuring a GCP account
     File: installing-gcp-account
   - Name: Installing a cluster quickly on GCP
     File: installing-gcp-default
@@ -118,8 +118,8 @@ Topics:
 - Name: Installing in restricted networks
   Dir: installing_restricted_networks
   Topics:
-#  - Name: Preparing for a disconnected installation
-#    File: installing-restricted-networks-preparations
+  - Name: Creating a mirror registry for a restricted network
+    File: installing-restricted-networks-preparations
   - Name: Restricted network AWS installation
     File: installing-restricted-networks-aws
   - Name: Restricted network bare metal installation

installing/installing_restricted_networks/installing-disconnected.adoc

@@ -0,0 +1,45 @@
+[id="installing-azure-customizations"]
+= Installing a cluster on Azure with customizations
+include::modules/common-attributes.adoc[]
+:context: installing-azure-customizations
+
+toc::[]
+
+In {product-title} version {product-version}, you can install a customized
+cluster on infrastructure that the installation program provisions on
+Microsoft Azure. To customize the installation, you modify
+some parameters in the `install-config.yaml` file before you install the cluster.
+
+.Prerequisites
+
+* Review details about the
+xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update]
+processes.
+//* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account]
+//to host the cluster.
+* If you use a firewall, you must
+xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to access Red Hat Insights].
+
+include::modules/cluster-entitlements.adoc[leveloffset=+1]
+
+include::modules/ssh-agent-using.adoc[leveloffset=+1]
+
+include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
+
+include::modules/installation-initializing.adoc[leveloffset=+1]
+
+include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
+
+include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
+include::modules/cli-install.adoc[leveloffset=+1]
+
+include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
+
+.Next steps
+
+* xref:../../installing/install_config/customizations.adoc#customizations[Customize your cluster].
+* If necessary, you can
+xref:../../telemetry/opting-out-of-telemetry.adoc#opting-out-of-telemetry[opt out of telemetry].

installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc

@@ -0,0 +1,45 @@
+[id="installing-restricted-networks-preparations"]
+= Creating a mirror registry for installation in a restricted network
+include::modules/common-attributes.adoc[]
+:context: installing-restricted-networks-preparations
+
+toc::[]
+
+Before you install a cluster on infrastructure that you provision in a
+restricted network, you must create a mirror registry.
+
+[IMPORTANT]
+====
+You must have access to the internet to obtain the data that populates the mirror
+repository. In this procedure, you place the mirror registry on a bastion host
+that has access to both your network and the internet. If you do not have access
+to a bastion host, use the method that best fits your restrictions to bring the
+contents of the mirror registry into your restricted network.
+====
+
+include::modules/installation-about-mirror-registry.adoc[leveloffset=+1]
+
+[id="installing-preparing-bastion"]
+== Preparing the bastion host
+
+Before you create the mirror registry, you must prepare the bastion host.
+
+include::modules/cli-install.adoc[leveloffset=+2]
+
+include::modules/installation-creating-mirror-registry.adoc[leveloffset=+1]
+
+include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1]
+
+//include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1]
+
+include::modules/installation-mirror-repository.adoc[leveloffset=+1]
+
+////
+Need to fix these links after the other PR merges.
+.Next steps
+
+* Install a cluster on infrastructure that you provision, such as
+xref:../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[VMware vSphere]
+or
+xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[bare metal].
+////

modules/installation-about-mirror-registry.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc
+
+[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.
+
+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.
+
+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.

modules/installation-adding-registry-pull-secret.adoc

@@ -0,0 +1,112 @@
+// Module included in the following assemblies:
+//
+// * TBD
+
+[id="installation-adding-registry-pull-secret_{context}"]
+= Adding the registry to your pull secret
+
+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.
+
+.Prerequisites
+
+* You configured a mirror registry to use in your restricted network.
+
+.Procedure
+
+Complete the following steps on the bastion host:
+
+. Download your `registry.redhat.io` pull secret from the
+link:https://cloud.redhat.com/openshift/install[OpenShift Infrastructure Providers]
+page.
+
+. 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:
++
+----
+$ 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": "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"
+    }
+  }
+}
+----
+
+. Edit the new file and add a section that describes your registry to it:
++
+----
+  "auths": {
+...
+    "<local_registry_host_name>:<local_registry_host_port>": { <1>
+      "auth": "<credentials>", <2>
+      "email": "you@example.com"
+  },
+...
+----
+<1> For `bastion_host_name`, specify the registry domain name
+that you specified in your certificate, and for `<local_registry_host_port>`,
+specify the port that your mirror registry uses to serve content.
+<2> For `<credentials>`, specify the base64-encoded user name and password for
+the mirror registry that you generated.
++
+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"
+    },
+    "<local_registry_host_name>:<local_registry_host_port>": {
+      "auth": "<credentials>",
+      "email": "you@example.com"
+    },
+    "registry.redhat.io": {
+      "auth": "NTE3Njg5Nj...",
+      "email": "you@example.com"
+    }
+  }
+}
+----

modules/installation-creating-mirror-registry.adoc

@@ -0,0 +1,149 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc
+
+ifeval::["{context}" == "installing-restricted-networks-preparations"]
+:restricted:
+endif::[]
+
+[id="installation-creating-mirror-registry_{context}"]
+= Creating a mirror registry
+
+Create a registry to host the mirrored content that you require for installing
+{product-title}.
+ifdef::restricted[]
+For installation in a restricted network, you must place the mirror on your
+bastion host.
+endif::restricted[]
+
+[NOTE]
+====
+The following procedure creates a simple registry that stores data in the
+`/opt/registry` folder and runs in a `podman` container. You can use a different
+registry solution, such as
+link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#repo-mirroring-in-red-hat-quay[Red Hat Quay].
+Review the following procedure to ensure that your registry functions
+correctly.
+====
+
+.Prerequisites
+
+* You have a Red Hat Enterprise Linux (RHEL) server on your network to use
+as the registry host.
+* The registry host can access the internet.
+
+.Procedure
+
+ifdef::restricted[]
+On the bastion host, take the following actions:
+endif::restricted[]
+
+. Install the required packages:
++
+----
+# yum -y install podman httpd httpd-tools jq
+----
++
+The `podman` package provides the container package that you run the registry
+in. The `httpd` and `httpd-tools` packages provide the `htpasswd` utility, which
+you use to create users. The `jq` package improves the display of JSON output
+on your command line.
+
+. Create folders for the registry:
++
+----
+# mkdir -p /opt/registry/{auth,certs,data}
+----
++
+These folders are mounted inside the registry container.
+
+. Provide a certificate for the registry. If you do not have an existing, trusted
+certificate authority, you can generate a self-signed certificate:
++
+----
+$ cd /opt/registry/certs
+# openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt
+----
++
+At the prompts, provide the required values for the certificate:
+[horizontal]
+Country Name (2 letter code):: Specify the two-letter ISO country code for your location.
+See the link:https://www.iso.org/iso-3166-country-codes.html[ISO 3166 country codes]
+standard.
+State or Province Name (full name):: Enter the full name of your state or province.
+Locality Name (eg, city):: Enter the name of your city.
+Organization Name (eg, company):: Enter your company name.
+Organizational Unit Name (eg, section):: Enter your department name.
+Common Name (eg, your name or your server's hostname):: Enter the host name for
+the registry host. Ensure that your hostname is in DNS and that it resolves to
+the expected IP address.
+Email Address:: Enter your email address.
+For more information, see the
+link:https://www.openssl.org/docs/man1.1.1/man1/req.html[req] description in the
+OpenSSL documentation.
+
+. Generate a user name and a password for your registry that uses the `bcrpt` format:
++
+----
+# htpasswd -bBc /opt/registry/auth/htpasswd <user_name> <password> <1>
+----
+<1> Replace `<user_name>` and `<password>` with a user name and a password.
+
+. Create the `mirror-registry` container to host your registry:
++
+----
+# podman run --name mirror-registry -p 5000:<local_registry_host_port> \ <1>
+     -v /opt/registry/data:/var/lib/registry:z \
+     -v /opt/registry/auth:/auth:z \
+     -e "REGISTRY_AUTH=htpasswd" \
+     -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
+     -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
+     -v /opt/registry/certs:/certs:z \
+     -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
+     -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
+     docker.io/library/registry:2
+----
+<1> For `<local_registry_host_port>`, specify the port that your mirror registry
+uses to serve content.
+
+. Open the required ports for your registry:
++
+----
+# firewall-cmd --add-port=<local_registry_host_port>/tcp --zone=internal --permanent <1>
+# firewall-cmd --add-port=<local_registry_host_port>/tcp --zone=public   --permanent <1>
+# firewall-cmd --reload
+----
+<1> For `<local_registry_host_port>`, specify the port that your mirror registry
+uses to serve content.
+
+. Add the self-signed certificate to your list of trusted certificates:
++
+----
+# cp /opt/registry/certs/domain.crt /etc/pki/ca-trust/source/anchors/
+# update-ca-trust
+----
++
+You must trust your certificate to log in to your registry during the mirror process.
+
+. Confirm that the registry is available:
++
+----
+$ curl -u <user_name>:<password> -k https://<local_registry_host_name>:<local_registry_host_port>/v2/_catalog <1>
+
+{"repositories":[]}
+----
+<1> For `<user_name>` and `<password>`, specify the user name and password
+for your registry. For `<local_registry_host_name>`, specify the registry domain name
+that you specified in your certificate, such as `registry.example.com`. For
+`<local_registry_host_port>`, specify the port that your mirror registry uses to
+serve content.
++
+If the command output displays an empty repository, your registry is available.
+
+////
+. To stop the registry::
++
+----
+# podman stop mirror-registry
+----
+////