Skip to content

Commit

Permalink
improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@johnsimcall
johnsimcall committed May 5, 2024
1 parent d8b9253 commit 93ad4a9
Show file tree
Hide file tree
Showing 6 changed files with 292 additions and 139 deletions.
Binary file modified content/modules/ROOT/assets/images/disconnected-operator-catalog.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 5 additions & 4 deletions content/modules/ROOT/pages/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Before we begin let's consider a few use-cases for disconnected networks:

The diagram below illustrates the various networks, systems, and connections this workshop provides.
The diagram will be simplifed and explained in more detail later.
The workshop instructions will help you prepare the [.lowside]#jump system# to download the installation content, setup the [.highside]#highside system# to host the content, and create an [.highside]#openshift.disco.lab cluster# -- which doesn't exist yet.
The workshop instructions will help you prepare the [.lowside]#jump system# to download the installation content, setup the [.highside]#highside system# to serve the content, and create an [.highside]#openshift.disco.lab cluster# -- which doesn't exist yet.

The [.salsa]#salsa network# and its systems were built automatically when the workshop environment was created.
You can log into the [.salsa]#salsa systems# to compare your systems with functional disconnected systems.
Expand All @@ -41,7 +41,8 @@ image::disco-4.svg[disco diagram,800]

=== Lab Access and Documentation notes

The terminal window to your right is *already* logged in to the [.lowside]#jump system's# *SSH Terminal*.
[%hardbreaks]
The terminal to your right is already logged in to the [.lowside]#jump system's# *SSH Terminal*.
The right-hand side of this browser can also show the [.lowside]#jump system's# graphical desktop by clicking on the *Desktop* button.

The lab instructions should be run as the user named `{bastion_ssh_user_name}`.
Expand Down Expand Up @@ -72,8 +73,8 @@ Using **Ctrl + Insert** (copy) and **Shift + Insert** (paste) also works.

[NOTE]
--
The workshop labs intentionally avoid asking you to use `vi`, `nano`, or `emacs` to edit text files.
The authors of workshop want you to focus on the material instead of the strange incantations required to save and quit out of `vi` and `nano`.
The workshop instructions intentionally avoid asking you to use `vi`, `nano`, or `emacs` to edit text files.
The authors of the workshop want you to focus on the material instead of the strange incantations required to save and quit out of `vi`, `nano` or `emacs`.
--

=== Alternate connection methods
Expand Down
29 changes: 19 additions & 10 deletions content/modules/ROOT/pages/lab02.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ You can refer to the https://docs.openshift.com/container-platform/{openshift_ve
** Install the `mirror-registry`
** Use `oc-mirror` to populate the `mirror-registry`

{counter:steps}. Tell the OpenShift installation program (`openshift-install`) where to find the installation images
{counter:steps}. Tell the OpenShift Installer (`openshift-install`) where to find the installation images

** Make a few changes to the default `install-config.yaml` file
*** Add credentials (`pull secret`) for the `mirror-registry`
Expand All @@ -34,7 +34,7 @@ You can refer to the https://docs.openshift.com/container-platform/{openshift_ve
Now that we know the procedure, let's start with **Step 1 - Preparing the [.lowside]#jump system#**

== Preparing the `jump system`
== Preparing the jump system

The [.lowside]#jump system# lives in the [.lowside]#lowside network# which allows it to download the mirroring tools and installation images.
The network is called [.lowside]#lowside# because it has a low security profile, and shouldn't be used to store sensitive information.
Expand Down Expand Up @@ -138,7 +138,7 @@ tar -xzf openshift-install.tar.gz openshift-install
rm -f openshift-install.tar.gz
----

== Mirroring the OpenShift installation images
=== Mirroring the OpenShift installation images

Now that the mirroring and installation tools have been downloaded and extracted, it's time to put `oc-mirror` to work! Let's start with a brief overview of using `oc-mirror`:

Expand All @@ -149,8 +149,8 @@ Now that the mirroring and installation tools have been downloaded and extracted
{counter:mirror}. Create an `ImageSetConfiguration` YAML file that describes:

** What to download (OpenShift itself, an Operator, and an image)
** What versions (e.g. everything between {openshift_min_version} and {openshift_max_version})
** Where to store the download content
** What versions (e.g. everything between `{openshift_min_version}` and `{openshift_max_version}`)
** Where to store the downloaded content

{counter:mirror}. Run `oc-mirror` with the YAML file

Expand Down Expand Up @@ -191,7 +191,8 @@ Create a file called `imageset-config.yaml` with the following contents:

[.lowside,source,yaml,subs="attributes",role=execute]
----
cat << EOF > imageset-config.yaml
cat << EOF > /mnt/low-side-data/imageset-config.yaml
---
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v1alpha2
storageConfig:
Expand Down Expand Up @@ -252,8 +253,8 @@ tmux
[0] 0:bash* "ip-10-0-6-23.us-west-" 07:21 01-May-24
Welcome to tmux - press [Ctrl + b then d] to Disconnect or press [Ctrl + b then h] for additional Help
Mouse mode has been turned on. Click to select your window/pane. Resize works too. Hold shift when selecting text.
Welcome to tmux - press [Ctrl + b then d] to Disconnect or press [Ctrl + b then h] for additional Help
Mouse mode has been turned on. Click to select your window/pane. Resize works too. Hold shift when selecting text.
----

