Skip to content

Commit b672e52

Browse files
kalexand-rhkalexand-rh
authored
Merge pull request #16678 from kalexand-rh/osdocs626
osdocs-626 preparing for disconnected installation
2 parents f9b4091 + ced98c6 commit b672e52

8 files changed

+505
-3
lines changed

‎_topic_map.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Topics:
107107
- Name: Installing on GCP
108108
Dir: installing_gcp
109109
Topics:
110-
- Name: Configuring an GCP account
110+
- Name: Configuring a GCP account
111111
File: installing-gcp-account
112112
- Name: Installing a cluster quickly on GCP
113113
File: installing-gcp-default
@@ -118,8 +118,8 @@ Topics:
118118
- Name: Installing in restricted networks
119119
Dir: installing_restricted_networks
120120
Topics:
121-
# - Name: Preparing for a disconnected installation
122-
# File: installing-restricted-networks-preparations
121+
- Name: Creating a mirror registry for a restricted network
122+
File: installing-restricted-networks-preparations
123123
- Name: Restricted network AWS installation
124124
File: installing-restricted-networks-aws
125125
- Name: Restricted network bare metal installation

‎installing/installing_restricted_networks/installing-disconnected.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[id="installing-azure-customizations"]
2+
= Installing a cluster on Azure with customizations
3+
include::modules/common-attributes.adoc[]
4+
:context: installing-azure-customizations
5+
6+
toc::[]
7+
8+
In {product-title} version {product-version}, you can install a customized
9+
cluster on infrastructure that the installation program provisions on
10+
Microsoft Azure. To customize the installation, you modify
11+
some parameters in the `install-config.yaml` file before you install the cluster.
12+
13+
.Prerequisites
14+
15+
* Review details about the
16+
xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update]
17+
processes.
18+
//* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account]
19+
//to host the cluster.
20+
* If you use a firewall, you must
21+
xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to access Red Hat Insights].
22+
23+
include::modules/cluster-entitlements.adoc[leveloffset=+1]
24+
25+
include::modules/ssh-agent-using.adoc[leveloffset=+1]
26+
27+
include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
28+
29+
include::modules/installation-initializing.adoc[leveloffset=+1]
30+
31+
include::modules/installation-configuration-parameters.adoc[leveloffset=+2]
32+
33+
include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
34+
35+
include::modules/installation-launching-installer.adoc[leveloffset=+1]
36+
37+
include::modules/cli-install.adoc[leveloffset=+1]
38+
39+
include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
40+
41+
.Next steps
42+
43+
* xref:../../installing/install_config/customizations.adoc#customizations[Customize your cluster].
44+
* If necessary, you can
45+
xref:../../telemetry/opting-out-of-telemetry.adoc#opting-out-of-telemetry[opt out of telemetry].

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[id="installing-restricted-networks-preparations"]
2+
= Creating a mirror registry for installation in a restricted network
3+
include::modules/common-attributes.adoc[]
4+
:context: installing-restricted-networks-preparations
5+
6+
toc::[]
7+
8+
Before you install a cluster on infrastructure that you provision in a
9+
restricted network, you must create a mirror registry.
10+
11+
[IMPORTANT]
12+
====
13+
You must have access to the internet to obtain the data that populates the mirror
14+
repository. In this procedure, you place the mirror registry on a bastion host
15+
that has access to both your network and the internet. If you do not have access
16+
to a bastion host, use the method that best fits your restrictions to bring the
17+
contents of the mirror registry into your restricted network.
18+
====
19+
20+
include::modules/installation-about-mirror-registry.adoc[leveloffset=+1]
21+
22+
[id="installing-preparing-bastion"]
23+
== Preparing the bastion host
24+
25+
Before you create the mirror registry, you must prepare the bastion host.
26+
27+
include::modules/cli-install.adoc[leveloffset=+2]
28+
29+
include::modules/installation-creating-mirror-registry.adoc[leveloffset=+1]
30+
31+
include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1]
32+
33+
//include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1]
34+
35+
include::modules/installation-mirror-repository.adoc[leveloffset=+1]
36+
37+
////
38+
Need to fix these links after the other PR merges.
39+
.Next steps
40+
41+
* Install a cluster on infrastructure that you provision, such as
42+
xref:../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[VMware vSphere]
43+
or
44+
xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[bare metal].
45+
////

