diff --git a/_topic_map.yml b/_topic_map.yml index 6ce0616c207e..6d28393243cc 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/installing/installing_restricted_networks/installing-disconnected.adoc b/installing/installing_restricted_networks/installing-disconnected.adoc new file mode 100644 index 000000000000..f8a447182ef2 --- /dev/null +++ b/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]. diff --git a/installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc b/installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc new file mode 100644 index 000000000000..0668f1cf90cb --- /dev/null +++ b/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]. +//// diff --git a/modules/installation-about-mirror-registry.adoc b/modules/installation-about-mirror-registry.adoc new file mode 100644 index 000000000000..1d6905e3acd7 --- /dev/null +++ b/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. diff --git a/modules/installation-adding-registry-pull-secret.adoc b/modules/installation-adding-registry-pull-secret.adoc new file mode 100644 index 000000000000..eed42553a911 --- /dev/null +++ b/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 ':' | 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" + } + } +} +---- + +. Edit the new file and add a section that describes your registry to it: ++ +---- + "auths": { +... + ":": { <1> + "auth": "", <2> + "email": "you@example.com" + }, +... +---- +<1> For `bastion_host_name`, specify the registry domain name +that you specified in your certificate, and for ``, +specify the port that your mirror registry uses to serve content. +<2> For ``, 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" + }, + ":": { + "auth": "", + "email": "you@example.com" + }, + "registry.redhat.io": { + "auth": "NTE3Njg5Nj...", + "email": "you@example.com" + } + } +} +---- diff --git a/modules/installation-creating-mirror-registry.adoc b/modules/installation-creating-mirror-registry.adoc new file mode 100644 index 000000000000..0b11960195b7 --- /dev/null +++ b/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 <1> +---- +<1> Replace `` and `` with a user name and a password. + +. Create the `mirror-registry` container to host your registry: ++ +---- +# podman run --name mirror-registry -p 5000: \ <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 ``, specify the port that your mirror registry +uses to serve content. + +. Open the required ports for your registry: ++ +---- +# firewall-cmd --add-port=/tcp --zone=internal --permanent <1> +# firewall-cmd --add-port=/tcp --zone=public --permanent <1> +# firewall-cmd --reload +---- +<1> For ``, 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 : -k https://:/v2/_catalog <1> + +{"repositories":[]} +---- +<1> For `` and ``, specify the user name and password +for your registry. For ``, specify the registry domain name +that you specified in your certificate, such as `registry.example.com`. For +``, 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 +---- +//// diff --git a/modules/installation-local-registry-pull-secret.adoc b/modules/installation-local-registry-pull-secret.adoc new file mode 100644 index 000000000000..684b531f2a61 --- /dev/null +++ b/modules/installation-local-registry-pull-secret.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc + +[id="installation-local-registry-pull-secret_{context}"] += Creating a pull secret for your mirror registry + +In a restricted network, you create a pull secret that contains only +the information for your registry. + +.Prerequisites + +* You configured a mirror registry to use in your restricted network. + +.Procedure + +* On the bastion host, create a new pull secret for your registry that is in +JSON format: ++ +---- +{ + "auths": { + ":": { <1> + "auth": "", <2> + "email": "you@example.com" + } + } +} +---- +<1> For `bastion_host_name`, specify the registry domain name +that you specified in your certificate, and for ``, +specify the port that your mirror registry uses to serve content. +<2> For ``, specify the base64-encoded user name and password for +the mirror registry that you generated. diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc new file mode 100644 index 000000000000..5104edd0a059 --- /dev/null +++ b/modules/installation-mirror-repository.adoc @@ -0,0 +1,96 @@ +// Module included in the following assemblies: +// +// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc + +[id="installation-mirror-repository_{context}"] += Mirroring the {product-title} image repository + +Mirror the {product-title} image repository to use during cluster installation +or upgrade. + +.Prerequisites + +* 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[OpenShift Infrastructure Providers] +page and modified it to include authentication to your mirror repository. + +.Procedure + +Complete the following steps on the bastion host: + +. Review the +link:https://access.redhat.com/downloads/content/290/[{product-title} downloads page] +to determine the version of {product-title} that you want to install. + +. Set the required environment variables: ++ +---- +$ export OCP_RELEASE= <1> +$ export LOCAL_REGISTRY=':' <2> +$ export LOCAL_REPOSITORY='' <3> +$ export PRODUCT_REPO='openshift-release-dev' <4> +$ export LOCAL_SECRET_JSON='' <5> +$ export RELEASE_NAME="ocp-release" <6> +---- +<1> For ``, specify the version number of {product-title} to +install, such as `4.2.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 +registry, such as `ocp4/openshift4`. +<4> The repository to mirror. For a production release, you must specify +`openshift-release-dev`. +<5> For ``, 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`. + +. Mirror the repository: ++ +---- +$ oc adm -a ${LOCAL_SECRET_JSON} release mirror \ + --from=quay.io/${UPSTREAM_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \ + --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ + --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE} +---- ++ +This command pulls the release information as a digest, and its output includes +text that resembles the following sample: ++ +---- +... +Success +Update image: ://: +Mirror prefix: :// + +To use the new mirrored repository to install, add the following section to the install-config.yaml: + +imageContentSources: +- mirrors: + - ://release + source: quay.io/openshift-release-dev/ocp-release +- mirrors: + - ://release + source: quay.io/openshift-release-dev/ocp-v4.0-art-dev +... +---- + +. Record the `imageContentSources` section from the output of the previous +command. This information is required during {product-title} installation. + +. To create the installation program that is based on the content that you +mirrored, extract it and pin it to the release: ++ +---- +$ oc adm release extract --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}" +---- ++ +[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. +====