[TIP]
Expand All @@ -272,8 +273,16 @@ oc-mirror --config imageset-config.yaml file:///mnt/low-side-data
----
[.output]
----
...
info: Mirroring completed in 2m52.23s (131.9MB/s)
Logging to .oc-mirror.log
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/publish
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/v2
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/charts
Creating directory: /mnt/low-side-data/oc-mirror-workspace/src/release-signatures
No metadata detected, creating new workspace
... a long, uncomfortable pause ...
info: Mirroring completed
Creating archive /mnt/low-side-data/mirror_seq1_000000.tar
----

Expand Down
69 changes: 47 additions & 22 deletions content/modules/ROOT/pages/lab03.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Installing the `mirror-registry` takes ~8 minutes.
The `oc-mirror` download that began in the last section takes ~15 minutes.

We will demonstrate that the [.highside]#highside# system is disconnected while we wait for the download to complete.
Then we will end this section by transferring the 25GB of OpenShift installation images across the 🍃 air gap 🍃 and into the disconnected `mirror-registry`.
Then we will end this section by transferring the ~25GB of OpenShift installation images across the 🍃 air gap 🍃 and into the disconnected `mirror-registry`.

== Creating a Mirror Registry

Expand Down Expand Up @@ -70,7 +70,7 @@ In the real world, customers often access their disconnected systems using a VPN
In your workshop environment, an exception was created in the firewall that allows (only) the [.lowside]#jump# system to SSH to the [.highside]#highside# system.

Password-less SSH has been enabled for your convenience.
Please log into the [.highside]#highside# system using `ssh` from the [.lowside]#jump# system.
Please log in to the [.highside]#highside# system using `ssh` from the [.lowside]#jump# system.

[.lowside,source,bash,role=execute,subs="attributes"]
----
Expand Down Expand Up @@ -110,8 +110,8 @@ The only option that we will provide is one to set the password for the `init` u
[.output]
----
...
INFO[2023-07-06 15:43:41] Quay installed successfully, config data is stored in /home/lab-user/quay-install
INFO[2023-07-06 15:43:41] Quay is available at https://ip-10-0-51-47.ec2.internal:8443 with credentials (init, discopass)
INFO[2024-05-04 15:43:41] Quay installed successfully, config data is stored in /home/lab-user/quay-install
INFO[2024-05-04 15:43:41] Quay is available at https://ip-10-0-51-47.ec2.internal:8443 with credentials (init, discopass)
----

[NOTE]
Expand All @@ -121,13 +121,13 @@ We can't move on to the next step of trusting the TLS certificate until the `mir

=== Trusting the `mirror-registry's` TLS certificate

The `mirror-registry` installer creates a TLS certificate that is not trusted by anything, not even the [.highside]#highside# system where it was installed.
The `mirror-registry` installer creates its own TLS certificate that is not trusted by anything, not even the [.highside]#highside# system where it was installed.
The `mirror-registry` allows users to provide their own certificate, if they were issued one by somebody they trust, using the `--sslCert` option.

The procedure to trust the `mirror-registry's` self-signed TLS certificate is simple.

[%hardbreaks]
Copy the Certificate Authority file (`rootCA.pem`) into the Red Hat Enterprise Linux CA trust directory.
Copy the Certificate Authority file (`rootCA.pem`) that was created by the `mirror-registry` automation in to the Red Hat Enterprise Linux CA trust directory.
Then run the `update-ca-trust` command.

[.highside,source,bash,role=execute]
Expand All @@ -153,10 +153,13 @@ Login Succeeded!

The `podman login` command creates an authentication file / __pull secret__ at `/run/user/1000/containers/auth.json`.

Note that the `oc-mirror` command looks for _pull secrets_ in multiple locations:
[NOTE]
--
The `oc-mirror` command looks for _pull secrets_ in multiple locations:

* `$HOME/.docker/config.json` (created on the [.lowside]#lowside jump# system)
* `$XDG_RUNTIME_DIR/containers/auth.json` (created on the [.highside]#highside# system)
--

== Transfer the installation content [[rsync-content]]

Expand All @@ -165,7 +168,7 @@ Make sure that your `oc-mirror` command has completed successfully before procee
If `oc-mirror` is still downloading the OpenShift installation images, please jump forward to <<prove-disconnected>>.
But don't forget to come back!

You can confirm the download finished by looking in your `tmux` pane to see if your [.underline]#prompt has returned#, and that the `.tar` archive was created.
You can confirm the download finished by looking in your `tmux` pane to see if your [.underline]#prompt has returned#, and that the `.tar` archive file was created.

[.output]
----
Expand All @@ -190,8 +193,17 @@ rsync -avP /mnt/low-side-data/ highside:/mnt/high-side-data/
----
[.output]
----
[lab-user@jump ~]$ rsync -avP /mnt/low-side-data/ highside:/mnt/high-side-data/
...
sending incremental file list
./
.oc-mirror.log
186,850 100% 146.94MB/s 0:00:00 (xfr#1, to-chk=124/126)
imageset-config.yaml
469 100% 458.01kB/s 0:00:00 (xfr#2, to-chk=123/126)
mirror_seq1_000000.tar
22,931,079,168 92% 125.16MB/s 0:00:15 (xfr#2, to-chk=122/126)
... a long, but amazing, transfer ...
publish/
publish/.metadata.json
332,183 100% 332.37kB/s 0:00:00 (xfr#66, to-chk=0/127)
Expand All @@ -202,7 +214,7 @@ total size is 30,788,095,434 speedup is 1.00

== Prove that highside is disconnected [[prove-disconnected]]

Looking at the workshop environment diagram, we can see how the [.highside]#highside# system is disconnected.
Looking at the workshop environment diagram, you can see how the [.highside]#highside# system is disconnected.
The [.highside]#highside network# doesn't provide any direct route to the internet.

[NOTE]
Expand All @@ -229,7 +241,7 @@ You may recall that:

If you try to access a **blocked website**, like [.underline]#quay.io#, you will see an **Access Denied** message like this.

[.highside,source,bash,role=execute]
[.highside,source,bash,role=execute,subs="attributes"]
----
curl -I quay.io
----
Expand All @@ -243,7 +255,7 @@ X-Squid-Error: ERR_ACCESS_DENIED 0

If you try to access an **allowed website**, like the Red Hat Update Infrastructure (RHUI) repos inside the Amazon AWS Cloud, you will see a message like this.

[.highside,source,bash,role=execute]
[.highside,source,bash,role=execute,subs="attributes"]
----
curl -I https://rhui.{aws_default_region}.aws.ce.redhat.com
----
Expand All @@ -256,25 +268,29 @@ Date: Mon, 29 Apr 2024 20:15:51 GMT

If you skipped ahead to prove that the [.highside]#highside systems# are really disconnected while the `oc-mirror` download was still working, it's time to go back to <<rsync-content>>.

== Upload OpenShift's installation images into the `mirror-registry`
== Upload OpenShift's installation images into the mirror-registry

Now that the [.highside]#highside# system has: a) received the installation images, b) trusts the `mirror-registry's` TLS certificate, and c) `podman` has logged in and created a new _pull secret_, you are ready to upload the installation images.
Now that the [.highside]#highside# system has: **a**) received the installation images, **b**) trusts the `mirror-registry's` TLS certificate, and **c**) `podman` has logged in and created a new _pull secret_, you are ready to upload the installation images.

We'll begin by adding the `oc`, `oc-mirror` and `openshift-install` commands to the PATH.

[TIP]
Make sure you are using the `tmux` pane that is logged in to the [.highside]#highside# system.

[.highside,source,bash,role=execute]
----
sudo mv -v /mnt/high-side-data/oc /bin/
sudo mv -v /mnt/high-side-data/oc-mirror /bin/
sudo mv -v /mnt/high-side-data/openshift-install /bin/
----

[WARNING]
--
Please run the next `oc-mirror` command in your `tmux` screen.
This will allow you to keep working on the next section while `oc-mirror` uploads ~25 GB of data into the `mirror-registry`.
The `oc-mirror` task should complete in about 15 minutes.
--
With the mirroring tools installed and configured, it is now time to run `oc-mirror` again, this time on the [.highside]#highside# system, to __upload__ the installation images in to the `mirror-registry`.
The __upload__ process takes ~15 minutes in this workshop environment.

[NOTE]
`oc-mirror` will create several __results files__ in the directory where it was ran.

Please change directories to `/mnt/high-side-data`, and use the `tmux` pane that is logged in to the [.highside]#highside# system to run the next command.

[.highside,source,bash,role=execute]
----
Expand All @@ -283,7 +299,16 @@ oc-mirror --from=/mnt/high-side-data/mirror_seq1_000000.tar docker://$(hostname)
----
[.output]
----
...
Logging to .oc-mirror.log
Checking push permissions for ip-10-0-54-198.us-west-2.compute.internal:8443
Publishing image set from archive "/mnt/high-side-data/mirror_seq1_000000.tar" to registry "ip-10-0-54-198.us-west-2.compute.internal:8443"
ip-10-0-54-198.us-west-2.compute.internal:8443/
openshift/release
blobs:
file://openshift/release sha256:d8190195889efb5333eeec18af9b6c82313edd4db62989bd3a357caca4f13f0e 1.404KiB
file://openshift/release sha256:cd8c26ed660bfc4447a17563df1dc5374f1cbd2ced1d7ae0af135fabaff1f7d2 17.86KiB
... a long, mind-expanding, upload ...
info: Mirroring completed in 18m10.33s (39.33MB/s)
Rendering catalog image "ip-10-0-8-121.us-west-2.compute.internal:8443/redhat/redhat-operator-index:v4.14" with file-based catalog
Expand Down
Loading

0 comments on commit 93ad4a9

Please sign in to comment.