‎modules/installation-about-mirror-registry.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc
4+
5+
[id="installation-about-mirror-registry_{context}"]
6+
= About the mirror registry
7+
8+
You can mirror the contents of the {product-title} registry and the images
9+
that are required to generate the installation program.
10+
11+
The mirror registry is a key component that is required to complete an
12+
installation in a restricted network. You can create this mirror on a bastion
13+
host, which can access both the internet and your closed network, or by using
14+
other methods that meet your restrictions.
15+
16+
Because of the way that {product-title} verifies integrity for the release
17+
payload, the image references in your local registry are identical to the ones
18+
that are hosted by Red Hat on link:https://quay.io[quay.io].
19+
During the bootstrapping process of installation, the images must have the same
20+
digests no matter which repository they are pulled from. To ensure that the
21+
release payload is identical, you mirror the images to your local repository.

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * TBD
4+
5+
[id="installation-adding-registry-pull-secret_{context}"]
6+
= Adding the registry to your pull secret
7+
8+
Modify your the pull secret for your {product-title} cluster to describe
9+
your local registry before you install an {product-title} cluster in a
10+
restricted network.
11+
12+
.Prerequisites
13+
14+
* You configured a mirror registry to use in your restricted network.
15+
16+
.Procedure
17+
18+
Complete the following steps on the bastion host:
19+
20+
. Download your `registry.redhat.io` pull secret from the
21+
link:https://cloud.redhat.com/openshift/install[OpenShift Infrastructure Providers]
22+
page.
23+
24+
. Generate the base64-encoded user name and password or token for your mirror
25+
registry:
26+
+
27+
----
28+
$ echo -n '<user_name>:<password>' | base64 -w0 <1>
29+
30+
BGVtbYk3ZHAtqXs=
31+
----
32+
<1> For `<user_name>` and `<password>`, specify the user name and password that
33+
you configured for your registry.
34+
35+
. Make a copy of your pull secret in JSON format:
36+
+
37+
----
38+
$ cat ./pull-secret.text | jq . > <path>/<pull-secret-file><1>
39+
----
40+
<1> Specify the path to the folder to store the pull secret in and a name for
41+
the JSON file that you create.
42+
+
43+
The contents of the file resemble the following example:
44+
+
45+
----
46+
{
47+
"auths": {
48+
"cloud.openshift.com": {
49+
"auth": "b3BlbnNo...",
50+
"email": "you@example.com"
51+
},
52+
"quay.io": {
53+
"auth": "b3BlbnNo...",
54+
"email": "you@example.com"
55+
},
56+
"registry.connect.redhat.com": {
57+
"auth": "NTE3Njg5Nj...",
58+
"email": "you@example.com"
59+
},
60+
"registry.redhat.io": {
61+
"auth": "NTE3Njg5Nj...",
62+
"email": "you@example.com"
63+
}
64+
}
65+
}
66+
----
67+
68+
. Edit the new file and add a section that describes your registry to it:
69+
+
70+
----
71+
"auths": {
72+
...
73+
"<local_registry_host_name>:<local_registry_host_port>": { <1>
74+
"auth": "<credentials>", <2>
75+
"email": "you@example.com"
76+
},
77+
...
78+
----
79+
<1> For `bastion_host_name`, specify the registry domain name
80+
that you specified in your certificate, and for `<local_registry_host_port>`,
81+
specify the port that your mirror registry uses to serve content.
82+
<2> For `<credentials>`, specify the base64-encoded user name and password for
83+
the mirror registry that you generated.
84+
+
85+
The file resembles the following example:
86+
+
87+
----
88+
{
89+
"auths": {
90+
"cloud.openshift.com": {
91+
"auth": "b3BlbnNo...",
92+
"email": "you@example.com"
93+
},
94+
"quay.io": {
95+
"auth": "b3BlbnNo...",
96+
"email": "you@example.com"
97+
},
98+
"registry.connect.redhat.com": {
99+
"auth": "NTE3Njg5Nj...",
100+
"email": "you@example.com"
101+
},
102+
"<local_registry_host_name>:<local_registry_host_port>": {
103+
"auth": "<credentials>",
104+
"email": "you@example.com"
105+
},
106+
"registry.redhat.io": {
107+
"auth": "NTE3Njg5Nj...",
108+
"email": "you@example.com"
109+
}
110+
}
111+
}
112+
----

‎modules/installation-creating-mirror-registry.adoc‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc
4+
5+
ifeval::["{context}" == "installing-restricted-networks-preparations"]
6+
:restricted:
7+
endif::[]
8+
9+
[id="installation-creating-mirror-registry_{context}"]
10+
= Creating a mirror registry
11+
12+
Create a registry to host the mirrored content that you require for installing
13+
{product-title}.
14+
ifdef::restricted[]
15+
For installation in a restricted network, you must place the mirror on your
16+
bastion host.
17+
endif::restricted[]
18+
19+
[NOTE]
20+
====
21+
The following procedure creates a simple registry that stores data in the
22+
`/opt/registry` folder and runs in a `podman` container. You can use a different
23+
registry solution, such as
24+
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].
25+
Review the following procedure to ensure that your registry functions
26+
correctly.
27+
====
28+
29+
.Prerequisites
30+
31+
* You have a Red Hat Enterprise Linux (RHEL) server on your network to use
32+
as the registry host.
33+
* The registry host can access the internet.
34+
35+
.Procedure
36+
37+
ifdef::restricted[]
38+
On the bastion host, take the following actions:
39+
endif::restricted[]
40+
41+
. Install the required packages:
42+
+
43+
----
44+
# yum -y install podman httpd httpd-tools jq
45+
----
46+
+
47+
The `podman` package provides the container package that you run the registry
48+
in. The `httpd` and `httpd-tools` packages provide the `htpasswd` utility, which
49+
you use to create users. The `jq` package improves the display of JSON output
50+
on your command line.
51+
52+
. Create folders for the registry:
53+
+
54+
----
55+
# mkdir -p /opt/registry/{auth,certs,data}
56+
----
57+
+
58+
These folders are mounted inside the registry container.
59+
60+
. Provide a certificate for the registry. If you do not have an existing, trusted
61+
certificate authority, you can generate a self-signed certificate:
62+
+
63+
----
64+
$ cd /opt/registry/certs
65+
# openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt
66+
----
67+
+
68+
At the prompts, provide the required values for the certificate:
69+
[horizontal]
70+
Country Name (2 letter code):: Specify the two-letter ISO country code for your location.
71+
See the link:https://www.iso.org/iso-3166-country-codes.html[ISO 3166 country codes]
72+
standard.
73+
State or Province Name (full name):: Enter the full name of your state or province.
74+
Locality Name (eg, city):: Enter the name of your city.
75+
Organization Name (eg, company):: Enter your company name.
76+
Organizational Unit Name (eg, section):: Enter your department name.
77+
Common Name (eg, your name or your server's hostname):: Enter the host name for
78+
the registry host. Ensure that your hostname is in DNS and that it resolves to
79+
the expected IP address.
80+
Email Address:: Enter your email address.
81+
For more information, see the
82+
link:https://www.openssl.org/docs/man1.1.1/man1/req.html[req] description in the
83+
OpenSSL documentation.
84+
85+
. Generate a user name and a password for your registry that uses the `bcrpt` format:
86+
+
87+
----
88+
# htpasswd -bBc /opt/registry/auth/htpasswd <user_name> <password> <1>
89+
----
90+
<1> Replace `<user_name>` and `<password>` with a user name and a password.
91+
92+
. Create the `mirror-registry` container to host your registry:
93+
+
94+
----
95+
# podman run --name mirror-registry -p 5000:<local_registry_host_port> \ <1>
96+
-v /opt/registry/data:/var/lib/registry:z \
97+
-v /opt/registry/auth:/auth:z \
98+
-e "REGISTRY_AUTH=htpasswd" \
99+
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
100+
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
101+
-v /opt/registry/certs:/certs:z \
102+
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
103+
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
104+
docker.io/library/registry:2
105+
----
106+
<1> For `<local_registry_host_port>`, specify the port that your mirror registry
107+
uses to serve content.
108+
109+
. Open the required ports for your registry:
110+
+
111+
----
112+
# firewall-cmd --add-port=<local_registry_host_port>/tcp --zone=internal --permanent <1>
113+
# firewall-cmd --add-port=<local_registry_host_port>/tcp --zone=public --permanent <1>
114+
# firewall-cmd --reload
115+
----
116+
<1> For `<local_registry_host_port>`, specify the port that your mirror registry
117+
uses to serve content.
118+
119+
. Add the self-signed certificate to your list of trusted certificates:
120+
+
121+
----
122+
# cp /opt/registry/certs/domain.crt /etc/pki/ca-trust/source/anchors/
123+
# update-ca-trust
124+
----
125+
+
126+
You must trust your certificate to log in to your registry during the mirror process.
127+
128+
. Confirm that the registry is available:
129+
+
130+
----
131+
$ curl -u <user_name>:<password> -k https://<local_registry_host_name>:<local_registry_host_port>/v2/_catalog <1>
132+
133+
{"repositories":[]}
134+
----
135+
<1> For `<user_name>` and `<password>`, specify the user name and password
136+
for your registry. For `<local_registry_host_name>`, specify the registry domain name
137+
that you specified in your certificate, such as `registry.example.com`. For
138+
`<local_registry_host_port>`, specify the port that your mirror registry uses to
139+
serve content.
140+
+
141+
If the command output displays an empty repository, your registry is available.
142+
143+
////
144+
. To stop the registry::
145+
+
146+
----
147+
# podman stop mirror-registry
148+
----
149+
////

0 commit comments

Comments
 (0)